summaryrefslogtreecommitdiffstats
path: root/testing/mozbase/docs/mozrunner.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--testing/mozbase/docs/mozrunner.rst183
1 files changed, 183 insertions, 0 deletions
diff --git a/testing/mozbase/docs/mozrunner.rst b/testing/mozbase/docs/mozrunner.rst
new file mode 100644
index 0000000000..5020e76cbb
--- /dev/null
+++ b/testing/mozbase/docs/mozrunner.rst
@@ -0,0 +1,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: