author Andrew Halberstadt <ahalberstadt@mozilla.com>
Thu, 12 Apr 2018 22:29:17 -0400
changeset 467469 df5d226d1df3204b7fb4b975e7075a3a3e7a9775
parent 462615 0db6e65892e98f6fb98579b75d87b44beb65c936
permissions -rw-r--r--
Bug 1445944 - [mozrunner] Create a base BlinkRuntimeRunner and add a ChromeRunner to the runners list r=rwood This allows consumers to bootstrap Chrome with mozrunner. For now the profile implementation is just an empty class but this will be expanded in a future commit. MozReview-Commit-ID: 1Z14FudH0JJ

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

.. code-block:: python

    from mozrunner import FennecEmulatorRunner

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

Runner API Documentation

Application Runners
.. automodule:: mozrunner.runners

.. autoclass:: mozrunner.base.BaseRunner

.. autoclass:: mozrunner.base.GeckoRuntimeRunner

.. autoclass:: mozrunner.base.BlinkRuntimeRunner

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