Marionette JavaScript Tests

  • Revision slug: Marionette/Marionette_JavaScript_Tests
  • Revision title: Marionette JavaScript Tests
  • Revision id: 458901
  • Created:
  • Creator: jgriffin
  • Is current revision? No
  • Comment

Revision Content

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

Test Structure

All Marionette JavaScript WebAPI 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();

For examples, see the tests under dom/telephony/tests/marionette.

Test Flags

Marionette JavaScript WebAPI 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 WebAPI 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)
Array getLogs()
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".

getLogs()

Returns all the logs so far as an array, and clears the log.

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 WebAPI tests written in JavaScript.&nbsp; These tests must have a filename that begins with "test_" and must have the extension ".js".</p>
<h3 id="Test_Structure">Test Structure</h3>
<p>All Marionette JavaScript WebAPI tests are asynchronous, and will not complete until the test calls <code>finish()</code>.&nbsp; 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.&nbsp; For example:</p>
<pre class="brush: js">
// test logic (possibly asynchronous) goes here...
finish();
</pre>
<p>For examples, see the tests under <a href="http://mxr.mozilla.org/mozilla-central/source/dom/telephony/test/marionette/" title="http://mxr.mozilla.org/mozilla-central/source/dom/telephony/test/marionette/">dom/telephony/tests/marionette</a>.</p>
<h3 id="Test_Flags">Test Flags</h3>
<p>Marionette JavaScript WebAPI 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.&nbsp; Defaults to "content".</td>
    </tr>
  </tbody>
</table>
<p>All flags are specified as JavaScript variable assignments inside the test file.&nbsp; 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 WebAPI 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>Array <a href="/en/Marionette/Marionette_JavaScript_Tests#getLogs()" title="/en/Marionette/Marionette_JavaScript_Tests#getLogs()">getLogs()</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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; Levels are arbitrary strings; defaults to "INFO".</p>
<h4 id="log()" name="log()">getLogs()</h4>
<p>Returns all the logs so far as an array, and clears the log.</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>.&nbsp; If the <code>test </code>function does not return true within <code>timeout </code>ms, an exception is thrown.&nbsp; 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