mozilla

Revision 286645 of Chrome tests

  • Revision slug: Chrome_tests
  • Revision title: Chrome tests
  • Revision id: 286645
  • Created:
  • Creator: gfritzsche
  • Is current revision? No
  • Comment update for toolkit versions >=1.9.1; 95 words added, 22 words removed

Revision Content

 

Introduction

A chrome test is basically a Mochitest running with chrome privileges.

The chrome test suite is an automated testing framework designed to allow testing of application chrome windows using JavaScript. It currently allows you to run JavaScript code in the same scope as the main Firefox browser window with chrome privileges and reports results using the same functions as the Mochitest test framework. The chrome test suite depends on runtests.py from the Mochitest framework.

Running the chrome tests

To run Mochitest you need to build Mozilla with your changes, change directory to, and run the command (1.9.1 and later):

make -C $(OBJDIR) mochitest-chrome

To test on older branches, run Mochitest's runtests.py script without passing it any command line arguments:

cd $(OBJDIR)/_tests/testing/mochitest
python runtests.py --chrome

This will launch your build and open a "chrome tests" window. The "run all tests" link will start the test run, and report the results in the UI. There's also an option to output the results to file, using the same command line parameter used by Mochitest (--log-file=/path/to/file). (Logging doesn't work yet, see {{ Bug(423497) }}.)

You can tell the test harness to run the tests automatically at startup without user interaction by passing the --autorun parameter. This can be used in combination with the --close-when-done parameter to fully automate the tests.

To run single tests on 1.9.1 use TEST_PATH, e.g.:

TEST_PATH=toolkit/content/tests/chrome/test_largemenu.xul make -C $(OBJDIR) mochitest-chrome

will just run the test_largemenu.xul. On older branches you can run single tests by passing its path to the --test-path parameter:

python runtests.py --chrome --test-path=toolkit/content/tests/chrome/test_largemenu.xul

Run a tests for a specific directory on 1.9.1 automatically with:

TEST_PATH=toolkit/mymodule/tests/chrome/ make -C $(OBJDIR) mochitest-chrome

Writing chrome tests

A chrome tests is basically a Mochitest running with chrome privileges, i.e. code and UI are referenced by chrome:// URIs. A basic XUL test file could look like this:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin" type="text/css"?>
<?xml-stylesheet href="chrome://mochikit/content/tests/SimpleTest/test.css" type="text/css"?>

<window title="Demo Test"
        xmlns="http://www.mozilla.org/keymaster/gat...re.is.only.xul"
        onload="RunTest();">
  <title>Demo Test</title>

  <script type="application/javascript"
          src="chrome://mochikit/content/tests/Simp.../SimpleTest.js"/>

  <script type="application/javascript">
  <![CDATA[
    SimpleTest.waitForExplicitFinish();

    function RunTest()
    {
      ok  (true ==  1, "this passes");
      todo(true === 1, "this fails");
      SimpleTest.finish();
    }
  ]]>
  </script>

  <body xmlns="http://www.w3.org/1999/xhtml">
    <p id="display"></p>
    <div id="content" style="display: none"></div>
    <pre id="test"></pre>
  </body>
</window>

The "RunTest" function is invoked by the test's onload handler, not by the test harness.

The comparison functions are identical to those supported by Mochitests, see how the comparison functions work in the Mochitest documentation for more details. The EventUtils helper functions are available on the "EventUtils" object defined in the global scope.

The test suite also supports asynchronous tests, using the same function names as Mochitest. Call SimpleTest.waitForExplicitFinish() if you want to delay reporting a result until after RunTest() has returned. Call SimpleTest.finish() once the test is complete. Be aware that the test harness will mark tests that take too long to complete as FAILED (the current timeout is 15 seconds).

Any exceptions thrown while running a test will be caught and reported in the test output as a failure. Exceptions thrown outside of the test's context (e.g. in a timeout, event handler, etc) will not be caught, but will result in a timed out test if they prevent finish() from being called.

The test file name must be prefixed with "test_", and must have a file extension of ".xul". Files that don't match this pattern will be ignored by the test harness, but you still can include them. For example, a XUL window file opened by your test_demo.xul via openDialog should be named window_demo.xul. Putting the bug number in the file name is recommended if your test verifies a bugfix, e.g. "test_bug123456.xul".

Adding a new chrome test to the tree

To add a new chrome test to the tree, follow the Mochitest instructions, keeping in mind that the chrome tests must be copied into _tests/testing/mochitest/chrome instead of _tests/testing/mochitest/mochitest.

{{ languages( { "ja": "ja/Chrome_tests" } ) }}

Revision Source

