`mozrunner` — Manage remote and local gecko processes¶

Mozrunner provides an API to manage a gecko-based application with an arbitrary configuration profile. It currently supports local desktop binaries such as Firefox and Thunderbird, as well as Firefox OS on mobile devices and emulators.

Basic usage¶

The simplest way to use mozrunner, is to instantiate a runner, start it and then wait for it to finish:

from mozrunner import FirefoxRunner
binary = 'path/to/firefox/binary'
runner = FirefoxRunner(binary=binary)
runner.start()
runner.wait()

This automatically creates and uses a default mozprofile object. If you wish to use a specialized or pre-existing profile, you can create a mozprofile object and pass it in:

from mozprofile import FirefoxProfile
from mozrunner import FirefoxRunner
import os

binary = 'path/to/firefox/binary'
profile_path = 'path/to/profile'
if os.path.exists(profile_path):
    profile = FirefoxProfile.clone(path_from=profile_path)
else:
    profile = FirefoxProfile(profile=profile_path)
runner = FirefoxRunner(binary=binary, profile=profile)
runner.start()
runner.wait()

Handling output¶

By default, mozrunner dumps the output of the gecko process to standard output. It is possible to add arbitrary output handlers by passing them in via the process_args argument. Be careful, passing in a handler overrides the default behaviour. So if you want to use a handler in addition to dumping to stdout, you need to specify that explicitly. For example:

from mozrunner import FirefoxRunner

def handle_output_line(line):
    do_something(line)

binary = 'path/to/firefox/binary'
process_args = { 'stream': sys.stdout,
                 'processOutputLine': [handle_output_line] }
runner = FirefoxRunner(binary=binary, process_args=process_args)

Mozrunner uses mozprocess to manage the underlying gecko process and handle output. See the mozprocess documentation for all available arguments accepted by process_args.

Handling timeouts¶

Sometimes gecko can hang, or maybe it is just taking too long. To handle this case you may want to set a timeout. Mozrunner has two kinds of timeouts, the traditional timeout, and the outputTimeout. These get passed into the runner.start() method. Setting timeout will cause gecko to be killed after the specified number of seconds, no matter what. Setting outputTimeout will cause gecko to be killed after the specified number of seconds with no output. In both cases the process handler’s onTimeout callbacks will be triggered.

from mozrunner import FirefoxRunner

def on_timeout():
    print('timed out after 10 seconds with no output!')

binary = 'path/to/firefox/binary'
process_args = { 'onTimeout': on_timeout }
runner = FirefoxRunner(binary=binary, process_args=process_args)
runner.start(outputTimeout=10)
runner.wait()

The runner.wait() method also accepts a timeout argument. But unlike the arguments to runner.start(), this one simply returns from the wait call and does not kill the gecko process.

runner.start(timeout=100)

waiting = 0
while runner.wait(timeout=1) is None:
    waiting += 1
    print("Been waiting for %d seconds so far.." % waiting)
assert waiting <= 100

Using a device runner¶

The previous examples used a GeckoRuntimeRunner. If you want to control a gecko process on a remote device, you need to use a DeviceRunner. The api is nearly identical except you don’t pass in a binary, instead you create a device object. For example, for B2G (Firefox OS) emulators you might do:

from mozrunner import B2GEmulatorRunner

b2g_home = 'path/to/B2G'
runner = B2GEmulatorRunner(arch='arm', b2g_home=b2g_home)
runner.start()
runner.wait()

Device runners have a device object. Remember that the gecko process runs on the device. In the case of the emulator, it is possible to start the device independently of the gecko process.

runner.device.start() # launches the emulator (which also launches gecko)
runner.start()        # stops the gecko process, installs the profile, restarts the gecko process

Runner API Documentation¶

Application Runners¶

This module contains a set of shortcut methods that create runners for commonly used Mozilla applications, such as Firefox or B2G emulator.

mozrunner.runners.B2GDesktopRunner(*args, **kwargs)¶

Create a B2G desktop runner.

Parameters:

binary – Path to b2g desktop binary.
cmdargs – Arguments to pass into binary.
profile – Profile object to use.
env – Environment variables to pass into the gecko process.
clean_profile – If True, restores profile back to original state.
process_class – Class used to launch the binary.
process_args – Arguments to pass into process_class.
symbols_path – Path to symbol files used for crash analysis.
show_crash_reporter – allow the crash reporter window to pop up. Defaults to False.

