Skip to main content

Visit Mozilla.org

Chrome tests

From MDC


Contents

[edit] Introduction

A chrome tests 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.pl/runtests.py from the Mochitest framework, so it won't work in a build with Mochitest disabled (--disable-mochitest).

[edit] Running the chrome tests

To run Mochitest you need to build Mozilla with your changes, change directory to $(OBJDIR)/_tests/testing/mochitest, and run the command: 

python runtests.py --chrome

(While running perl runtests.pl --chrome is currently still supported, it's deprecated in favour of runtests.py and will pass away eventually.)

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.

You can run single tests by passing its path to the --test-path parameter, e.g. 

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

will just run the test_largemenu.xul.

[edit] 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/gatekeeper/there.is.only.xul"
        onload="RunTest();">
  <title>Demo Test</title>

  <script type="application/javascript" 
          src="chrome://mochikit/content/MochiKit/packed.js"/>
  <script type="application/javascript"
          src="chrome://mochikit/content/tests/SimpleTest/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 test() (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 in your XUL file. 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".

[edit] 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.

Retrieved from "http://developer.mozilla.org/en/docs/Chrome_tests"