gecko/testing/mozbase/docs/mozrunner.rst

178 lines
5.2 KiB
ReStructuredText

: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)
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
:doc:`mozprofile <mozprofile>` object and pass it in:
.. code-block:: python
from mozprofile import Profile
from mozrunner import FirefoxRunner
import os
binary = 'path/to/firefox/binary'
profile_path = 'path/to/profile'
if os.path.exists(profile_path):
profile = Profile.clone(path_from=profile_path)
else:
profile = Profile(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:
.. code-block:: python
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 :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)
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.
.. code-block:: python
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:
.. code-block:: python
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.
.. 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
:members:
BaseRunner
~~~~~~~~~~
.. autoclass:: mozrunner.base.BaseRunner
:members:
GeckoRuntimeRunner
~~~~~~~~~~~~~~~~~~
.. autoclass:: mozrunner.base.GeckoRuntimeRunner
:show-inheritance:
:members:
DeviceRunner
~~~~~~~~~~~~
.. autoclass:: mozrunner.base.DeviceRunner
:show-inheritance:
:members:
Device API Documentation
------------------------
Generally using the device classes directly shouldn't be required, but in some
cases it may be desirable.
Device
~~~~~~
.. autoclass:: mozrunner.devices.Device
:members:
Emulator
~~~~~~~~
.. autoclass:: mozrunner.devices.Emulator
:show-inheritance:
:members: