Marionette JavaScript Tests

  • Revision slug: Marionette/Marionette_JavaScript_Tests
  • Revision title: Marionette JavaScript Tests
  • Revision id: 4398
  • Created:
  • Creator: philikon
  • Is current revision? No
  • Comment one or more formatting changes

Revision Content

Marionette supports tests written in JavaScript.  These tests must have a filename that begins with "test_" or "browser_" and must have the extension ".js".

Test Structure

Test files beginning with "test_"

All Marionette JavaScript tests are asynchronous, and will not complete until the test calls finish().  When finish() is called, the framework collects information about all the assertions made during the test and sends it to the Marionette test driver, which will report the results.  For example:

// test logic (possibly asynchronous) goes here...
finish();

Test files beginning with "browser_"

Tests beginning with "browser_" have additional structural requirements.  These tests can be run either by the mochitest-browser-chrome framework, or by Marionette.  These tests must have a test() function, which the framework calls to start the test.  These tests must call finish() to end the test, as described above.  For example:

function test() {
   // test logic (possibly asynchronous) goes here...
   finish();
}

Test Flags

Marionette JavaScript tests can utilize flags to direct Marionette to perform certain actions.

Flag Type Description
MARIONETTE_TIMEOUT integer The maximum number of seconds a test can wait for finish() to be called, before timing out.
MARIONETTE_CONTEXT string Either "content" or "chrome"; the context in which the test will be executed in.  Defaults to "content".

All flags are specified as JavaScript variable assignments inside the test file.  For example:

MARIONETTE_TIMEOUT = 30000; // 30s timeout
MARIONETTE_CONTEXT = "chrome"; // execute test in chrome context
// test logic (possibly asynchronous) goes here...
finish();

Test Functions

All JavaScript tests have a number of functions available to them.

void is(value1, value2, message)
void isnot(value1, value2, message)
void ok(value, message)
void finish()
void log(message, level)
void waitFor(callback, test, timeout)
void runEmulatorCmd(cmd, callback)

is(value1, value2, message)

Asserts that two values are equivalent.  A failure of an assertion will cause the test to fail with the given message.

isnot(value1, value2, message)

Asserts that two values are not equivalent.  A failure of an assertion will cause the test to fail with the given message.

ok(value, message)

Asserts that a value is true.  A failure of an assertion will cause the test to fail with the given message.

finish()

Ends the test.

log(message, level)

Causes the specified message to be logged at the specified level.  Levels are arbitrary strings; defaults to "INFO".

waitFor(callback, test, timeout)

Repeatedly calls the function passed as the test parameter until that function returns true, then calls the callback.  If the test function does not return true within timeout ms, an exception is thrown.  The timeout parameter can be omitted, in which case a system default timeout is used.

runEmulatorCmd(cmd, callback)

Send the specified command string to the emulator's control port. The optional callback is invoked with an array containing the result lines of the command's output. Please refer to the Android Emulator documentation for the list of commands.

Revision Source

<p>Marionette supports tests written in JavaScript.  These tests must have a filename that begins with "test_" or "browser_" and must have the extension ".js".</p>
<h3 id="Test_Structure">Test Structure</h3>
<h4 id='Test_files_beginning_with_"test_"'>Test files beginning with "test_"</h4>
<p>All Marionette JavaScript tests are asynchronous, and will not complete until the test calls <code>finish()</code>.  When <code>finish()</code> is called, the framework collects information about all the assertions made during the test and sends it to the Marionette test driver, which will report the results.  For example:</p>
<pre class="brush: js">// test logic (possibly asynchronous) goes here...
finish();
</pre>
<h4 id='Test_files_beginning_with_"browser_"'>Test files beginning with "browser_"</h4>
<p>Tests beginning with "browser_" have additional structural requirements.  These tests can be run either by the mochitest-browser-chrome framework, or by Marionette.  These tests must have a <code>test()</code> function, which the framework calls to start the test.  These tests must call <code>finish()</code> to end the test, as described above.  For example:</p>
<pre class="brush: js">function test() {
   // test logic (possibly asynchronous) goes here...
   finish();
}
</pre>
<h3 id="Test_Flags">Test Flags</h3>
<p>Marionette JavaScript tests can utilize flags to direct Marionette to perform certain actions.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Flag</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>MARIONETTE_TIMEOUT</code></td> <td>integer</td> <td>The maximum number of seconds a test can wait for <code>finish()</code> to be called, before timing out.</td> </tr> <tr> <td><code>MARIONETTE_CONTEXT</code></td> <td>string</td> <td>Either "content" or "chrome"; the context in which the test will be executed in.  Defaults to "content".</td> </tr> </tbody>
</table>
<p>All flags are specified as JavaScript variable assignments inside the test file.  For example:</p>
<pre class="brush: js">MARIONETTE_TIMEOUT = 30000; // 30s timeout
MARIONETTE_CONTEXT = "chrome"; // execute test in chrome context
// test logic (possibly asynchronous) goes here...
finish();
</pre>
<h3 id="Test_Functions">Test Functions</h3>
<p>All JavaScript tests have a number of functions available to them.</p>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#is()" title="en/Marionette/Marionette_JavaScript_Tests#is()">is(value1, value2, message)</a></code></td> </tr> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#isnot()" title="en/Marionette/Marionette_JavaScript_Tests#isnot()">isnot(value1, value2, message)</a></code></td> </tr> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#ok()" title="en/Marionette/Marionette_JavaScript_Tests#ok()">ok(value, message)</a></code></td> </tr> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#finish()" title="en/Marionette/Marionette_JavaScript_Tests#finish()">finish()</a></code></td> </tr> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#log()" title="en/Marionette/Marionette_JavaScript_Tests#log()">log(message, level)</a></code></td> </tr> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#waitFor()" title="en/Marionette/Marionette_JavaScript_Tests#waitFor()">waitFor(callback, test, timeout)</a></code></td> </tr> <tr> <td><code>void <a href="/en/Marionette/Marionette_JavaScript_Tests#runEmulatorCmd()" title="en/Marionette/Marionette_JavaScript_Tests#runEmulatorCmd()">runEmulatorCmd(cmd, callback)</a></code></td> </tr> </tbody>
</table>
<h4 id="is()" name="is()">is(value1, value2, message)</h4>
<p>Asserts that two values are equivalent.  A failure of an assertion will cause the test to fail with the given message.</p>
<h4 id="isnot()" name="isnot()">isnot(value1, value2, message)</h4>
<p>Asserts that two values are not equivalent.  A failure of an assertion will cause the test to fail with the given message.</p>
<h4 id="ok()" name="ok()">ok(value, message)</h4>
<p>Asserts that a value is true.  A failure of an assertion will cause the test to fail with the given message.</p>
<h4 id="finish()" name="finish()">finish()</h4>
<p>Ends the test.</p>
<h4 id="log()" name="log()">log(message, level)</h4>
<p>Causes the specified message to be logged at the specified level.  Levels are arbitrary strings; defaults to "INFO".</p>
<h4 id="waitFor()" name="waitFor()">waitFor(callback, test, timeout)</h4>
<p>Repeatedly calls the function passed as the <code>test </code>parameter until that function returns true, then calls the <code>callback</code>.  If the <code>test </code>function does not return true within <code>timeout </code>ms, an exception is thrown.  The <code>timeout </code>parameter can be omitted, in which case a system default timeout is used.</p>
<h4 id="runEmulatorCmd()" name="runEmulatorCmd()">runEmulatorCmd(cmd, callback)</h4>
<p>Send the specified command string to the emulator's control port. The optional callback is invoked with an array containing the result lines of the command's output. Please refer to the <a class="external" href="http://developer.android.com/tools/devices/emulator.html#console" title="http://developer.android.com/tools/devices/emulator.html#console">Android Emulator documentation</a> for the list of commands.</p>
Revert to this revision