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
|
: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, 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:
|
