Browser chrome mochitests

Browser chrome mochitests are mochitests that run in the context of the desktop Firefox browser window. The test files are named browser_something.js by convention, and in addition to mochitest assertions supports the CommonJS standard assertions, like nodejs’ assert module but implemented in Assert.sys.mjs.

These tests are used to test UI-related behaviour in Firefox for Desktop. They do not run on Android. If you’re testing internal code that does not directly interact with the user interface, xpcshell tests are probably a better fit for your needs.

Running the tests

You can run individual tests locally using the standard ./mach test command: ./mach test path/to/browser_test.js. You can omit the path if the filename is unique. You can also run entire directories, or specific test manifests:

./mach test path/to/browser.toml

You can also use the more specific ./mach mochitest command in the same way. Using ./mach mochitest --help will give you an exhaustive overview of useful other available flags relating to running, debugging and evaluating tests.

For both commands, you can use the --verify flag to run the test under test verification. This helps flush out intermittent issues with the test.

On our infrastructure, these tests run in the mochitest-browser-chrome jobs. There, they run on a per-manifest basis (so for most manifests, more than one test will run while the browser stays open).

The tests also get run in verify mode in the test-verify jobs, whenever the test itself is changed.

Note that these tests use “real” focus and input, so you’ll need to not touch your machine while running them. You can run them with the --headless flag to avoid this, but some tests may break in this mode.

Adding new tests

You can use the standard ./mach addtest path/to/new/browser_test.js command to generate a new browser test, and add it to the relevant manifest, if tests already exist in that directory. This automatically creates a test file using the right template for you, and adds it to the manifest.

If there are no tests in the directory yet (for example, for an entirely new feature and directory) you will need to:

  1. create an empty browser.toml file

  2. add it to BROWSER_CHROME_MANIFESTS collection from a moz.build file.

  3. then run the ./mach addtest command as before.

In terms of the contents of the test, please see Writing new browser mochitests.

Debugging tests

The ./mach test and ./mach mochitest commands support a --jsdebugger flag which will open the browser toolbox. If you add the debugger; keyword in your test, the debugger will pause there.

Alternatively, you can set breakpoints using the debugger yourself. If you want to pause the debugger before running the test, you can use the --no-autorun flag. Alternatively, if you want to pause the debugger on failure, you can use --debug-on-failure.

For more details, see Avoiding intermittent tests.

Reference material