blob: 766b02cc4c7afd8e1531eda06b9ba12b96b303fb [file] [log] [blame]
:mod:`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:
.. code-block:: python
from mozrunner import FirefoxRunner
binary = 'path/to/firefox/binary'
runner = FirefoxRunner(binary=binary)
This automatically creates and uses a default mozprofile object. If you
wish to use a specialized or pre-existing profile, you can create a
:doc:`mozprofile <mozprofile>` object and pass it in:
.. code-block:: python
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)
profile = FirefoxProfile(profile=profile_path)
runner = FirefoxRunner(binary=binary, profile=profile)
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:
.. code-block:: python
from mozrunner import FirefoxRunner
def handle_output_line(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 :doc:`mozprocess <mozprocess>` to manage the underlying gecko
process and handle output. See the :doc:`mozprocess documentation <mozprocess>`
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.
.. code-block:: python
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)
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.
.. code-block:: python
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:
.. code-block:: python
from mozrunner import B2GEmulatorRunner
b2g_home = 'path/to/B2G'
runner = B2GEmulatorRunner(arch='arm', b2g_home=b2g_home)
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.
.. code-block:: python
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
.. automodule:: mozrunner.runners
.. autoclass:: mozrunner.base.BaseRunner
.. autoclass:: mozrunner.base.GeckoRuntimeRunner
.. autoclass:: mozrunner.base.DeviceRunner
Device API Documentation
Generally using the device classes directly shouldn't be required, but in some
cases it may be desirable.
.. autoclass:: mozrunner.devices.Device
.. autoclass:: mozrunner.devices.Emulator