Testing

Firefox has many test harnesses. This page summarizes the most common ones, where they live, and how to run them. The unifying entry point is ./mach test <path>, which dispatches to the appropriate harness based on the file.

Harness map

Harness	What it tests	Where tests live	Mach command
Mochitest (plain)	Browser DOM behavior with privileged JS access	dom/, toolkit/, etc.	./mach mochitest path
Mochitest-chrome	Chrome-privileged code	browser/, toolkit/	./mach mochitest --flavor=chrome
Mochitest-browser	Full browser UI tests	browser/components/.../browser_*.js	./mach mochitest path
xpcshell	Headless JS unit tests, XPCOM-only	*/test/unit/, services/	./mach xpcshell-test path
gtest	C++ unit tests	*/gtest/, testing/gtest/	./mach gtest 'Name.*'
Reftest	Pixel-comparison layout tests	layout/reftests/	./mach reftest path
Crashtest	Layout crash regressions	*/crashtests/	./mach crashtest path
Web platform tests (WPT)	Cross-browser standards tests	testing/web-platform/	./mach wpt path
Marionette	Mozilla-flavored WebDriver	testing/marionette/	./mach marionette-test
Geckodriver / WebDriver	W3C WebDriver	testing/geckodriver/	cargo test in geckodriver
Talos	Performance regressions (long-form)	testing/talos/	./mach talos-test
Raptor	Page-load and benchmark performance	testing/raptor/	./mach raptor
AWSY	Memory ("Are We Slim Yet")	testing/awsy/	./mach awsy-test
TPS	Sync end-to-end tests	services/sync/tps/	./mach tps-build then ./mach tps
Cppunit	Standalone C++ tests (legacy)	testing/cppunittest.toml	./mach cppunittest
Mozharness scripts	CI-side orchestration	testing/mozharness/	typically run by TaskCluster

Picking the right harness

• Adding a new Web platform behavior? Write a WPT under testing/web-platform/tests/<spec>/. WPT is required for nearly all spec-conformance changes.
• Testing browser chrome? Use mochitest-browser. Files named browser_*.js. They run in the browser UI process.
• Testing C++ that doesn't need a browser? Use gtest. Files under <dir>/gtest/.
• Testing JS without a DOM? Use xpcshell. Quick, headless.
• Layout regression? Reftest or crashtest under layout/reftests/.

Running just the affected tests

./mach try includes a "test selection" that picks tests likely to be affected by your changes. Locally:

./mach test --outgoing       # find tests covered by changed files
./mach try fuzzy             # interactive try selection

Test manifests

Tests are listed in manifests next to them:

• mochitest.toml — Mochitest manifest
• xpcshell.toml — xpcshell manifest
• browser.toml — mochitest-browser manifest
• reftest.list, crashtest.list — Reftest/crashtest manifests
• meta.toml / __init__.toml — WPT metadata

When adding a test, also add it to the manifest in the same directory.

Skipping intermittents

Tests can be marked skip-if = ... in the manifest, with a reason and ideally a Bug NNNNNN. The skipfails.py tooling under testing/ helps maintain skip annotations:

• testing/skipfails.py
• testing/clean_skipfails.py
• testing/intermittent_failures.py

CI: TaskCluster

Local runs cover one platform; CI runs the full matrix across Linux/macOS/Windows/Android × debug/opt/asan/tsan. The task graph lives in taskcluster/. To preview what CI will do, use ./mach try.

Test-only modules

Helpers that tests can import live under testing/modules/ (e.g., Sinon.sys.mjs, XPCShellContentUtils.sys.mjs) and testing/specialpowers/ (the SpecialPowers API to bypass content-process security in mochitests).