The Mozilla integrated tools package

The Mozilla integrated tools package (MozITP) is a one-stop shop for setting up Firefox OS-related tools, which can handle automatic Testing on Mulet or a real device, flashing TaskCluster images, flashing with the B2G installer add-on, and running the TV and phone versions of Mulet. This article details how the toools package works, and how it can be installed.

Environment setup

MozITP depends on Vagrant and Virtualbox. By default, VMs in VirtualBox will automartically enable VT-x/AMD-V and Nested Paging, so you should enable the VT-x/AMD-V feature of your host.

Let's look at how to set up the environment on Linux, Mac OS X, and Windows.

Ubuntu

• Download Vagrant's Debian package.
• Install Vagrant using this:

  $ sudo dpkg -i <PATH_TO_PKG_FILE>

• Install VirtualBox using this:

  $ sudo apt-get install virtualbox virtualbox-dkms virtualbox-qt

• Reboot your computer after the Virtualbox installation has finished.
• Download and install the VirtualBox Extension Pack.
• Set up the USB for VirtualBox using the following command:

  $ sudo adduser <USERNAME> vboxusers

• Re-login or restart your computer.
• Make sure you enable Intel VT-x and VT-d in the BIOS.

Mac OS X

• Install Brew Cask.
• Install Vagrant using this:

  $ sudo brew cask install vagrant; sudo brew cask install vagrant-manager

• Install VirtualBox using this:

  $ sudo brew cask install virtualbox

• Install the VirtualBox Extension Pack using the following:

  $ sudo brew cask install virtualbox-extension-pack

• Make sure you enable Intel VT-x and VT-d in BIOS.

Windows (experimental)

• Install the Windows version of Git. Make sure that you don't let Git change the line ending symbol to windows format.
• Install the Windows bash shell.
• Install Vagrant for Windows.
• Install Virtualbox for Windows.
• Run launch.sh in PowerShell or git-bash.
• Make sure you enable Intel VT-x and VT-d in your computer's BIOS.
• If your VirtualBox VM failed to start, try enabling Hyper-V in VirtualBox > Settings > System > Accleration > Paravirtualization Interface.

Other Platforms

Whatever the case, you need to install Vagrant — see the Installing Vagrant guide for more details.

You also need to install a VM provider for Vagrant. We are assuming the use of VirtualBox throughout our article.

Cloning the Repo

After the environment has been set up, you need to clone the MozITP repo. Do so with the following command:

$ git clone https://github.com/mozilla-b2g/MozITP.git

You can run git pull at any time to get the latest version of the repo.

Usage

Now you've set up the environment and cloned the repo, you can start using MozITP.

Setting permissions

If you get any problems running the scripts, you need to make sure you have the necessary permissions set on the commands. Add execute permissions, for example:

$ chmod u+x launch.sh

Launching the MozITP

Launch MozITP with the following command:

$ ./launch.sh

At this point a Vagrant VM will be launched — you should see something like this:

Stopping MozITP

To stop the VM, running the following:

$ ./bin/stop.sh

Resetting to factory

To reset the VM to the factory defaults, run this command:

$ ./bin/reset_vm.sh

Updating the VM

To update to the latest version of the VM, run the following:

$ ./bin/update_vm.sh

GIJ (Gaia Integration Test / JS Marionette)

You can run the GIJ (Gaia integration tests in JavaScript) directly from inside MozITP, which is very useful for automation. See the Supported Platforms section for available targets.

Running GIJ

To run GIJ directly, run the following:

$ ./launch.sh gij

To run GIJ just on a specific app, you'll need a command structure like the following:

$ export APP=video; ./launch.sh gij # The `export` is important, don't miss it

To run GIJ on a specific test file:

export TEST_FILES=apps/clock/test/marionette/hour_format_test.js 
./launch.sh gij

Running GIJ directly on a device

To run GIJ directly on the device. The device must be connected through USB before you run the command

$ ./launch.sh gij device

Running GIJ with your own Gaia build

If you already have a Gaia repository you want to test, you can use the following commands:

export GAIA=/path/to/your/gaia
./launch.sh

If you change your mind and want to use the latest Gaia instead, you can do this:

./reset_vm.sh
unset GAIA
./launch.sh

Or if you want to keep the VM, you can do this:

unset GAIA
./launch.sh
# Remove the flag
vagrant ssh -c "rm ~/.users_gaia_exists"
# Restart the VM
./bin/stop.sh
./launch.sh

GIP (Python Gaia Integration Test)

See the Supported Platforms section for available targets.

Running GIP

To run GIP, do the following:

./launch.sh gip 

Flashing

Let's look at how to flash a TaskCluster image onto your instance of MozITP.

If you already have TaskCluster credentials:

• For flashing the TaskCluster image (needs credentials), please run ./bin/get_credentials.sh before flashing. 
• Next, run launch.sh and select Flashing B2G Image.
• Or just run ./launch.sh flash.

If you don't have TaskCluster credentials:

• You can use the B2G installer add-on to handle this.
• Run ./launch.sh and select Enter Firefox b2g-installer Add-on from the menu.

Shared Folder

You can put files/folders into the shared folder.

• The shared folder will be pushed from the host to the VM when you run ./launch.sh.
• The shared folder will be pulled from the VM to the host when you exit the launch.sh script, or when running ./bin/stop.sh.

The following table contains a summary of the commands:

Troubleshooting

• To run launch.sh in Jenkins or over SSH, use xvfb-run ./launch.sh, otherwise the vagrant up command will fail.
• To run tests on a device connected via USB device, you need to first add the user to the vboxusers group using the following command structure:

  $ sudo adduser <your username> vboxusers

• If you want to run tests against USB-connected devices in Jenkins, also add the jenkins user to the vboxusers group.

Supported Platforms

The following platforms are supported by MozITP:

• Linux
• OS X
• Windows (experimental)
• Flashable devices: Aries (Sony Z3C), Flame

The following table shows the different environments that can be tested/emulated by MozITP, and how well specific tests currently work on those environments:

* This combination doesn't currently work. If you need it/want to help with getting it running, please file a bug or email us on the dev-fxos mailing list.

See Also

The MozITP main repository