<p> </p>
<h3 id="Introduction" name="Introduction">Introduction</h3>
<p>A chrome test is basically a <a href="/en/Mochitest" title="en/Mochitest">Mochitest</a> running with chrome privileges.</p>
<p>The chrome test suite is an automated testing framework designed to allow testing of application chrome windows using JavaScript. It currently allows you to run JavaScript code in the same scope as the main Firefox browser window with chrome privileges and reports results using the same functions as the <a href="/en/Mochitest" title="en/Mochitest">Mochitest test framework</a>. The chrome test suite depends on runtests.py from the Mochitest framework.</p>
<h3 id="Running_the_chrome_tests" name="Running_the_chrome_tests">Running the chrome tests</h3>
<p>To run Mochitest you need to <a href="/En/Developer_Guide/Build_Instructions" title="en/Build_Documentation">build Mozilla</a> with your changes, change directory to, and run the command (1.9.1 and later):</p>
<pre>make -C $(OBJDIR) mochitest-chrome
</pre>
<p>To test on older branches, run Mochitest's runtests.py script without passing it any command line arguments:</p>
<pre class="eval">cd <code>$(OBJDIR)/_tests/testing/mochitest</code>
python runtests.py --chrome
</pre>
<p>This will launch your build and open a "chrome tests" window. The "run all tests" link will start the test run, and report the results in the UI. There's also an option to output the results to file, using the same command line parameter used by Mochitest (--log-file=/path/to/file). <em>(Logging doesn't work yet, see {{ Bug(423497) }}.)</em></p>
<p>You can tell the test harness to run the tests automatically at startup without user interaction by passing the <code>--autorun</code> parameter. This can be used in combination with the <code>--close-when-done</code> parameter to fully automate the tests.</p>
<p>To run single tests on 1.9.1 use <code>TEST_PATH</code>, e.g.:</p>
<pre>TEST_PATH=toolkit/content/tests/chrome/test_largemenu.xul make -C $(OBJDIR) mochitest-chrome
</pre>
<p>will just run the test_largemenu.xul. On older branches you can run single tests by passing its path to the --test-path parameter:</p>
<pre class="eval">python runtests.py --chrome --test-path=toolkit/content/tests/chrome/test_largemenu.xul
</pre>
<p>Run a tests for a specific directory on 1.9.1 automatically with:</p>
<pre class="eval">TEST_PATH=toolkit/mymodule/tests/chrome/ make -C <code>$(OBJDIR)</code> mochitest-chrome
</pre>
<h3 id="Writing_chrome_tests" name="Writing_chrome_tests">Writing chrome tests</h3>
<p>A chrome tests is basically a <a href="/en/Mochitest" title="en/Mochitest">Mochitest</a> running with chrome privileges, i.e. code and UI are referenced by <code>chrome://</code> URIs. A basic XUL test file could look like this:</p>
<pre class="eval">&lt;?xml version="1.0"?&gt;
&lt;?xml-stylesheet href="<a class=" external" href="chrome://global/skin" rel="freelink">chrome://global/skin</a>" type="text/css"?&gt;
&lt;?xml-stylesheet href="<a class=" external" href="chrome://mochikit/content/tests/SimpleTest/test.css" rel="freelink">chrome://mochikit/content/tests/SimpleTest/test.css</a>" type="text/css"?&gt;

&lt;window title="Demo Test"
        xmlns="<a class=" external" href="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" rel="freelink">http://www.mozilla.org/keymaster/gat...re.is.only.xul</a>"
        onload="RunTest();"&gt;
  &lt;title&gt;Demo Test&lt;/title&gt;

  &lt;script type="application/javascript"
          src="<a class=" external" href="chrome://mochikit/content/tests/SimpleTest/SimpleTest.js" rel="freelink">chrome://mochikit/content/tests/Simp.../SimpleTest.js</a>"/&gt;

  &lt;script type="application/javascript"&gt;
  &lt;![CDATA[
    SimpleTest.waitForExplicitFinish();

    function RunTest()
    {
      ok  (true ==  1, "this passes");
      todo(true === 1, "this fails");
      SimpleTest.finish();
    }
  ]]&gt;
  &lt;/script&gt;

  &lt;body xmlns="<a class=" external" href="http://www.w3.org/1999/xhtml" rel="freelink">http://www.w3.org/1999/xhtml</a>"&gt;
    &lt;p id="display"&gt;&lt;/p&gt;
    &lt;div id="content" style="display: none"&gt;&lt;/div&gt;
    &lt;pre id="test"&gt;&lt;/pre&gt;
  &lt;/body&gt;
&lt;/window&gt;
</pre>
<p>The "RunTest" function is invoked by the test's <code>onload</code> handler, not by the test harness.</p>
<p>The comparison functions are identical to those supported by Mochitests, see <a href="/en/Mochitest#How_do_the_comparison_functions_work.3F" title="en/Mochitest#How_do_the_comparison_functions_work.3F">how the comparison functions work</a> in the Mochitest documentation for more details. The <a class="external" href="http://lxr.mozilla.org/mozilla/source/testing/mochitest/tests/SimpleTest/EventUtils.js">EventUtils helper functions</a> are available on the "EventUtils" object defined in the global scope.</p>
<p>The test suite also supports asynchronous tests, using the same function names as Mochitest. Call SimpleTest.waitForExplicitFinish() if you want to delay reporting a result until after RunTest() has returned. Call SimpleTest.finish() once the test is complete. Be aware that the test harness will mark tests that take too long to complete as FAILED (the current timeout is 15 seconds).</p>
<p>Any exceptions thrown while running a test will be caught and reported in the test output as a failure. Exceptions thrown outside of the test's context (e.g. in a timeout, event handler, etc) will not be caught, but will result in a timed out test if they prevent finish() from being called.</p>
<p>The test file name must be prefixed with "test_", and must have a file extension of ".xul". Files that don't match this pattern will be ignored by the test harness, but you still can include them. For example, a XUL window file opened by your test_demo.xul via openDialog should be named window_demo.xul. Putting the bug number in the file name is recommended if your test verifies a bugfix, e.g. "test_bug123456.xul".</p>
<h3 id="Adding_a_new_chrome_test_to_the_tree" name="Adding_a_new_chrome_test_to_the_tree">Adding a new chrome test to the tree</h3>
<p>To add a new chrome test to the tree, follow the <a href="/en/Mochitest#Adding_new_Mochitest_tests_to_the_tree" title="en/Mochitest#Adding_new_Mochitest_tests_to_the_tree">Mochitest instructions</a>, keeping in mind that the chrome tests must be copied into _tests/testing/mochitest/chrome instead of _tests/testing/mochitest/mochitest.</p>
<p>{{ languages( { "ja": "ja/Chrome_tests" } ) }}</p>
Revert to this revision