Metro browser chrome tests

The metro browser chrome test suite is an automated testing framework designed to allow testing of the immersive version of Firefox for Windows 8 and above using JavaScript. It currently allows you to run JavaScript code in the same scope as the immersive browser and report results using the same functions as the Mochitest test framework.

Running the metro browser chrome tests

To run Mochitest, first build Mozilla with your changes; then run

./mach mochitest-metro

This will launch metro browser chrome tests in the default immersive browser. For information on setting your local build as the default, visit the Windows 8 Integration wiki page.

It is possible to run individual tests as well. As with Mochitest, the path given as an argument is the path to a test file within the Mozilla source tree. If the path points to the root tests directory, then all metro browser chrome tests will be run.

For example, to run a specific test the command would be:

./mach mochitest-metro browser/metro/base/tests/mochitest/(testfile)

Writing browser chrome tests

Metro browser chrome tests make use of a common framework for defining and running tests. A simple test looks like this:

gTests.push({
  desc: "Test loading about:blank",
  setUp: function () { },
  tearDown: function () { },
  run: function () {
    yield addTab("about:blank");
    is(tab.browser.currentURI.spec, "about:blank", "about:blank is loaded");
  }
});

function test() {
  runTests();
}

gTests contains individual tests that make up the library of tests your test file will contain. Each test can have start up and tear down logic, plus the body of the test contained in run(). The test file can contain other functions which will be ignored unless invoked by test(). gTests make use of Promises and Tasks for managing execution.

Test comparison functions used in metro browser chrome tests are identical to those supported by Mochitests, see how the comparison functions work in the Mochitest documentation for more details.

Helper functions

The EventUtils helper functions are available on the EventUtils object defined in the global scope. Additional metro specific test helpers can be found in /browser/metro/base/tests/mochitest/head.js.

You may add additional common utils and helpers to head.js. Be careful about changing existing helpers as changes may impact tests in other libraries.

Static content for tests

Static content (html files, images, etc.) should be stored in sub directories to avoid polluting the main test directory. Sub directories for larger test suites may also be created.

Exceptions in tests

Any exceptions thrown under test() will be caught and reported as a general failure. setUp(), tearDown(), and run() each have individual exception handlers to prevent one method from interfering with the execution of another. An exception in any of these methods will cause a test failure. Additional built-in framework test checks will run after the completion of each individual test insuring tests clean up properly. For more information on test execution see the main test exectuon loop in head.js.

Adding a new browser chrome test to the tree

To add a new metro browser chrome test add the test file to the BROWSER_TESTS variable in /browser/metro/base/tests/mochitest/Makefile.in. Your test file name must be prefixed with "browser_", and must have a file extension of ".js". Files that don't match this pattern will be ignored by the test harness. Using a descriptive file name is strongly encouraged instead of just using a bug number.