Revision Content

Note: The previous page was largely out of date. The new page is intended as a guide to the testing frameworks at Mozilla; some of the old page should be split out to a "Running Automated Tests" page to complement the "Developing Tests" page (which itself needs to be updated).

You've just written a feature and (hopefully!) want to test it. Or you've decided that an existing feature doesn't have enough tests and want to contribute some. But where do you start? You've looked around and found references to things like "xpcshell" or "mozmill" or "talos". What do they all do? What's the overlap? In short, where should your new tests go?

This document aims to answer that question. There's a very short summary of each framework, and a bit of Q&A to help you pick your framework. This may only narrow down your choices, however, in which case you should read more about the frameworks and/or hop on irc://irc.mozilla.org/#ateam, #qa, or one of the development forums and ask questions.

Generally, you should pick the lowest-level framework that you can. If you are testing JavaScript but don't need a window, use xpcshell. If you're testing page layout, try to use reftest. The advantage is that you don't drag in a lot of other components that might have their own problems, so you can home in quickly on any bugs in what you are specifically testing.

In production

buildbot automation

These tests are found within the mozilla-central tree, along with the product code. They are all run when a changeset is pushed to mozilla-central, mozilla-inbound, or try, with the results showing up on tbpl. They can also be run on their own.

These tests are run on machines in a very large pool. For the most part, all tests of a particular type run on the same pool of machines, regardless of branch. One substantial exception is that try builds are performed on a pool that is isolated from all other builds.

Written in C++, compiled-code tests can test pretty much anything but are difficult to write properly and are often less suitable than a domain-specific harness. In general, this should be your last option for a new test, unless you have to test something that is not exposed to JavaScript. These tests, invoked in-tree via make check , also include python unit tests to ensure that the tree is in a good state.

xpcshell are console JavaScript tests. There is no chrome, no content, no window. xpcshell is useful for testing low-level things, such as XPCOM components. If you don't need a window, use this. xpcshell is particularly useful for testing low-level objects that are exposed to JavaScript.

JS shell tests (J)

Tests specifically for the JavaScript engine. They test every piece of the engine.

A reftest verifies that two web pages are rendered identically to test layout and graphics correctness, taking advantage of the fact that there is generally more than one way to achieve any given visual effect in a browser. For each test, Reftest will take two sample pages that try to produce the same effect (normally one with a simple markup, and one using more complex markup) and verify that they produce the same visual construct.

Mochitest uses JavaScript to test features. Anything piece that has its functionality exposed in JavaScript can theoretically be tested with Mochitest. "Plain" mochitest should be used to test DOM APIs and other pieces of functionality exposed to web content (i.e. requiring no special permissions).

Mochitest-other (Moth)

Mochitest-other are mochitests with higher privileges, logically split into a few sections:

IPC: tests plugin APIs, particularly out-of-process plugins.

a11y: tests accessibility interfaces.

chrome: tests running with high privileges that can test a lot of the browser's functionality. Tests that verify JavaScript interactions with chrome-level objects should go here. These tests do not exist for mobile Firefox.

Mochitest-browser-chrome (M b-c)

browser-chrome: running in the scope of the browser window, this is a rough UI automation tool testing how the browser interacts with itself and with content. Since these are moving away from the rest of mochitest's functionality, they will eventually be split into their own category, "b-c".

Mochitest-metro-chrome (M mc)

browser-metro-chrome: Browser chrome tests running in the immersive version of Firefox for Windows 8 and up.

Mochitest-Robocop tests run on Native Android builds only marked with an 'rc' in tbpl. These are Java based tests which run from the mochitest harness and generated similar log files. These are designed for testing the native UI of Android devices by sending events to the front end.

Jetpack (JP)

Jetpack tests verify the Add-on SDK code that is included in builds of Firefox. The canonical source for the tests and the Add-on SDK code lives at github and is periodically uplifted to mozilla-central but you can run the tests direct from a Firefox build. If you need help interpreting test failures or fixing bugs in the SDK code itself then come and talk to the SDK team in #jetpack.

Mozmill is an extensive framework for browser automation. It is an extension with an extensive API to help you write functional tests that simulate user interactions, as well as a full unit test API. It can be used to test configurations that are difficult to simulate in buildbot automation. QA automation uses Mozmill to test localized builds, performance over time, and other scenarios.

