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.
MozITP depends on Vagrant and Virtualbox.
By default, VM in VirtualBox will enable VT-x/AMD-V and Nested Paging, so you have to enable 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.
- 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.
- 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 the BIOS.
- 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 the BIOS.
- If your VirtualBox VM failed to start, try enabling Hyper-V in VirtualBox > Settings > System > Accleration > Paravirtualization Interface.
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.
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
And you can run git pull
to get the latest version of this repo.
Now you've set up the environment and cloned the repo, you can start using MozITP.
Note: The following commands should be run from inside the MozITP directory.
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
Launch MozITP with the following command:
$ ./launch.sh
At this point a Vagrant VM will be launched โ you should see something like this:
To stop the VM, running the following:
$ ./bin/stop.sh
To reset the VM to the factory defaults, run this command:
$ ./bin/reset_vm.sh
To update to the latest version of the VM, run the following:
$ ./bin/update_vm.sh
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.
Warning: Sometimes the test case itself has bugs, which makes the GIJ test fail. To verify if it's a GIJ platform bug or a test case bug, run
./test/gij_phone_mulet_sanity_test.sh
or./test/gij_phone_device_sanity_test.sh
files, depending on whether you are running the tests on Mulet or a real device. If it passes, it could be a bug in the test case, not the platform.
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
To run GIJ directly on the device. The device must be connected through USB before you run the command:
$ ./launch.sh gij device
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
$ vagrant ssh -c "rm ~/.users_gaia_exists" # Remove the flag
$ ./bin/stop.sh # Restart the VM
$ ./launch.sh
To run GIJ on TV mulet, run the following:
$ ./launch.sh gij-tv
See Supported Platforms section for available targets.
To run GIP, do the following:
$ ./launch.sh gip
The MozCingi, fuzz testing of B2G.
To run fuzz testing, do the following:
$ ./launch.sh fuzz <testcases.zip>
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.
You can put files/folders into shared folder.
- The shared folder will be pushed from host into VM when you run
./launch.sh
. - The shared folder will be pulled from VM to host when you exit the
./launch.sh
script, or when run./bin/stop.sh
.
The following table contains a summary of the commands:
Command | From | To |
---|---|---|
run ./launch.sh |
host | VM |
exit ./launch.sh |
VM | host |
run ./bin/stop.sh |
VM | host |
- To run
launch.sh
in jenkins or over SSH, usexvfb-run ./launch.sh
, otherwise thevagrant 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.
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:
Platform | GIJ | GIP | Fuzz |
---|---|---|---|
Phone Mulet | OK (headless) | OK | OK |
Phone Device | OK | OK | OK |
Phone Emulator | Too slow | by request* | by request* |
TV Mulet | OK | by request* | by request* |
TV Device | by request* | by request* | by request* |
TV Emulator | by request* | by request* | by request* |
* This combination doesn't currently work. If you need it/want to help with getting it running, please file a bug or email us.