Mochitest

  • Revision slug: Mochitest
  • Revision title: Mochitest
  • Revision id: 9773
  • Created:
  • Creator: Jonathan_Watt
  • Is current revision? No
  • Comment Add more information on how to add new tests to the tree and have the tinderboxen use them

Revision Content

Introduction

Mochitest is an automated testing framework built on top of the MochiKit JavaScript libraries. It's just one of the automated regression testing facilities Mozilla developers have at their desposal. Tests report success or failure to the test harness using JavaScript function calls.

Mochitest's unique strength is that it runs tests written as webpages in a full browser environment where the tests have chrome (elevated) privileges. This allows JavaScript in the tests to do much, much more than it would otherwise be able to do. In addition to the capabilities a script would normally have (e.g. DOM manipulation), scripts can access XPCOM components and services, and even access the browser itself. This allows a script to, say, simulate user input to the browser's user interface, before examining the browser to verify that the input had the intended results.

Mochitest's use of JavaScript function calls to communicate test success or failure can make it unsuitable for certain types of test. Only things that can in some way be tested using JavaScript (with chrome privileges!) can be tested with this framework. Given some creativity, that's actually much more things than you might first think, but it's not possible to write Mochitest tests to directly test a non-scripted C++ component, for example.

Try not to use Mochitest

Yes, really. For many things Mochitest is overkill. In general you should always try to use one of the lighterweight testing frameworks. For example, if you only want to test a single XPCOM component then you should use xpcshell. On the other hand there are some things that Mochitest cannot do, or isn't designed to do. For example, for visual output tests you should try to use the reftest framework. For more information on the different types of automated testing frameworks see Mozilla automated testing.

Running Mochitests

To run the Mochitest tests you need to build Mozilla, change directory to objdir/_tests/testing/mochitest and run the command:

> perl runtests.pl

This will open your new build with a document containing a "Run Tests" link at the top. To run the tests simply click that link and watch the results being generated in front of your eyes.

Writing new Mochitests

A basic document on Writing MochiTest-based unit tests has already been started. (Maybe the basic stuff from that document should be moved here and that document should give the matter more detailed treatment?)

Adding new Mochitests

Once you've written a new test you need to add it to the Mozilla source tree and tell the build system about it so that the Mozilla tinderboxes will run it automatically.

New Mochitest tests should go somewhere close to the code they are testing. For example, if you create a new test for some HTML feature, you probably want to put the test in the directory mozilla/content/html/content/test or mozilla/content/document/content/test. If a test directory does not exist near the code you are testing you can add a new test directory as the patch in bug 368531 demonstrates.

To tell the build system about your new test you need to add the name of your test file to _TEST_FILES in the test directory's Makefile.in.

Before committing your new test and the Makefile.in changes, do run Mochitest in an up to date trunk build to check that you will not unexpectedly turn the tree orange.

FAQ

For answers to frequently asked Mochitest questions see the Mochitest FAQ. (Information between these two documents could really do with a lot of reorganization.)

Revision Source

<p>
</p>
<h3 name="Introduction"> Introduction </h3>
<p>Mochitest is an automated testing framework built on top of the <a class="external" href="http://mochikit.com/">MochiKit</a> JavaScript libraries. It's just one of the automated regression testing facilities Mozilla developers have at their desposal. Tests report success or failure to the test harness using JavaScript function calls.
</p><p>Mochitest's unique strength is that it runs tests written as webpages in a full browser environment where the tests have chrome (elevated) privileges. This allows JavaScript in the tests to do much, much more than it would otherwise be able to do. In addition to the capabilities a script would normally have (e.g. DOM manipulation), scripts can access XPCOM components and services, and even access the browser itself. This allows a script to, say, simulate user input to the browser's user interface, before examining the browser to verify that the input had the intended results.
</p><p>Mochitest's use of JavaScript function calls to communicate test success or failure can make it unsuitable for certain types of test. Only things that can in some way be tested using JavaScript (with chrome privileges!) can be tested with this framework. Given some creativity, that's actually much more things than you might first think, but it's not possible to write Mochitest tests to directly test a non-scripted C++ component, for example.
</p>
<h3 name="Try_not_to_use_Mochitest"> Try not to use Mochitest </h3>
<p>Yes, really. For many things Mochitest is overkill. In general you should always try to use one of the lighterweight testing frameworks. For example, if you only want to test a single XPCOM component then you should use <a href="en/Writing_xpcshell-based_unit_tests">xpcshell</a>. On the other hand there are some things that Mochitest cannot do, or isn't designed to do. For example, for visual output tests you should try to use the <a href="en/Creating_reftest-based_unit_tests">reftest</a> framework. For more information on the different types of automated testing frameworks see <a href="en/Mozilla_automated_testing">Mozilla automated testing</a>.
</p>
<h3 name="Running_Mochitests"> Running Mochitests </h3>
<p>To run the Mochitest tests you need to <a href="en/Build_Documentation">build Mozilla</a>, change directory to objdir/_tests/testing/mochitest and run the command:
</p>
<code><pre>&gt; perl runtests.pl
</pre></code>
<p>This will open your new build with a document containing a "Run Tests" link at the top. To run the tests simply click that link and watch the results being generated in front of your eyes.
</p>
<h3 name="Writing_new_Mochitests"> Writing new Mochitests </h3>
<p>A basic document on <a href="en/Writing_MochiTest-based_unit_tests">Writing MochiTest-based unit tests</a> has already been started. (Maybe the basic stuff from that document should be moved here and that document should give the matter more detailed treatment?)
</p>
<h3 name="Adding_new_Mochitests"> Adding new Mochitests </h3>
<p>Once you've written a new test you need to add it to the Mozilla source tree and tell the build system about it so that the Mozilla tinderboxes will run it automatically.
</p><p>New Mochitest tests should go somewhere close to the code they are testing. For example, if you create a new test for some HTML feature, you probably want to put the test in the directory mozilla/content/html/content/test or mozilla/content/document/content/test. If a test directory does not exist near the code you are testing you can add a new test directory as the patch in <a class="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=368531">bug 368531</a> demonstrates.
</p><p>To tell the build system about your new test you need to add the name of your test file to _TEST_FILES in the test directory's Makefile.in.
</p><p>Before committing your new test and the Makefile.in changes, do run Mochitest in an up to date trunk build to check that you will not unexpectedly turn the tree orange.
</p>
<h3 name="FAQ"> FAQ </h3>
<p>For answers to frequently asked Mochitest questions see the <a href="en/Mochitest_FAQ">Mochitest FAQ</a>. (Information between these two documents could really do with a lot of reorganization.)
</p>
Revert to this revision