xpcshell ツールはいくつかの種類の機能のテストに利用可能です。XPCOM の層で（スクリプトから利用可能なインターフェースを通じて）利用可能な物は、xpcshell でテストする事ができます。より多くの情報への手がかりを得るにはMozilla の自動テストおよび "automated testing" タグが指定されているページを参照してください。
初めての xpcshell ベースのテスト
初めての xpcshell ベースのテストの作り方は、簡単です。以下の内容で、test_first.js という名前（ユニットテストのファイル名は必ず test_ で始めてください）のファイルを作成してください。：
function run_test()
{
// 何か複雑な処理を行い、その結果としてどのような結果が望まれているのかをここに書いてください。
// これはただの例なので、trueを返しています。
ok(true);
}
これは実際には何もテストしませんが、実際にどのようにテストを書けばよいのかについての考え方を示しています。テストを実行したい時には、まず初めに xpcshell.ini manifest ファイルにこのテストファイル名を書く必要があります。テストファイルを既存のテストのセットの中に追加してください（例えばnetwork/test/unit/など。そして、 mach を利用してテストを実行します。
$ ./mach xpcshell-test netwerk/test/
...失敗または成功の旨のメッセージがコンソールに出力されます...
単体のテストは mach を使って次の様に実行します。
$ ./mach xpcshell-test <path_to_test_file>自分のテストを追加する
The test is executed by the test harness by calling the run_test function defined in the file. Anything you want to test must be spawned from this function.
If you have a group of files in a directory and they all include some common code that needs to run before or after your tests, to set up resources for example, you can put one copy of that code in a common source file and add it to the head or tail section of the manifest.
Each of your test files needs to contain at least a "run_test()" function. If the "run_test()" function runs to completion without throwing an exception, the test succeeds. If the your test needs to wait for asynchronous callbacks, you can tell the test harness to not kill the test when your callback has finished (as opposed to when run_test() has finished) with do_test_pending and do_test_finished (see below). add_test and run_next_test provide a nice interface around that if you want to run several asynchronous tests in succession.
If you want to import a common module in your tests you can use resource://test to load it. This special address always resolves to the current test folder.
Components.utils.import("resource://test/module.jsm"); // Import module.jsm that is in the same folder as current test.
XPCShell test functions
xpcshell tests have access to the following functions. They are defined in testing/xpcshell/head.js and testing/modules/Assert.jsm if you want to see how they work.
Test case registration and execution
add_test(testFunction)- Add a test function to the list of tests that are to be run asynchronously. Each test function must call
run_next_test()when it's done.run_test()should also callrun_next_test()to start execution of all asynchronous test functions. In most cases, you should rather use the more readable variantadd_task.
run_next_test()- Run the next test function from the list of asynchronous tests. Each test function must call
run_next_test()when it's done.run_test()should also callrun_next_test()to start execution of all asynchronous test functions.
add_task(testGenerator)- Add a generator to the list of tests that are to be run asynchronously. Whenever the generator
yields a Promise, the test runner waits until the promise is resolved or rejected before proceeding. As in Task.jsm, rejected promises are converted into exceptions, and resolved promises are converted into values.run_test()should also callrun_next_test()to start execution of all asynchronous test functions. The test cases must not callrun_next_test(), it is called automatically when the task finishes. do_register_cleanup(callback)- Executes the function
callbackafter the test has finished running, regardless of whether the test passes or fails. You can use this to clean up anything that might otherwise cause problems between test runs. do_test_pending()- Delay exit of the test until do_test_finished() is called. do_test_pending() may be called multiple times, and do_test_finished() must be paired with each before the unit test will exit.
do_test_finished()- Call this function to inform the test framework that an asynchronous operation has completed. If all asynchronous operations have completed (i.e., every do_test_pending() has been matched with a do_test_finished() in execution), then the unit test will exit.
Assertions and logging
ok, equal, notEqual, deepEqual, notDeepEqual, strictEqual, notStrictEqual- These assertion methods are provided by Assert.jsm. It implements the CommonJS Unit Testing specification version 1.1, which provides a basic, standardized interface for performing in-code logical assertions with optional, customizable error reporting. It is highly recommended to use these assertion methods, instead of the ones mentioned below.
Assert.throws(callback, expectedException, optional message)Assert.throws(callback, message)- Asserts that the provided callback function throws an exception. The
expectedExceptionargument can be anErrorinstance, or a regular expression matching part of the error message (like inAssert.throws(() => a.b, /is not defined/). do_check_eq(a, b)非推奨 Gecko 32.0- Call this function to assert that two objects are equal (using ==). If not equal, an exception is logged and the test case is halted.
do_check_neq(a, b)非推奨 Gecko 32.0- Call this function to assert that two objects are not equal (using !=). If equal, an exception is logged and the test case is halted.
do_check_true(expr)非推奨 Gecko 32.0- Call this function to assert that
expris equal totrue. do_check_false(expr)非推奨 Gecko 32.0- Call this function to assert that
expris equal tofalse. do_check_null(expr)非推奨 Gecko 32.0- Call this function to assert that
expris equal tonull. do_print(messageText)- Call this function to print text to the test's log file.
do_throw(messageText)非推奨 Gecko 32.0- Call this function to report an error and exit the test. The argument is a string that will be reported in the test's log file.
- Note: While
do_throwcan be caught by atry/catchblock, executing it will cause the test to fail when it completes.
Environment
do_get_file(testdirRelativePath, allowNonexistent)- Returns an
nsILocalFileobject representing the given file (or directory) in the test directory. For example, if your test is unit/test_something.js, and you need to access unit/data/somefile, you would calldo_get_file('data/somefile'). The given path must be delimited with forward slashes. You can use this to access test-specific auxiliary files if your test requires access to external files. Note that you can also use this function to get directories.Note: If your test needs access to one or more files that aren't in the test directory, you should install those files to the test directory in the Makefile where you specifyXPCSHELL_TESTS. For an example, seenetwerk/test/Makefile.in#117. do_get_profile()- Registers a directory with the profile service and returns an
nsILocalFileobject representing that directory. It also makes sure that the profile-change-net-teardown, profile-change-teardown, and profile-before-change observer notifications are sent before the test finishes. This is useful if the components loaded in the test observe them to do cleanup on shutdown (e.g., places). do_get_idle()- By default XPCShell tests will disable the idle service, so that idle time will always be reported as 0. Calling this function will re-enable the service and return a handle to it; the idle time will then be correctly requested to the underlying OS. The idle-daily notification could be fired when requesting idle service. It is suggested to always get the service through this method if the test has to use idle.
do_get_cwd()- Returns an
nsILocalFileobject representing the test directory. This is the directory containing the test file when it is currently being run. Your test can write to this directory as well as read any files located alongside your test. Your test should be careful to ensure that it will not fail if a file it intends to write already exists, however. load(testdirRelativePath)- Imports the JavaScript file referenced by
testdirRelativePathinto the global script context, executing the code inside it. The file specified is a file within the test directory. For example, if your test is unit/test_something.js and you have another file unit/extra_helpers.js, you can load the second file from the first simply by callingload('extra_helpers.js'). do_load_module(testdirRelativePath)- Calls do_get_file(
testdirRelativePath), then registers the returned file.
Utility
do_parse_document(path, type)- Parses and returns a DOM document.
do_execute_soon(callback)- Executes the function
callbackon a later pass through the event loop. Use this when you want some code to execute after the current function has finished executing, but you don't care about a specific time delay. This function will automatically insert ado_test_pending/do_test_finishedpair for you.
do_timeout(delay, fun)- Call this function to schedule a timeout. The given function will be called with no arguments provided after the specified delay (in milliseconds). Note that you must call
do_test_pendingso that the test isn't completed before your timer fires, and you must calldo_test_finishedwhen the actions you perform in the timeout complete, if you have no other functionality to test. (Note: the function argument used to be a string argument to be passed to eval, and some older branches support only a string argument or support both string and function.)
Async tests
When testing async APIs, we need to tell the test harness not to kill the test process once run_test() is finished, but to keep spinning the event loop until our callbacks have been called and our test has completed. This can be achieved with do_test_pending() and do_test_finished():
function run_test() {
// Tell the harness to keep spinning the event loop at least
// until the next do_test_finished() call.
do_test_pending();
someAsyncProcess(function callback(result) {
equal(result, expectedResult);
// Close previous do_test_pending() call.
do_test_finished();
});
}
Task-based asynchronous tests
If you have many such tests to perform, it's often easier to turn them into tasks, register them with add_task(), and invoke them with run_next_test():
function run_test() {
run_next_test();
}
add_task(function* test_foo() {
let foo = yield makeFoo(); // makeFoo() returns a Promise
equal(foo, expectedFoo);
});
add_task(function* test_bar() {
let foo = yield makeBar(); // makeBar() returns a Promise
equal(bar, expectedBar);
});
Callback-based asynchronous tests
Alternatively, you may put them in separate functions, register them with add_test(), and invoke them with run_next_test():
function run_test() {
run_next_test();
}
add_test(function test_foo() {
makeFoo(function callback(foo) { // makeFoo invokes a callback once completed
equal(foo, expectedFoo);
run_next_test();
});
});
add_test(function test_bar() {
makeBar(function callback(bar) {
equal(bar, expectedBar);
run_next_test();
});
});
Testing under Electrolysis
Since not all platforms support multi-process (electrolysis, aka "e10s"), you need to put any e10s-specific tests in a separate directory, and only run them if MOZ_IPC is defined. See /netwerk/test/Makefile.in for an example. Note that any "head_" or "tail_" scripts you have in your usual tests directory will not be run automatically in the new directory (but you can write a simple wrapper to load them: see "head_channels_clone.js" in netwerk/test/unit_ipc).
By default xpcshell tests run in the parent process. If you wish to run test logic in the child, you have several ways to do it:
- Create a regular test_foo.js test, and then write a wrapper test_foo_wrap.js file that uses the run_test_in_child() function to run an entire script file in the child. This is an easy way to arrange for a test to be run twice, once in chrome and then later (via the _wrap.js file) in content. See /network/test/unit_ipc for examples. The run_test_in_child() function takes a callback, so you should be able to call it multiple times with different files, if that's useful.
- For tests that need to run logic in both the parent + child processes during a single test run, you may use the poorly documented SendCommand() function, which takes a code string to be executed on the child, and a callback function to be run on the parent when it has completed. You will want to first call do_load_child_test_harness() to set up a reasonable test environment on the child. SendCommand returns immediately, so you will generally want to use do_test_pending/do_test_finished with it. NOTE: this method of test has not been used much, and your level of pain may be significant. Consider option #1 if possible.
See the documentation for run_test_in_child() and do_load_child_test_harness() in testing/xpcshell/head.js for more information.
Platform-specific tests
Sometimes you might want a test to know what platform it's running on (to test platform-specific features, or allow different behaviors). Unit tests are not normally invoked from a Makefile (unlike Mochitests), or preprocessed (so not #ifdefs), so platform detection with those methods isn't trivial.
Runtime detection
Some tests will want to only execute certain portions on specific platforms. One approach that's been used is to look for the existence of platform-specific components or interfaces. It's a bit hackish, but it's simple and it works.
- For Windows:
var isWindows = ("@mozilla.org/windows-registry-key;1" in Components.classes);
- For OS X:
var isOSX = ("nsILocalFileMac" in Components.interfaces);
- For Linux:
var isLinux = ("@mozilla.org/gnome-gconf-service;1" in Components.classes);
Adding your tests to the xpcshell manifest
To add a test to an xpcshell manifest file, you simply put the test file name in square brackets [] on its own line in the file, like so:
#edit netwerk/test/unit/xpcshell.ini [DEFAULT] head = head_channels.js tail = [test_first.js]
If this is a new directory that doesn't have an xpcshell manifest file, create a new file named xpcshell.ini and then add the following to a moz.build file near that file in the directory hierarchy:
XPCSHELL_TESTS_MANIFESTS += ['path/to/xpcshell.ini']
Typically, the moz.build containing XPCSHELL_TESTS_MANIFESTS is not in the same directory as xpcshell.ini, but rather in a parent directory. Common directory structures look like:
- feature/moz.build
- feature/tests/xpcshell/xpcshell.ini
or
- feature/moz.build
- feature/tests/moz.build
- feature/tests/xpcshell/xpcshell.ini
Adding conditions to a test
Sometimes you may want to add conditions to specify that a test should be skipped in certain configurations, or that a test is known to fail on certain platforms. You can do this in xpcshell manifests by adding annotations below the test file entry in the manifest, for example:
[test_first.js] skip-if = os == 'win'
This example would skip running test_first.js on Windows. There are currently three conditionals you can specify:
skip-if
skip-if tells the harness to skip running this test if the condition evaluates to true. You should use this only if the test has no meaning on a certain platform, or causes undue problems like hanging the test suite for a long time.
run-if
run-if tells the harness to only run this test if the condition evaluates to true. It functions as the inverse of skip-if.
fail-if
fail-if tells the harness that this test is expected to fail if the condition is true. If you add this to a test, make sure you file a bug on the failure and include the bug number in a comment in the manifest, like:
[test_first.js] # bug xxxxxx fails-if = os == 'linux'
run-sequentially
run-sequentially basically tells the harness to run the respective test in isolation. This is required for tests that are not "thread-safe". You should do all you can to avoid using this option, since this will kill performance. However, we understand that there are some cases where this is imperative, so we made this option available. If you add this to a test, make sure you specify a reason and possibly even a bug number, like:
[test_first.js] run-sequentially = Has to launch Firefox binary, bug 123456.
Manifest conditional expressions
For a more detailed description of the syntax of the conditional expressions, as well as what variables are available, see this page.
Running unit tests
Tests should be run using ./mach xpcshell-test path/to/tests/. To run a single test, use ./mach xpcshell-test path/to/test.js.
Running unit tests under a C++ debugger
Via --debugger and -debugger-interactive
You can specify flags when issuing the xpcshell-test command that will cause your test to stop right before running so you can attach to xpcshell in a debugger (implemented in バグ 382682).
Example:
$ ./mach xpcshell-test --debugger gdb --debugger-interactive netwerk/test/test_resumable_channel.js # js>_execute_test(); ...failure or success messages are printed to the console... # js>quit();
Debugging Electrolysis (e10s) xpcshell tests
Under e10s you have two processes. You can debug the chrome process, the child process, or both at the same time.
To debug the chrome process
simply use the --debugger-interactive and --debugger flags as described above.
To debug the child process
The child process is where your xpcshell test's JS code is being run, so it is often--but not always--the process you're interested in. To debug the child, set MOZ_DEBUG_CHILD_PROCESS=1 in your environment (or on the command line) and run the test, and you will see the child process emit a printf with its process ID, then sleep. Attach a debugger to the child's pid, and when it wakes up you can debug it:
$ MOZ_DEBUG_CHILD_PROCESS=1 ./mach xpcshell-test test_simple_wrap.js CHILDCHILDCHILDCHILD debug me @13476
To debug both parent and child processes
Use MOZ_DEBUG_CHILD_PROCESS=1 to attach debuggers to each process. (For gdb at least, this means running separate copies of gdb, one for each process.)
Common problems
Events are not processed during test execution if not explicitly triggered. This sometimes causes issues during shutdown, when code is run that expects previously created events to have been already processed. In such cases, this code at the end of a test can help:
let thread = gThreadManager.currentThread; while (thread.hasPendingEvents()) thread.processNextEvent(true);