Returns:

A GeckoRuntimeRunner for b2g desktop.

mozrunner.runners.B2GDeviceRunner(b2g_home=None, adb_path=None, logdir=None, serial=None, **kwargs)¶

Create a B2G device runner.

Parameters:

b2g_home – Path to root B2G repository.
logdir – Path to save logfiles such as logcat.
serial – Serial of device to connect to as seen in adb devices.
profile – Profile object to use.
env – Environment variables to pass into the b2g.sh process.
clean_profile – If True, restores profile back to original state.
process_class – Class used to launch the b2g.sh process.
process_args – Arguments to pass into the b2g.sh process.
symbols_path – Path to symbol files used for crash analysis.

Returns:

A DeviceRunner for B2G devices.

mozrunner.runners.B2GEmulatorRunner(arch='arm', b2g_home=None, adb_path=None, logdir=None, binary=None, no_window=None, resolution=None, sdcard=None, userdata=None, **kwargs)¶

Create a B2G emulator runner.

Parameters:

arch – The architecture of the emulator, either ‘arm’ or ‘x86’. Defaults to ‘arm’.
b2g_home – Path to root B2G repository.
logdir – Path to save logfiles such as logcat and qemu output.
no_window – Run emulator without a window.
resolution – Screen resolution to set emulator to, e.g ‘800x1000’.
sdcard – Path to local emulated sdcard storage.
userdata – Path to custom userdata image.
profile – Profile object to use.
env – Environment variables to pass into the b2g.sh process.
clean_profile – If True, restores profile back to original state.
process_class – Class used to launch the b2g.sh process.
process_args – Arguments to pass into the b2g.sh process.
symbols_path – Path to symbol files used for crash analysis.

Returns:

A DeviceRunner for B2G emulators.

mozrunner.runners.FennecEmulatorRunner(avd='mozemulator-4.3', adb_path=None, avd_home=None, logdir=None, serial=None, binary=None, app='org.mozilla.fennec', **kwargs)¶

Create a Fennec emulator runner. This can either start a new emulator (which will use an avd), or connect to an already-running emulator.

Parameters:

avd – name of an AVD available in your environment. Typically obtained via tooltool: either ‘mozemulator-4.3’ or ‘mozemulator-x86’. Defaults to ‘mozemulator-4.3’
avd_home – Path to avd parent directory
logdir – Path to save logfiles such as logcat and qemu output.
serial – Serial of emulator to connect to as seen in adb devices. Defaults to the first entry in adb devices.
binary – Path to emulator binary. Defaults to None, which causes the device_class to guess based on PATH.
app – Name of Fennec app (often org.mozilla.fennec_$USER) Defaults to ‘org.mozilla.fennec’
cmdargs – Arguments to pass into binary.

Returns:

A DeviceRunner for Android emulators.

mozrunner.runners.FirefoxRunner(*args, **kwargs)¶

Create a desktop Firefox runner.

Parameters:

binary – Path to Firefox binary.
cmdargs – Arguments to pass into binary.
profile – Profile object to use.
env – Environment variables to pass into the gecko process.
clean_profile – If True, restores profile back to original state.
process_class – Class used to launch the binary.
process_args – Arguments to pass into process_class.
symbols_path – Path to symbol files used for crash analysis.
show_crash_reporter – allow the crash reporter window to pop up. Defaults to False.

Returns:

A GeckoRuntimeRunner for Firefox.

mozrunner.runners.Runner(*args, **kwargs)¶

Create a generic GeckoRuntime runner.

Parameters:

binary – Path to binary.
cmdargs – Arguments to pass into binary.
profile – Profile object to use.
env – Environment variables to pass into the gecko process.
clean_profile – If True, restores profile back to original state.
process_class – Class used to launch the binary.
process_args – Arguments to pass into process_class.
symbols_path – Path to symbol files used for crash analysis.
show_crash_reporter – allow the crash reporter window to pop up. Defaults to False.

Returns:

A generic GeckoRuntimeRunner.

mozrunner.runners.ThunderbirdRunner(*args, **kwargs)¶

Create a desktop Thunderbird runner.

Parameters:

binary – Path to Thunderbird binary.
cmdargs – Arguments to pass into binary.
profile – Profile object to use.
env – Environment variables to pass into the gecko process.
clean_profile – If True, restores profile back to original state.
process_class – Class used to launch the binary.
process_args – Arguments to pass into process_class.
symbols_path – Path to symbol files used for crash analysis.
show_crash_reporter – allow the crash reporter window to pop up. Defaults to False.

