• Skip to main content
  • Select language
  • Skip to search
MDN Web Docs
  • Technologies
    • HTML
    • CSS
    • JavaScript
    • Graphics
    • HTTP
    • APIs / DOM
    • WebExtensions
    • MathML
  • References & Guides
    • Learn web development
    • Tutorials
    • References
    • Developer Guides
    • Accessibility
    • Game development
    • ...more docs
B2G OS
  1. MDN
  2. Archive of obsolete content
  3. B2G OS
  4. Automated Testing of B2G OS
  5. XPCShell

XPCShell

In This Article
  1. The Recommended Way
    1. Prerequisites
    2. Running the tests
  2.  
  3. The Hard Way
    1. Prerequisites
    2. Running the tests
      1. Installing busybox manually
    3. Running xpcshell tests with a downloaded emulator

XPCShell tests are headless tests of Gecko XPCOM APIs. You can run XPCShell tests on B2G; in this article we will look at how to do so. Currently, these are mainly tested on the emulator, but should in theory run on devices as well.

Note: In this article $B2G_HOME refers to the cloned B2G repository.

The Recommended Way

The easiest way to run xpcshell tests on B2G is using mach.

Prerequisites

  • You need to build B2G for the target you're testing (see: Building and installing Firefox OS). Currently only emulator builds are supported, though other devices may work.
  • Make sure adb is on your path. If you have a build, this can be found at $B2G_HOME/out/host/<platform>/bin.

Running the tests

To run the full suite of tests, build B2G and then:

cd $B2G_HOME
./mach xpcshell-test

To run a specific test, or a directory containing tests:

./mach xpcshell-test path/to/test/or/directory

If a directory is specified, it will be searched recursively for test files. To see other options:

./mach xpcshell-test --help

 

The Hard Way

If for some reason you can't or don't wish to use the mach command, you can try running the harness directly. This method is not recommended as it can be tricky to get right.

Prerequisites

  • You need to build B2G for the target you're testing (see: Building and installing Firefox OS). Currently only emulator builds are supported, though other devices may work.
  • You need to install some Python packages, either in a virtualenv or otherwise:
    cd $GECKO_DIR/testing/mozbase
    python setup_development.py
    cd $GECKO_DIR/testing/marionette/client
    python setup.py develop
    
  • Either make sure adb is on your path or specify it with --adbpath (on Linux it is found at $B2G_HOME/out/host/linux-x86/bin/adb.)
  • Have a local copy of Busybox (this isn't strictly necessary but greatly reduces the setup time required.)

Running the tests

You can then run xpcshell tests using one of the following sets of terminal commands:

If you are using an emulator:

cd $B2G_HOME/objdir-gecko
make package-tests
cd dist/test-stage/xpcshell
python runtestsb2g.py --b2gpath $B2G_HOME --adbpath $ADB_PATH --emulator arm --use-device-libs --manifest <path_to_xpcshell_manifest> --testing-modules-dir <path_to_testing_modules_dir> --busybox <path_to_busybox_binary>

If you are using a real device:

cd $B2G_HOME/objdir-gecko
make package-tests
cd dist/test-stage/xpcshell
python runtestsb2g.py --b2gpath $B2G_HOME --adbpath $ADB_PATH --use-device-libs --manifest <path_to_xpcshell_manifest> --testing-modules-dir <path_to_testing_modules_dir>

You can optionally add --total-chunks and --this-chunks arguments as you would with regular desktop xpcshell tests. Use:

python runtestsb2g.py --help

for a full list of supported arguments.

Important: The manifest path you supply must be under the dist/test-stage/xpcshell directory. Don't use a path to the original source location of the manifest in the tree.

After you invoke runtestsb2g.py, the test runner will launch the emulator for you (if you're running the tests on an emulator) or reboot your device (if you're running the tests on a device), and start running the tests. Because the emulator is slow, and it is necessary to push a test profile to the emulator and restart B2G, the tests can take a few minutes to start. Before they start, you will just see a black or white screen. After they start, you should see the test log being dumped to the console.

When the tests are done, the emulator is shut down for you, or if you're using a device, the device is rebooted.

Installing busybox manually

When running xpcshell tests on devices there is no --busybox option, so setting up the test run can take a very long time. Fortunately you can still install it manually prior to running the tests. For an example of how to do this see https://github.com/mozilla/Negatus/blob/master/setup-tools.sh.

Running xpcshell tests with a downloaded emulator

If you've built B2G for another config (like otoro) and want to run the tests on an emulator, you can do so without building an emulator yourself.  Just download the latest trunk arm emulator, and use the same instructions as above, replacing the --b2gpath $B2G_HOME argument for runreftestb2g.py with --b2gpath /path/to/unpacked/emulator.

Document Tags and Contributors

Tags: 
  • automated
  • Firefox OS
  • Gaia
  • Guide
  • tests
  • XPCOM
  • XPCShell
 Contributors to this page: chrisdavidmills, ahal, jgriffin, jryans, Changbin, gsvelto, teoli, kscarfone, mdas, ethertank, Sheppy
 Last updated by: chrisdavidmills, Feb 27, 2017, 3:02:09 AM
See also
  1. Build and install
    1. Build and install overview
    2. B2G OS build process summary
    3. Build prerequisites
    4. Preparing for your first build
    5. Building B2G OS
    6. B2G installer add-on
    7. Building B2G OS for Flame on Mac OS X
    8. Choosing how to run Gaia or B2G OS
    9. Compatible Devices
    10. Installing B2G OS on a mobile device
    11. Creating and applying B2G OS update packages
    12. Building and installing FOTA community builds
    13. B2G build variables reference sheet
  2. Porting B2G OS
    1. Porting overview
    2. Porting basics
    3. Porting on CyanogenMod
  3. Developing Gaia
    1. Developing Gaia overview
    2. Running the Gaia codebase
    3. Run Gaia on desktop using Mulet
    4. Understanding the Gaia codebase
    5. Making Gaia code changes
    6. Testing Gaia code changes
    7. Submitting a Gaia patch
    8. Gaia build system primer
    9. Different ways to run Gaia
    10. Make options reference
    11. Gaia tools reference
  4. B2G OS APIs