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 and run the command:
./mach mochitest -f chrome
To run a single test, just pass the path to the test into mach:
./mach mochitest -f chrome toolkit/content/tests/chrome/test_largemenu.xul
You can also pass the path to a directory containing many tests. Run mach help mochitest for full documentation.
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="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
onload="RunTest();">
<title>Demo Test</title>
<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="https://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".
Helper files can be included, for example, from https://example.com/chrome/dom/workers/test/serviceworkers/serviceworkermanager_iframe.html.
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 and use a manifest named chrome.ini instead of mochitest.ini.