DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (901e88980751)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
: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 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:

.. 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 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)
    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
    runner.start()        # stops the gecko process (if started), installs the profile, (re)starts 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:

BlinkRuntimeRunner
~~~~~~~~~~~~~~~~~~
.. autoclass:: mozrunner.base.BlinkRuntimeRunner
   :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:

EmulatorAVD
~~~~~~~~~~~
.. autoclass:: mozrunner.devices.EmulatorAVD
   :show-inheritance:
   :members: