View source for MailNews:Xpcshell tests

<small>[[MailNews:Automated Testing|<< Back to MailNews:Automated Testing]]</small>

__TOC__

The xpcshell unit tests are probably the easiest test to write, requiring no UI and being written in javascript. They are very useful for testing interfaces and back-end functionality.

MailNews has a growing set of xpcshell tests. Developers and contributors should consider adding tests within MailNews where possible.

xpcshell tests can be run in a variety of different ways, the [http://developer.mozilla.org/en/docs/Writing_xpcshell-based_unit_tests devmo wiki page] describes these best.

== xpcshell test reporting ==

These currently run on the [http://tinderbox.mozilla.org/SeaMonkey/ SeaMonkey tinderboxes], and report as TUnit. Thunderbird hopes to pick running of these up soon ({{bug|422817}}).

== Developing xpcshell tests within MailNews ==

When developing new tests it is useful to look at the [http://developer.mozilla.org/en/docs/Writing_xpcshell-based_unit_tests devmo documentation for writing xpcshell-based unit tests].

[http://mxr.mozilla.org/seamonkey/find?text=&kind=text&string=%2Fmailnews%2F.*test_.* This list links the existing tests] that are currently within Thunderbird.

The review policy for tests is [[MailNews:Automated_Testing#Rules_and_Review_Policy|located here]].

=== MailNews xpcshell test facilities ===

Each existing unit test directory has a head_*.js file that provides the following by importing core scripts:

* A global variable "gProfileDir" containing an nsIFile variable with the profile directory to use for the xpcshell tests.
* A nsIDirectoryService that points at the gProfileDir and provides the necessary facilities to use profile-related directories, e.g. NS_GetSystemDirectory("MailD", ...).

In addition, the [[MailNews:Fakeserver|fakeserver]] library allows tests to communicate with a variety of different, potentially non-standard servers.


=== Profile Directory Cleanup ===

The xpcshell tests do not run in a standard profile directory. The mailnews xpcshell test facilities provide a specific directory for its tests:

<pre>
<objdir>/_tests/mailtest/
</pre>

This directory is emptied and re-created before each test is run. This means that when running a test with SOLO_FILE and check-one or check-interactive, the directory is left in place to aid debugging.

== Guidelines for new tests ==

These guidelines are intended to provide some level of consistency across the MailNews tests.

=== New Directories for tests ===

* New directories should be created as test/unit under whichever directory they apply, e.g. tests directly relating to the address book go into mailnews/addrbook/test/unit.
* All new directories should have a head_*.js file, these should import some of the core mailnews files (mailDirService.js at a minimum) and may provide any functions common to that set of tests.

=== New Tests ===

* The test name should be relevant to the class/interface/action the bug is testing, or the bug number of the bug it is checking that it fixes (a bug number would imply just testing one bug, whereas a name implies testing some or all functionality of an item).
* Where the profile directory is required, use gProfileDir that is automatically created in [http://mxr.mozilla.org/seamonkey/source/mailnews/test/resources/mailDirService.js mailDirService.js]

== Problems running core xpcshell tests on MailNews ==

See [[MailNews:Automated_Testing#xpcshell_tests]] for the list of current problems.

== Useful Links ==

* [http://developer.mozilla.org/en/docs/Writing_xpcshell-based_unit_tests devmo documentation for writing xpcshell-based unit tests]
* [http://mxr.mozilla.org/seamonkey/find?text=&kind=text&string=%2Fmailnews%2F.*test_.* Current MailNews unit tests]