3.5 KiB
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:
- create an empty
browser.tomlfile - add it to
BROWSER_CHROME_MANIFESTScollection from amoz.buildfile. - then run the
./mach addtestcommand 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.