SpeedTests is a framework for executing arbitrary tests, which report results via JavaScript calls, in several browsers. Originally this framework was designed for modified versions of Microsoft's speed demos but has now been expanded to include conformance tests such as test262 and Kraken. SpeedTests are good for cross-browser comparisons when tests don't need to dig too deep into the guts of the browsers.

Peptest measures responsiveness, how "snappy" Firefox/Thunderbird feels, by issuing alerts when the event loop is stuck for more than 50 ms. It will soon be available on try, to catch regressions in responsiveness. If you're helping to improve peppiness, consider writing some peptests to help you measure your improvements and to find future regressions.

Marionette is a test automation framework used to drive the UI and JS/XPCOM layer of remote or local instances.

The Marionette client includes the harness which runs Marionette and mochitest-browser-chrome tests. It will give you similar functionality as Selenium for Firefox builds, but with built in chrome support as well. With it, you can send commands to chrome or content on demand, allowing you to coordinate large scope tests like communicating to multiple remote gecko processes (useful for testing things like SMS messaging for WebAPI for example).

This is currently being used to test B2G, but can work with any gecko platform.

So which do I use already?

Here's a series of questions to ask when you want to write some tests. Remember this is only a rough guide, and it may give you multiple frameworks. Try #ateam on irc.mozilla.org to get some more specific answers.

Want to investigate responsiveness?

Testing UI?

Testing Mobile/Android?

Mobile UI, look at Robocop. There are some specific features that Mochitest or Reftest can cover. Mochitest-chrome and browser-chrome do not run on Android. If you want to test performance, Talos runs just fine with a few limitations (use --noChrome options) and smaller cycles (e.g. 10 iterations instead of 20, etc...)

None of the above?

To get your tests run through buildbot, try Mochitest, or, if higher privileges are required and you don't need mobile testing, try Mochitest chrome tests.

While not in buildbot automation, Mozmill is a bigger framework that can test almost anything, on the desktop at least.

For desktop Firefox or B2G, or if you just want to see the future of Gecko testing, look into the on-going Marionette project.

Revision Source

