`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 to run Firefox for Android on the emulator, you might do:

from mozrunner import FennecEmulatorRunner

avd_home = 'path/to/avd'
runner = FennecEmulatorRunner(app='org.mozilla.fennec', avd_home=avd_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
runner.start()        # stops the gecko process (if started), installs the profile, (re)starts 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, Firefox for Android or Thunderbird.

mozrunner.runners.ChromeRunner(*args, **kwargs)

Create a desktop Google Chrome runner.

Parameters:

binary – Path to Chrome binary.
cmdargs – Arguments to pass into the binary.

mozrunner.runners.ChromiumRunner(*args, **kwargs)

Create a desktop Google Chromium runner.

Parameters:

binary – Path to Chromium binary.
cmdargs – Arguments to pass into the binary.

mozrunner.runners.FennecEmulatorRunner(avd='mozemulator-arm', 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 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, explicit_cleanup=False)

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(keep_profile=False): Cleanup all runner state

abstract property 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.

property 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

Raises:

RunnerNotStartedError

stop(sig=None, timeout=None)

Kill the process.

Parameters:

sig – Signal used to kill the process, defaults to SIGKILL (has no effect on Windows).
timeout – Maximum time to wait for the processs to exit (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: BaseRunner

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

property command: Returns the command list to run.

start(*args, **kwargs)

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

Raises:

RunnerNotStartedError

BlinkRuntimeRunner

class mozrunner.base.BlinkRuntimeRunner(binary, cmdargs=None, **runner_args)

Bases: BaseRunner

A base runner class for running apps like Google Chrome or Chromium.

check_for_crashes(*args, **kwargs)

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

property command: Returns the command list to run.

DeviceRunner

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

Bases: BaseRunner

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

check_for_crashes(dump_save_path=None, test_name=None, **kwargs)

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(*args, **kwargs): Cleanup all runner state

property command: Returns the command list to run.

property returncode

The returncode of the remote process.

A value of None indicates the process is still running. Otherwise 0 is returned, because there is no known way yet to retrieve the real exit code.

start(*args, **kwargs)

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

Raises:

RunnerNotStartedError

stop(sig=None)

Kill the process.

Parameters:

sig – Signal used to kill the process, defaults to SIGKILL (has no effect on Windows).
timeout – Maximum time to wait for the processs to exit (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 remote process to exit.

Parameters:: timeout – if not None, will return after timeout seconds.
Returns:: the process return code or None if timeout was reached and the process is still running.

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.

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.

property 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.

EmulatorAVD

class mozrunner.devices.EmulatorAVD(app_ctx, binary, avd, port=5554, **kwargs)

Bases: BaseEmulator

property args: Arguments to pass into the emulator binary.

start(): Starts a new emulator.

mozrunner — Manage remote and local gecko processes

Basic usage

Handling output

Handling timeouts

Using a device runner

Runner API Documentation

Application Runners

BaseRunner

GeckoRuntimeRunner

BlinkRuntimeRunner

DeviceRunner

Device API Documentation

Device

EmulatorAVD

`mozrunner` — Manage remote and local gecko processes