Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 822 insertions, 0 deletions

diff --git a/testing/docs/xpcshell/index.rst b/testing/docs/xpcshell/index.rst
new file mode 100644
index 0000000000..e9a8e93aca
--- /dev/null
+++ b/testing/docs/xpcshell/index.rst
@@ -0,0 +1,822 @@
+XPCShell tests
+==============
+
+xpcshell tests are quick-to-run tests, that are generally used to write
+unit tests. They do not have access to the full browser chrome like
+``browser chrome tests``, and so have much
+lower overhead. They are typical run by using ``./mach xpcshell-test``
+which initiates a new ``xpcshell`` session with
+the xpcshell testing harness. Anything available to the XPCOM layer
+(through scriptable interfaces) can be tested with xpcshell. See
+``Mozilla automated testing`` and ``pages
+tagged "automated testing"`` for more
+information.
+
+Introducing xpcshell testing
+----------------------------
+
+xpcshell test filenames must start with ``test_``.
+
+Creating a new test directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to create a new test directory, then follow the steps here.
+The test runner needs to know about the existence of the tests and how
+to configure them through the use of the ``xpcshell.ini`` manifest file.
+
+First add a ``XPCSHELL_TESTS_MANIFESTS += ['xpcshell.ini']`` declaration
+(with the correct relative ``xpcshell.ini`` path) to the ``moz.build``
+file located in or above the directory.
+
+Then create an empty ``xpcshell.ini`` file to tell the build system
+about the individual tests, and provide any additional configuration
+options.
+
+Creating a new test in an existing directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you're creating a new test in an existing directory, you can simply
+run:
+
+.. code:: bash
+
+   $ ./mach addtest path/to/test/test_example.js
+   $ hg add path/to/test/test_example.js
+
+This will automatically create the test file and add it to
+``xpcshell.ini``, the second line adds it to your commit.
+
+The test file contains an empty test which will give you an idea of how
+to write a test. There are plenty more examples throughout
+mozilla-central.
+
+Running tests
+-------------
+
+To run the test, execute it by running the ``mach`` command from the
+root of the Gecko source code directory.
+
+.. code:: bash
+
+   # Run a single test:
+   $ ./mach xpcshell-test path/to/tests/test_example.js
+
+   # Test an entire test suite in a folder:
+   $ ./mach xpcshell-test path/to/tests/
+
+   # Or run any type of test, including both xpcshell and browser chrome tests:
+   $ ./mach test path/to/tests/test_example.js
+
+The test is executed by the testing harness. It will call in turn:
+
+-  ``run_test`` (if it exists).
+-  Any functions added with ``add_task`` or ``add_test`` in the order
+   they were defined in the file.
+
+See also the notes below around ``add_task`` and ``add_test``.
+
+xpcshell Testing API
+--------------------
+
+xpcshell tests have access to the following functions. They are defined
+in
+:searchfox:`testing/xpcshell/head.js <testing/xpcshell/head.js>`
+and
+:searchfox:`testing/modules/Assert.sys.mjs <testing/modules/Assert.sys.mjs>`.
+
+Assertions
+^^^^^^^^^^
+
+- ``Assert.ok(truthyOrFalsy[, message])``
+- ``Assert.equal(actual, expected[, message])``
+- ``Assert.notEqual(actual, expected[, message])``
+- ``Assert.deepEqual(actual, expected[, message])``
+- ``Assert.notDeepEqual(actual, expected[, message])``
+- ``Assert.strictEqual(actual, expected[, message])``
+- ``Assert.notStrictEqual(actual, expected[, message])``
+- ``Assert.rejects(actual, expected[, message])``
+- ``Assert.greater(actual, expected[, message])``
+- ``Assert.greaterOrEqual(actual, expected[, message])``
+- ``Assert.less(actual, expected[, message])``
+- ``Assert.lessOrEqual(actual, expected[, message])``
+
+
+These assertion methods are provided by
+:searchfox:`testing/modules/Assert.sys.mjs <testing/modules/Assert.sys.mjs>`.
+It implements the `CommonJS Unit Testing specification version
+1.1 <http://wiki.commonjs.org/wiki/Unit_Testing/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. You can on all these methods remove the
+``Assert.`` from the beginning of the name, e.g. ``ok(true)`` rather
+than ``Assert.ok(true)``, however keeping the ``Assert.`` prefix may
+be seen as more descriptive and easier to spot where the tests are.
+``Assert.throws(callback, expectedException[, message])``
+``Assert.throws(callback[, message])``
+Asserts that the provided callback function throws an exception. The
+``expectedException`` argument can be an ``Error`` instance, or a
+regular expression matching part of the error message (like in
+``Assert.throws(() => a.b, /is not defined/``).
+``Assert.rejects(promise, expectedException[, message])``
+Asserts that the provided promise is rejected. Note: that this should
+be called prefixed with an ``await``. The ``expectedException``
+argument can be an ``Error`` instance, or a regular expression
+matching part of the error message. Example:
+``await Assert.rejects(myPromise, /bad response/);``
+
+Test case registration and execution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``add_task([condition, ]testFunc)``
+   Add an asynchronous function or to the list of tests that are to be
+   run asynchronously. Whenever the function ``await``\ s a
+   `Promise </en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm>`__,
+   the test runner waits until the promise is resolved or rejected
+   before proceeding. Rejected promises are converted into exceptions,
+   and resolved promises are converted into values.
+   You can optionally specify a condition which causes the test function
+   to be skipped; see `Adding conditions through the add_task or
+   add_test
+   function <#adding-conditions-through-the-add-task-or-add-test-function>`__
+   for details.
+   For tests that use ``add_task()``, the ``run_test()`` function is
+   optional, but if present, it should also call ``run_next_test()`` to
+   start execution of all asynchronous test functions. The test cases
+   must not call ``run_next_test()``, it is called automatically when
+   the task finishes. See `Async tests <#async-tests>`__, below, for
+   more information.
+``add_test([condition, ]testFunction)``
+   Add a test function to the list of tests that are to be run
+   asynchronously.
+   You can optionally specify a condition which causes the test function
+   to be skipped; see `Adding conditions through the add_task or
+   add_test
+   function <#adding-conditions-through-the-add-task-or-add-test-function>`__
+   for details.
+   Each test function must call ``run_next_test()`` when it's done. For
+   tests that use ``add_test()``, ``the run_test()`` function is
+   optional, but if present, it should also call ``run_next_test()`` to
+   start execution of all asynchronous test functions. In most cases,
+   you should rather use the more readable variant ``add_task()``. See
+   `Async tests <#async-tests>`__, below, for more information.
+``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 call ``run_next_test()`` to start
+   execution of all asynchronous test functions. See `Async
+   tests <#async-tests>`__, below, for more information.
+**``registerCleanupFunction``**\ ``(callback)``
+   Executes the function ``callback`` after the current JS test file has
+   finished running, regardless of whether the tests inside it pass or
+   fail. You can use this to clean up anything that might otherwise
+   cause problems between test runs.
+   If ``callback`` returns a ``Promise``, the test will not finish until
+   the promise is fulfilled or rejected (making the termination function
+   asynchronous).
+   Cleanup functions are called in reverse order of registration.
+``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.
+
+Environment
+^^^^^^^^^^^
+
+``do_get_file(testdirRelativePath, allowNonexistent)``
+   Returns an ``nsILocalFile`` object 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 call ``do_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::
+
+      **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 specify
+      ``XPCSHELL_TESTS``. For an example, see
+      ``netwerk/test/Makefile.in#117``.
+``do_get_profile()``
+   Registers a directory with the profile service and returns an
+   ``nsILocalFile`` object representing that directory. It also makes
+   sure that the **profile-change-net-teardown**,
+   **profile-change-teardown**, and **profile-before-change** `observer
+   notifications </en/Observer_Notifications#Application_shutdown>`__
+   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).
+
+   .. note::
+
+      **Note:** ``do_register_cleanup`` will perform any cleanup
+      operation *before* the profile and the network is shut down by the
+      observer notifications.
+``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 ``nsILocalFile`` object 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 ``testdirRelativePath``
+   into 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 by
+   calling ``load('extra_helpers.js')``.
+
+Utility
+^^^^^^^
+
+``do_parse_document(path, type)``
+   Parses and returns a DOM document.
+``executeSoon(callback)``
+   Executes the function ``callback`` on 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 a
+   ``do_test_pending`` / ``do_test_finished`` pair 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_pending`` so that
+   the test isn't completed before your timer fires, and you must call
+   ``do_test_finished`` when 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.)
+
+Multiprocess communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``do_send_remote_message(name, optionalData)``
+   Asynchronously send a message to all remote processes. Pairs with
+   ``do_await_remote_message`` or equivalent ProcessMessageManager
+   listeners.
+``do_await_remote_message(name, optionalCallback)``
+   Returns a promise that is resolved when the message is received. Must
+   be paired with\ ``do_send_remote_message`` or equivalent
+   ProcessMessageManager calls. If **optionalCallback** is provided, the
+   callback must call ``do_test_finished``. If optionalData is passed
+   to ``do_send_remote_message`` then that data is the first argument to
+   **optionalCallback** or the value to which the promise resolves.
+
+
+xpcshell.ini manifest
+---------------------
+
+The manifest controls what tests are included in a test suite, and the
+configuration of the tests. It is loaded via the \`moz.build\` property
+configuration property.
+
+The following are all of the configuration options for a test suite as
+listed under the ``[DEFAULT]`` section of the manifest.
+
+``tags``
+   Tests can be filtered by tags when running multiple tests. The
+   command for mach is ``./mach xpcshell-test --tag TAGNAME``
+``head``
+   The relative path to the head JavaScript file, which is run once
+   before a test suite is run. The variables declared in the root scope
+   are available as globals in the test files. See `Test head and
+   support files <#test-head-and-support-files>`__ for more information
+   and usage.
+``firefox-appdir``
+   Set this to "browser" if your tests need access to things in the
+   browser/ directory (e.g. additional XPCOM services that live there)
+``skip-if`` ``run-if`` ``fail-if``
+   For this entire test suite, run the tests only if they meet certain
+   conditions. See `Adding conditions in the xpcshell.ini
+   manifest <#adding-conditions-through-the-add-task-or-add-test-function>`__ for how
+   to use these properties.
+``support-files``
+   Make files available via the ``resource://test/[filename]`` path to
+   the tests. The path can be relative to other directories, but it will
+   be served only with the filename. See `Test head and support
+   files <#test-head-and-support-files>`__ for more information and
+   usage.
+``[test_*]``
+   Test file names must start with ``test_`` and are listed in square
+   brackets
+
+
+Creating a new xpcshell.ini file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When creating a new directory and new xpcshell.ini manifest file, the
+following must be added to a moz.build file near that file in the
+directory hierarchy:
+
+.. code:: bash
+
+   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:
+
+.. code:: bash
+
+   feature
+   ├──moz.build
+   └──tests/xpcshell
+      └──xpcshell.ini
+
+   # or
+
+   feature
+   ├──moz.build
+   └──tests
+      ├──moz.build
+      └──xpcshell
+         └──xpcshell.ini
+
+
+Test head and support files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Typically in a test suite, similar setup code and dependencies will need
+to be loaded in across each test. This can be done through the test
+head, which is the file declared in the ``xpcshell.ini`` manifest file
+under the ``head`` property. The file itself is typically called
+``head.js``. Any variable declared in the test head will be in the
+global scope of each test in that test suite.
+
+In addition to the test head, other support files can be declared in the
+``xpcshell.ini`` manifest file. This is done through the
+``support-files`` declaration. These files will be made available
+through the url ``resource://test`` plus the name of the file. These
+files can then be loaded in using the
+``ChromeUtils.import`` function
+or other loaders. The support files can be located in other directory as
+well, and they will be made available by their filename.
+
+.. code:: bash
+
+   # File structure:
+
+   path/to/tests
+   ├──head.js
+   ├──module.jsm
+   ├──moz.build
+   ├──test_example.js
+   └──xpcshell.ini
+
+.. code:: ini
+
+   # xpcshell.ini
+   [DEFAULT]
+   head = head.js
+   support-files =
+     ./module.jsm
+     ../../some/other/file.js
+   [test_component_state.js]
+
+.. code:: js
+
+   // head.js
+   var globalValue = "A global value.";
+
+   // Import support-files.
+   const { foo } = ChromeUtils.import("resource://test/module.jsm");
+   const { bar } = ChromeUtils.import("resource://test/file.jsm");
+
+.. code:: js
+
+   // test_example.js
+   function run_test() {
+     equal(globalValue, "A global value.", "Declarations in head.js can be accessed");
+   }
+
+
+Additional testing considerations
+---------------------------------
+
+Async tests
+^^^^^^^^^^^
+
+Asynchronous tests (that is, those whose success cannot be determined
+until after ``run_test`` finishes) can be written in a variety of ways.
+
+Task-based asynchronous tests
+-----------------------------
+
+The easiest is using the ``add_task`` helper. ``add_task`` can take an
+asynchronous function as a parameter. ``add_task`` tests are run
+automatically if you don't have a ``run_test`` function.
+
+.. code:: js
+
+   add_task(async function test_foo() {
+     let foo = await makeFoo(); // makeFoo() returns a Promise<foo>
+     equal(foo, expectedFoo, "Should have received the expected object");
+   });
+
+   add_task(async function test_bar() {
+     let foo = await makeBar(); // makeBar() returns a Promise<bar>
+     Assert.equal(bar, expectedBar, "Should have received the expected object");
+   });
+
+Callback-based asynchronous tests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also use ``add_test``, which takes a function and adds it to the
+list of asynchronously-run functions. Each function given to
+``add_test`` must also call ``run_next_test`` at its end. You should
+normally use ``add_task`` instead of ``add_test``, but you may see
+``add_test`` in existing tests.
+
+.. code:: js
+
+   add_test(function test_foo() {
+     makeFoo(function callback(foo) { // makeFoo invokes a callback<foo> once completed
+       equal(foo, expectedFoo);
+       run_next_test();
+     });
+   });
+
+   add_test(function test_bar() {
+     makeBar(function callback(bar) {
+       equal(bar, expectedBar);
+       run_next_test();
+     });
+   });
+
+
+Other tests
+^^^^^^^^^^^
+
+We can also 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. Newer tests
+prefer the use of ``add_task`` rather than this method. This can be
+achieved with ``do_test_pending()`` and ``do_test_finished()``:
+
+.. code:: js
+
+   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();
+     });
+   }
+
+
+Testing in child processeses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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. Use
+`AppConstants.jsm <https://searchfox.org/mozilla-central/rev/a0333927deabfe980094a14d0549b589f34cbe49/toolkit/modules/AppConstants.jsm#148>`__
+for determining the platform, for example:
+
+.. code:: js
+
+   ChromeUtils.import("resource://gre/modules/AppConstants.jsm");
+
+   let isMac = AppConstants.platform == "macosx";
+
+
+Conditionally running a test
+----------------------------
+
+There are two different ways to conditional skip a test, either through
+
+
+Adding conditions through the ``add_task`` or ``add_test`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use conditionals on individual test functions instead of entire
+files. The condition is provided as an optional first parameter passed
+into ``add_task()`` or ``add_test()``. The condition is an object which
+contains a function named ``skip_if()``, which is an `arrow
+function </en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions>`__
+returning a boolean value which is **``true``** if the test should be
+skipped.
+
+For example, you can provide a test which only runs on Mac OS X like
+this:
+
+.. code:: js
+
+   ChromeUtils.import("resource://gre/modules/AppConstants.jsm");
+
+   add_task({
+     skip_if: () => AppConstants.platform != "mac"
+   }, async function some_test() {
+     // Test code goes here
+   });
+
+Since ``AppConstants.platform != "mac"`` is ``true`` only when testing
+on Mac OS X, the test will be skipped on all other platforms.
+
+.. note::
+
+   **Note:** Arrow functions are ideal here because if your condition
+   compares constants, it will already have been evaluated before the
+   test is even run, meaning your output will not be able to show the
+   specifics of what the condition is.
+
+
+Adding conditions in the xpcshell.ini manifest
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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:
+
+.. code:: ini
+
+   [test_example.js]
+   skip-if = os == 'win'
+
+This example would skip running ``test_example.js`` on Windows.
+
+.. note::
+
+   **Note:** Starting with Gecko (Firefox 40 / Thunderbird 40 /
+   SeaMonkey 2.37), you can use conditionals on individual test
+   functions instead of on entire files. See `Adding conditions through
+   the add_task or add_test
+   function <#adding-conditions-through-the-add-task-or-add-test-function>`__
+   above for details.
+
+There are currently four 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:
+
+.. code:: ini
+
+   [test_example.js]
+   # bug xxxxxx
+   fail-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:
+
+.. code:: ini
+
+   [test_example.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 </en/XPCshell_Test_Manifest_Expressions`.
+
+
+Running a specific test only
+----------------------------
+
+When working on a specific feature or issue, it is convenient to only
+run a specific task from a whole test suite. Use ``.only()`` for that
+purpose:
+
+.. code:: js
+
+   add_task(async function some_test() {
+     // Some test.
+   });
+
+   add_task(async function some_interesting_test() {
+   // Only this test will be executed.
+   }).only();
+
+
+Problems with pending events and shutdown
+-----------------------------------------
+
+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:
+
+.. code:: js
+
+   let thread = gThreadManager.currentThread;
+   while (thread.hasPendingEvents())
+     thread.processNextEvent(true);
+
+
+Debugging xpcshell-tests
+------------------------
+
+
+Running unit tests under the javascript debugger
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Via --jsdebugger
+^^^^^^^^^^^^^^^^
+
+You can specify flags when issuing the ``xpcshell-test`` command that
+will cause your test to stop right before running so you can attach the
+`javascript debugger </docs/Tools/Tools_Toolbox>`__.
+
+Example:
+
+.. code:: bash
+
+   $ ./mach xpcshell-test --jsdebugger browser/components/tests/unit/test_browserGlue_pingcentre.js
+    0:00.50 INFO Running tests sequentially.
+   ...
+    0:00.68 INFO ""
+    0:00.68 INFO "*******************************************************************"
+    0:00.68 INFO "Waiting for the debugger to connect on port 6000"
+    0:00.68 INFO ""
+    0:00.68 INFO "To connect the debugger, open a Firefox instance, select 'Connect'"
+    0:00.68 INFO "from the Developer menu and specify the port as 6000"
+    0:00.68 INFO "*******************************************************************"
+    0:00.68 INFO ""
+    0:00.71 INFO "Still waiting for debugger to connect..."
+   ...
+
+At this stage in a running Firefox instance:
+
+-  Go to the three-bar menu, then select ``More tools`` ->
+   ``Remote Debugging``
+-  A new tab is opened. In the Network Location box, enter
+   ``localhost:6000`` and select ``Connect``
+-  You should then get a link to *``Main Process``*, click it and the
+   Developer Tools debugger window will open.
+-  It will be paused at the start of the test, so you can add
+   breakpoints, or start running as appropriate.
+
+If you get a message such as:
+
+::
+
+    0:00.62 ERROR Failed to initialize debugging: Error: resource://devtools appears to be inaccessible from the xpcshell environment.
+   This can usually be resolved by adding:
+     firefox-appdir = browser
+   to the xpcshell.ini manifest.
+   It is possible for this to alter test behevior by triggering additional browser code to run, so check test behavior after making this change.
+
+This is typically a test in core code. You can attempt to add that to
+the xpcshell.ini, however as it says, it might affect how the test runs
+and cause failures. Generally the firefox-appdir should only be left in
+xpcshell.ini for tests that are in the browser/ directory, or are
+Firefox-only.
+
+
+Running unit tests under a C++ debugger
+---------------------------------------
+
+
+Via ``--debugger and -debugger-interactive``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can specify flags when issuing the ``xpcshell-test`` command that
+will launch xpcshell in the specified debugger (implemented in
+`bug 382682 <https://bugzilla.mozilla.org/show_bug.cgi?id=382682>`__).
+Provide the full path to the debugger, or ensure that the named debugger
+is in your system PATH.
+
+Example:
+
+.. code:: bash
+
+   $ ./mach xpcshell-test --debugger gdb --debugger-interactive netwerk/test/unit/test_resumable_channel.js
+   # js>_execute_test();
+   ...failure or success messages are printed to the console...
+   # js>quit();
+
+On Windows with the VS debugger:
+
+.. code:: bash
+
+   $ ./mach xpcshell-test --debugger devenv --debugger-interactive netwerk/test/test_resumable_channel.js
+
+Or with WinDBG:
+
+.. code:: bash
+
+   $ ./mach xpcshell-test --debugger windbg --debugger-interactive netwerk/test/test_resumable_channel.js
+
+Or with modern WinDbg (WinDbg Preview as of April 2020):
+
+.. code:: bash
+
+   $ ./mach xpcshell-test --debugger WinDbgX --debugger-interactive netwerk/test/test_resumable_channel.js
+
+
+Debugging xpcshell tests in a child process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To debug the child process, where code is often being run in a project,
+set MOZ_DEBUG_CHILD_PROCESS=1 in your environment (or on the command
+line) and run the test. 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:
+
+.. code:: bash
+
+   $ MOZ_DEBUG_CHILD_PROCESS=1 ./mach xpcshell-test test_simple_wrap.js
+   CHILDCHILDCHILDCHILD
+     debug me @13476
+
+
+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.)