<div class="note">
<strong>Note:</strong> The previous page was largely out of date. The new page is intended as a guide to the testing frameworks at Mozilla; some of the old page should be split out to a "<a href="/en-US/docs/Running_automated_tests">Running Automated Tests</a>" page to complement the "<a href="/en-US/docs/Mozilla/QA/Developing_tests">Developing Tests</a>" page (which itself needs to be updated).</div>
<p>You've just written a feature and (hopefully!) want to test it. Or you've decided that an existing feature doesn't have enough tests and want to contribute some. But where do you start? You've looked around and found references to things like "xpcshell" or "mozmill" or "talos". What do they all do? What's the overlap? In short, where should your new tests go?</p>
<p>This document aims to answer that question. There's a very short summary of each framework, and a bit of Q&amp;A to help you pick your framework. This may only narrow down your choices, however, in which case you should read more about the frameworks and/or hop on irc://irc.mozilla.org/#ateam, #qa, or one of the development forums and ask questions.</p>
<p>Generally, you should pick the lowest-level framework that you can. If you are testing JavaScript but don't need a window, use xpcshell. If you're testing page layout, try to use reftest. The advantage is that you don't drag in a lot of other components that might have their own problems, so you can home in quickly on any bugs in what you are specifically testing.</p>
<p>For how test harnesses work see <a href="/en-US/docs/How_test_harnesses_work">https://developer.mozilla.org/en-US/docs/How_test_harnesses_work</a></p>
<h2 id="In_production">In production</h2>
<h3 id="buildbot_automation">buildbot automation</h3>
<p>These tests are found within the mozilla-central tree, along with the product code. They are all run when a changeset is pushed to mozilla-central, mozilla-inbound, or try, with the results showing up on <a href="http://tbpl.mozilla.org">tbpl</a>. They can also be run on their own.</p>
<p>These tests are run on machines in a very large pool. For the most part, all tests of a particular type run on the same pool of machines, regardless of branch. One substantial exception is that try builds are performed on a pool that is isolated from all other builds.</p>
<p>The letters in parentheses are the abbreviations used by tbpl.</p>
<h4 id="compiled-code_(B)"><a name="compiled-code">compiled-code (B)</a></h4>
<p>Written in C++, <a href="/en-US/docs/Compiled-code_automated_tests">compiled-code tests</a> can test pretty much anything but are difficult to write properly and are often less suitable than a domain-specific harness. In general, this should be your last option for a new test, unless you have to test something that is not exposed to JavaScript. These tests, invoked in-tree via <a href="/en-US/docs/Compiled-code_automated_tests#Running_the_tests">make check</a> , also include <a href="/en-US/docs/Compiled-code_automated_tests#Python_unit_tests">python unit tests</a> to ensure that the tree is in a good state.</p>
<h4 id="xpcshell_(X)"><a name="xpcshell">xpcshell (X)</a></h4>
<p><a href="/en-US/docs/XPConnect/xpcshell">xpcshell</a> are console JavaScript tests. There is no chrome, no content, no window. xpcshell is useful for testing low-level things, such as XPCOM components. If you don't need a window, use this. xpcshell is particularly useful for testing low-level objects that <em>are</em> exposed to JavaScript.</p>
<h4 id="JS_shell_tests_(J)">JS shell tests (J)</h4>
<p>Tests specifically for the JavaScript engine. They test every piece of the engine.</p>
<h4 id="crashtest_(C)"><a name="crashtest">crashtest (C)</a></h4>
<p>Really simple: open a web page and see if it causes a crash. If you've found pages that crash Firefox, add a test here to make sure future versions don't experience this crash again.</p>
<h4 id="reftest_(R)"><a name="reftest">reftest (R)</a></h4>
<p>A <a href="/en-US/docs/Creating_reftest-based_unit_tests">reftest</a> verifies that two web pages are rendered identically to test layout and graphics correctness, taking advantage of the fact that there is generally more than one way to achieve any given visual effect in a browser. For each test, Reftest will take two sample pages that try to produce the same effect (normally one with a simple markup, and one using more complex markup) and verify that they produce the same visual construct.</p>
<h4 id="Mochitest_(M)"><a name="mochitest">Mochitest (M)</a></h4>
<p><a href="/en-US/docs/Mochitest">Mochitest</a> uses JavaScript to test features. Anything piece that has its functionality exposed in JavaScript can theoretically be tested with Mochitest. "Plain" mochitest should be used to test DOM APIs and other pieces of functionality exposed to web content (i.e. requiring no special permissions).</p>
<h4 id="Mochitest-other_(Moth)">Mochitest-other (Moth)</h4>
<p>Mochitest-other are mochitests with higher privileges, logically split into a few sections:</p>
<ul>
<li>IPC: tests plugin APIs, particularly out-of-process plugins.</li>
<li>a11y: tests accessibility interfaces.</li>
<li><a href="/en-US/docs/Chrome_tests" name="mochitestother">chrome</a>: tests running with high privileges that can test a lot of the browser's functionality. Tests that verify JavaScript interactions with chrome-level objects should go here. These tests do not exist for mobile Firefox.</li>
</ul>
<h4 id="Mochitest-browser-chrome_(M_b-c)">Mochitest-browser-chrome (M b-c)</h4>
<p><a href="/en-US/docs/Browser_chrome_tests">browser-chrome</a>: running in the scope of the browser window, this is a rough UI automation tool testing how the browser interacts with itself and with content. Since these are moving away from the rest of mochitest's functionality, they will eventually be split into their own category, "b-c".</p>
<h4 id="Mochitest-metro-chrome_(M_mc)">Mochitest-metro-chrome (M mc)</h4>
<p><a href="https://developer.mozilla.org/en-US/docs/Metro_browser_chrome_tests" title="https://developer.mozilla.org/en-US/docs/Metro_browser_chrome_tests">browser-metro-chrome</a>: Browser chrome tests running in the immersive version of Firefox for Windows 8 and up.</p>
<h4 id="Mochitest-Robocop_(Mrc)"><a name="robocop">Mochitest-Robocop (Mrc)</a></h4>
<p><a class="link-https" href="https://wiki.mozilla.org/Auto-tools/Projects/Robocop/WritingTests">Mochitest-Robocop</a> tests run on Native Android builds only marked with an 'rc' in tbpl. These are Java based tests which run from the mochitest harness and generated similar log files. These are designed for testing the native UI of Android devices by sending events to the front end.</p>
<h4 id="Jetpack_(JP)">Jetpack (JP)</h4>
<p><a href="https://wiki.mozilla.org/Jetpack/Testing#Running_tests_from_compiled_Firefox">Jetpack tests</a> verify the Add-on SDK code that is included in builds of Firefox. The canonical source for the tests and the <a href="https://github.com/mozilla/addon-sdk">Add-on SDK code</a> lives at github and is periodically uplifted to mozilla-central but you can run the tests direct from a Firefox build. If you need help interpreting test failures or fixing bugs in the SDK code itself then come and talk to the SDK team in <a href="irc://irc.mozilla.org/#jetpack">#jetpack</a>.</p>
<h4 id="Talos_(T)"><a name="talos">Talos (T)</a></h4>
<p><a class="link-https" href="https://wiki.mozilla.org/Buildbot/Talos">Talos</a> is a framework for performance testing. If you're measuring performance, Talos is the place to go.</p>
<p><a class="link-https" href="https://wiki.mozilla.org/Buildbot/Talos">Talos tests on buildbot</a> are split into a few categories. Some test suites are run in several categories but with different configurations or metrics. The following are the codes as found on tbpl:</p>
<ul>
<li>tp: Measures the load time of a set of test web pages taken from the Alexa top 500.</li>
<li>s: SVG rendering performance.</li>
</ul>
<h5 id="Desktop_only">Desktop only</h5>
<ul>
<li>c: chrome. A set of suites with chrome (i.e. the full UI) enabled.</li>
<li>di: dirty. Uses a "dirty" places.sqlite that more closely resembles that of an average user.</li>
<li>dr: <a class="link-https" href="https://wiki.mozilla.org/Dromaeo">Dromaeo</a>. A suite of JavaScript performance tests.</li>
<li>n: nochrome. A set of suites with chrome disabled.</li>
</ul>
<h5 id="Mobile_only">Mobile only</h5>
<ul>
<li>dh: tdhtml. Measures the time to cycle through a set of DHTML test pages.</li>
<li>pn: tpan. Loads a test page and measures the time to pan to the bottom then back up to the top.</li>
<li>sp: tsspider. Runs the SunSpider benchmark test.</li>
<li>tpn: The tp suites with chrome disabled.</li>
<li>ts: Tests the startup time of Firefox by opening the browser 20 times.</li>
<li>w: twinopen. Time to open a new window.</li>
<li>z: tzoom. Loads a test page and measures the time to zoom in and out.</li>
</ul>
<p>These are <a class="link-https" href="https://wiki.mozilla.org/Auto-tools/Projects/Robocop/WritingTests">Robocop</a> based tests:</p>
<ul>
<li>(rck2): tcheckerboard2: Loads a test page, zooms and pans, measures the amount of checkerboarding (delayed painting).</li>
<li>(rp): trobopan: Loads a test page and pans to the bottom and back to the top. This measures the lag time in rendering the page.</li>
<li>(rpr): tprovider: Fills the awesomebar database (android os db) with thousands of entries and measures the time to perform a series of queries.</li>
</ul>
<h4 id="Mozmill"><a name="mozmill">Mozmill</a></h4>
<p><a href="/en-US/docs/Mozmill">Mozmill</a> is an extensive framework for browser automation. It is an extension with an extensive API to help you write functional tests that simulate user interactions, as well as a full unit test API. It can be used to test configurations that are difficult to simulate in buildbot automation. QA automation uses Mozmill to test localized builds, performance over time, and other scenarios.</p>
<h4 id="Speedtests"><a name="speedtests">Speedtests</a></h4>
<p><a class="link-https" href="https://wiki.mozilla.org/Auto-tools/Projects/SpeedTests">SpeedTests</a> is a framework for executing arbitrary tests, which report results via JavaScript calls, in several browsers. Originally this framework was designed for modified versions of Microsoft's <a href="http://ie.microsoft.com/testdrive/">speed demos</a> but has now been expanded to include conformance tests such as test262 and Kraken. SpeedTests are good for cross-browser comparisons when tests don't need to dig too deep into the guts of the browsers.</p>
<h4 id="Peptest"><a name="peptest">Peptest</a></h4>
<p><a href="/en-US/docs/Mozilla_automated_testing/Peptest">Peptest</a> measures responsiveness, how "snappy" Firefox/Thunderbird feels, by issuing alerts when the event loop is stuck for more than 50 ms. It will soon be available on try, to catch regressions in responsiveness. If you're helping to improve peppiness, consider writing some peptests to help you measure your improvements and to find future regressions.</p>
<h4 id="Marionette_harness"><a name="marionette">Marionette harness</a></h4>
<p><a href="/en-US/docs/Marionette">Marionette</a> is a test automation framework used to drive the UI and JS/XPCOM layer of remote or local instances.</p>
<p>The <a href="/en-US/docs/Marionette/Running_Tests">Marionette client</a> includes the harness which runs Marionette and mochitest-browser-chrome tests. It will give you similar functionality as Selenium for Firefox builds, but with built in chrome support as well. With it, you can send commands to chrome or content on demand, allowing you to coordinate large scope tests like communicating to multiple remote gecko processes (useful for testing things like SMS messaging for WebAPI for example).</p>
<p>This is currently being used to test B2G, but can work with any gecko platform.</p>
<h2 id="So_which_do_I_use_already.3F">So which do I use already?</h2>
<p>Here's a series of questions to ask when you want to write some tests. Remember this is only a rough guide, and it may give you multiple frameworks. Try #ateam on irc.mozilla.org to get some more specific answers.</p>
<h3 id="Is_it_low-level_code.3F">Is it low-level code?</h3>
<p>If the functionality is exposed to JavaScript, consider <a href="#xpcshell">xpcshell</a>. If not, you'll probably have to use <a href="#compiled-code">compiled-code tests</a>.</p>
<h3 id="Does_it_cause_a_crash.3F">Does it cause a crash?</h3>
<p>If so, a <a href="#crashtest">crashtest</a> could help isolate the problem. Note that this may lead to more tests once the core problem is found.</p>
<h3 id="Is_it_a_layout.2Fgraphics_feature.3F">Is it a layout/graphics feature?</h3>
<p><a href="#reftest">Reftest</a> is your best bet, if possible.</p>
<h3 id="Do_you_need_to_verify_performance.3F">Do you need to verify performance?</h3>
<p>Try <a href="#talos">Talos</a>!</p>
<h3 id="Are_you_comparing_speed_or_functionality_between_browsers.3F">Are you comparing speed or functionality between browsers?</h3>
<p>See if you can write a <a href="#speedtests">Speedtest</a>.</p>
<h3 id="Want_to_investigate_responsiveness.3F">Want to investigate responsiveness?</h3>
<p><a href="#peptest">Peptest</a> provides an easy way to measure responsiveness.</p>
<h3 id="Testing_UI.3F">Testing UI?</h3>
<p>If it's mobile UI, look into <a href="#robocop">Robocop</a>. For desktop, try <a href="#mochitestother">browser chrome tests</a>, soon to be split out of Mochitest, or Mozmill</p>
<h3 id="Testing_Mobile.2FAndroid.3F">Testing Mobile/Android?</h3>
<p>Mobile UI, look at <a href="#robocop">Robocop</a>. There are some specific features that <a href="#mochitest">Mochitest</a> or <a href="#reftest">Reftest</a> can cover. Mochitest-chrome and browser-chrome do not run on Android. If you want to test performance, <a href="#talos">Talos</a> runs just fine with a few limitations (use --noChrome options) and smaller cycles (e.g. 10 iterations instead of 20, etc...)</p>
<h3 id="None_of_the_above.3F">None of the above?</h3>
<p>To get your tests run through buildbot, try <a href="#mochitest">Mochitest</a>, or, if higher privileges are required and you don't need mobile testing, try <a href="#mochitestother">Mochitest chrome tests</a>.</p>
<p>While not in buildbot automation, <a href="#mozmill">Mozmill</a> is a bigger framework that can test almost anything, on the desktop at least.</p>
<p>For desktop Firefox or B2G, or if you just want to see the future of Gecko testing, look into the on-going <a href="#marionette">Marionette</a> project.</p>
<!--languages( { "es": "es/Pruebas_automatizadas_de_Mozilla", "ja": "Ja/Mozilla_automated_testing", "zh-cn": "zh-cn/Mozilla_automated_testing" } )-->