Returns:

A GeckoRuntimeRunner for Thunderbird.

BaseRunner¶

class mozrunner.base.BaseRunner(app_ctx=None, profile=None, clean_profile=True, env=None, process_class=None, process_args=None, symbols_path=None, dump_save_path=None, addons=None)¶

The base runner class for all mozrunner objects, both local and remote.

check_for_crashes(dump_directory=None, dump_save_path=None, test_name=None, quiet=False)¶

Check for possible crashes and output the stack traces.

Parameters:	dump_directory – Directory to search for minidump files dump_save_path – Directory to save the minidump files to test_name – Name to use in the crash output quiet – If True don’t print the PROCESS-CRASH message to stdout
Returns:	Number of crashes which have been detected since the last invocation

cleanup()¶: Cleanup all runner state

command¶: Returns the command list to run.

is_running()¶

Checks if the process is running.

Returns:	True if the process is active

reset()¶: Reset the runner to its default state.

returncode¶

The returncode of the process_handler. A value of None indicates the process is still running. A negative value indicates the process was killed with the specified signal.

Raises:	RunnerNotStartedError

start(debug_args=None, interactive=False, timeout=None, outputTimeout=None)¶

Run self.command in the proper environment.

Parameters:	debug_args – arguments for a debugger interactive – uses subprocess.Popen directly timeout – see process_handler.run() outputTimeout – see process_handler.run()
Returns:	the process id

stop(sig=None)¶

Kill the process.

Parameters:	sig – Signal used to kill the process, defaults to SIGKILL (has no effect on Windows).
Returns:	the process return code if process was already stopped, -<signal> if process was killed (Unix only)
Raises:	RunnerNotStartedError

wait(timeout=None)¶

Wait for the process to exit.

Parameters:	timeout – if not None, will return after timeout seconds. Timeout is ignored if interactive was set to True.
Returns:	the process return code if process exited normally, -<signal> if process was killed (Unix only), None if timeout was reached and the process is still running.
Raises:	RunnerNotStartedError

GeckoRuntimeRunner¶

class mozrunner.base.GeckoRuntimeRunner(binary, cmdargs=None, **runner_args)¶

Bases: mozrunner.base.runner.BaseRunner

The base runner class used for local gecko runtime binaries, such as Firefox and Thunderbird.

DeviceRunner¶

class mozrunner.base.DeviceRunner(device_class, device_args=None, **kwargs)¶

Bases: mozrunner.base.runner.BaseRunner

The base runner class used for running gecko on remote devices (or emulators), such as B2G.

Device API Documentation¶

Generally using the device classes directly shouldn’t be required, but in some cases it may be desirable.

Device¶

class mozrunner.devices.Device(app_ctx, logdir=None, serial=None, restore=True)¶

cleanup()¶: Cleanup the device.

connect()¶: Connects to a running device. If no serial was specified in the constructor, defaults to the first entry in adb devices.

install_busybox(busybox)¶

Installs busybox on the device.

Parameters:	busybox – Path to busybox binary to install.

pull_minidumps()¶

Saves any minidumps found in the remote profile on the local filesystem.

Returns:	Path to directory containing the dumps.

reboot()¶: Reboots the device via adb.

remote_profiles¶: A list of remote profiles on the device.

setup_profile(profile)¶

Copy profile to the device and update the remote profiles.ini to point to the new profile.

Parameters:	profile – mozprofile object to copy over.

Emulator¶

class mozrunner.devices.Emulator(app_ctx, arch, resolution=None, sdcard=None, userdata=None, no_window=None, binary=None, **kwargs)¶

Bases: mozrunner.devices.emulator.BaseEmulator

args¶: Arguments to pass into the emulator binary.

cleanup()¶: Cleans up and kills the emulator, if it was started by mozrunner.

connect()¶: Connects to a running device. If no serial was specified in the constructor, defaults to the first entry in adb devices.

mozrunner — Manage remote and local gecko processes¶

Basic usage¶

Handling output¶

Handling timeouts¶

Using a device runner¶

Runner API Documentation¶

Application Runners¶

BaseRunner¶

GeckoRuntimeRunner¶

DeviceRunner¶

Device API Documentation¶

Device¶

Emulator¶

`mozrunner` — Manage remote and local gecko processes¶