mozrunner — 管理远程和本地 Gecko 进程

Mozrunner 提供了一个 API 来管理具有任意配置配置文件的基于 Gecko 的应用程序。它目前支持本地桌面二进制文件，例如 Firefox 和 Thunderbird，以及移动设备和模拟器上的 Firefox OS。

基本用法

使用 mozrunner 最简单的方法是实例化一个运行器，启动它，然后等待它完成

from mozrunner import FirefoxRunner
binary = 'path/to/firefox/binary'
runner = FirefoxRunner(binary=binary)
runner.start()
runner.wait()

这会自动创建并使用默认的 mozprofile 对象。如果您希望使用专门的或预先存在的配置文件，您可以创建一个 mozprofile 对象并将其传递进去

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()

处理输出

默认情况下，mozrunner 将 Gecko 进程的输出转储到标准输出。可以通过 process_args 参数传递任意输出处理程序来添加它们。请注意，传递处理程序会覆盖默认行为。因此，如果您想除了转储到标准输出之外还使用处理程序，则需要明确指定。例如

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 使用 mozprocess 来管理底层的 Gecko 进程和处理输出。请参阅 mozprocess 文档 以了解 process_args 接受的所有可用参数。

处理超时

有时 Gecko 可能会挂起，或者可能只是花费的时间太长。为了处理这种情况，您可能希望设置超时。Mozrunner 有两种类型的超时，传统的 timeout 和 outputTimeout。这些被传递到 runner.start() 方法中。设置 timeout 会导致 Gecko 在指定秒数后被杀死，无论发生什么情况。设置 outputTimeout 会导致 Gecko 在指定秒数后在没有输出的情况下被杀死。在这两种情况下，进程处理程序的 onTimeout 回调将被触发。

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()

runner.wait() 方法也接受超时参数。但与 runner.start() 的参数不同，此参数只会从等待调用中返回，而不会杀死 Gecko 进程。

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

使用设备运行器

前面的示例使用了 GeckoRuntimeRunner。如果您想控制远程设备上的 Gecko 进程，则需要使用 DeviceRunner。除了不传递二进制文件之外，api 几乎相同，而是创建一个设备对象。例如，要在模拟器上运行 Android 版 Firefox，您可以执行以下操作

from mozrunner import FennecEmulatorRunner

avd_home = 'path/to/avd'
runner = FennecEmulatorRunner(app='org.mozilla.fennec', avd_home=avd_home)
runner.start()
runner.wait()

设备运行器具有 device 对象。请记住，Gecko 进程在设备上运行。在模拟器的情况下，可以独立于 Gecko 进程启动设备。

runner.device.start() # launches the emulator
runner.start()        # stops the gecko process (if started), installs the profile, (re)starts the gecko process

运行器 API 文档

应用程序运行器

此模块包含一组快捷方法，用于创建 Firefox、Android 版 Firefox 或 Thunderbird 等常用 Mozilla 应用程序的运行器。

mozrunner.runners.ChromeRunner(*args, **kwargs)

创建一个桌面 Google Chrome 运行器。

参数:

  • binary – Chrome 二进制文件的路径。

  • cmdargs – 传递到二进制文件中的参数。

mozrunner.runners.ChromiumRunner(*args, **kwargs)

创建一个桌面 Google Chromium 运行器。

参数:

  • binary – Chromium 二进制文件的路径。

  • cmdargs – 传递到二进制文件中的参数。

mozrunner.runners.FennecEmulatorRunner(avd='mozemulator-arm', adb_path=None, avd_home=None, logdir=None, serial=None, binary=None, app='org.mozilla.fennec', **kwargs)

创建一个 Fennec 模拟器运行器。这可以启动一个新的模拟器（它将使用 avd），也可以连接到一个已经运行的模拟器。

参数:

  • avd – 您环境中可用的 AVD 的名称。通常通过 tooltool 获取：'mozemulator-4.3' 或 'mozemulator-x86'。默认为 'mozemulator-4.3'

  • avd_home – avd 父目录的路径

  • logdir – 保存日志文件（如 qemu 输出）的路径。

  • serial – 要连接到的模拟器的序列号，如 adb devices 中所示。默认为 adb devices 中的第一个条目。

  • binary – 模拟器二进制文件的路径。默认为 None，这会导致 device_class 根据 PATH 推测。

  • app – Fennec 应用程序的名称（通常为 org.mozilla.fennec_$USER）默认为 'org.mozilla.fennec'

  • cmdargs – 传递到二进制文件中的参数。

返回:

Android 模拟器的 DeviceRunner。

mozrunner.runners.FirefoxRunner(*args, **kwargs)

创建一个桌面 Firefox 运行器。

参数:

  • binary – Firefox 二进制文件的路径。

  • cmdargs – 传递到二进制文件中的参数。

  • profile – 要使用的配置文件对象。

  • env – 传递到 Gecko 进程的环境变量。

  • clean_profile – 如果为 True，则将配置文件恢复到原始状态。

  • process_class – 用于启动二进制文件的类。

  • process_args – 传递到 process_class 中的参数。

  • symbols_path – 用于崩溃分析的符号文件的路径。

  • show_crash_reporter – 允许崩溃报告窗口弹出。默认为 False。

返回:

Firefox 的 GeckoRuntimeRunner。

mozrunner.runners.Runner(*args, **kwargs)

创建一个通用的 GeckoRuntime 运行器。

参数:

  • binary – 二进制文件的路径。

  • cmdargs – 传递到二进制文件中的参数。

  • profile – 要使用的配置文件对象。

  • env – 传递到 Gecko 进程的环境变量。

  • clean_profile – 如果为 True，则将配置文件恢复到原始状态。

  • process_class – 用于启动二进制文件的类。

  • process_args – 传递到 process_class 中的参数。

  • symbols_path – 用于崩溃分析的符号文件的路径。

  • show_crash_reporter – 允许崩溃报告窗口弹出。默认为 False。

返回:

一个通用的 GeckoRuntimeRunner。

mozrunner.runners.ThunderbirdRunner(*args, **kwargs)

创建一个桌面 Thunderbird 运行器。

参数:

  • binary – Thunderbird 二进制文件的路径。

  • cmdargs – 传递到二进制文件中的参数。

  • profile – 要使用的配置文件对象。

  • env – 传递到 Gecko 进程的环境变量。

  • clean_profile – 如果为 True，则将配置文件恢复到原始状态。

  • process_class – 用于启动二进制文件的类。

  • process_args – 传递到 process_class 中的参数。

  • symbols_path – 用于崩溃分析的符号文件的路径。

  • show_crash_reporter – 允许崩溃报告窗口弹出。默认为 False。

返回:

Thunderbird 的 GeckoRuntimeRunner。

BaseRunner

class mozrunner.base.BaseRunner(app_ctx=None, profile=None, clean_profile=True, env=None, process_class=None, process_args=None, symbols_path=None, dump_save_path=None, addons=None, explicit_cleanup=False)

所有 mozrunner 对象（本地和远程）的基本运行器类。

check_for_crashes(dump_directory=None, dump_save_path=None, test_name=None, quiet=False)

检查可能的崩溃并输出堆栈跟踪。

参数:

  • dump_directory – 搜索 minidump 文件的目录

  • dump_save_path – 保存 minidump 文件的目录

  • test_name – 在崩溃输出中使用的名称

  • quiet – 如果为 True，则不将 PROCESS-CRASH 消息打印到 stdout

返回:

自上次调用以来检测到的崩溃次数

cleanup(keep_profile=False)

清理所有运行器状态

abstract property command

返回要运行的命令列表。

is_running()

检查进程是否正在运行。

返回:

如果进程处于活动状态，则为 True

reset()

将运行器重置为其默认状态。

property returncode

process_handler 的返回值。值为 None 表示进程仍在运行。负值表示进程已使用指定的信号终止。

引发:

RunnerNotStartedError

start(debug_args=None, interactive=False, timeout=None, outputTimeout=None)

在正确的环境中运行 self.command。

参数:

  • debug_args – 调试器的参数

  • interactive – 直接使用 subprocess.Popen

  • timeout – 请参阅 process_handler.run()

  • outputTimeout – 请参阅 process_handler.run()

返回:

进程 ID

引发:

RunnerNotStartedError

stop(sig=None, timeout=None)

终止进程。

参数:

  • sig – 用于终止进程的信号，默认为 SIGKILL（对 Windows 无效）。

  • timeout – 等待进程退出最长时间（对 Windows 无效）。

返回:

如果进程已停止，则为进程返回值，如果进程被终止，则为 -<signal>（仅限 Unix）

引发:

RunnerNotStartedError

wait(timeout=None)

等待进程退出。

参数:

timeout – 如果不为 None，将在 timeout 秒后返回。如果 interactive 设置为 True，则忽略 Timeout。

返回:

如果进程正常退出，则为进程返回值；如果进程被终止，则为 -<signal>（仅限 Unix）；如果达到超时且进程仍在运行，则为 None。

引发:

RunnerNotStartedError

GeckoRuntimeRunner

class mozrunner.base.GeckoRuntimeRunner(binary, cmdargs=None, **runner_args)

基类: BaseRunner

用于本地 gecko 运行时二进制文件（例如 Firefox 和 Thunderbird）的基本运行器类。

property command

返回要运行的命令列表。

start(*args, **kwargs)

在正确的环境中运行 self.command。

参数:

  • debug_args – 调试器的参数

  • interactive – 直接使用 subprocess.Popen

  • timeout – 请参阅 process_handler.run()

  • outputTimeout – 请参阅 process_handler.run()

返回:

进程 ID

引发:

RunnerNotStartedError

BlinkRuntimeRunner

class mozrunner.base.BlinkRuntimeRunner(binary, cmdargs=None, **runner_args)

基类: BaseRunner

用于运行 Google Chrome 或 Chromium 等应用程序的基本运行器类。

check_for_crashes(*args, **kwargs)

检查可能的崩溃并输出堆栈跟踪。

参数:

  • dump_directory – 搜索 minidump 文件的目录

  • dump_save_path – 保存 minidump 文件的目录

  • test_name – 在崩溃输出中使用的名称

  • quiet – 如果为 True，则不将 PROCESS-CRASH 消息打印到 stdout

返回:

自上次调用以来检测到的崩溃次数

property command

返回要运行的命令列表。

DeviceRunner

class mozrunner.base.DeviceRunner(device_class, device_args=None, **kwargs)

基类: BaseRunner

用于在远程设备（或模拟器）上运行 gecko 的基本运行器类。

check_for_crashes(dump_save_path=None, test_name=None, **kwargs)

检查可能的崩溃并输出堆栈跟踪。

参数:

  • dump_directory – 搜索 minidump 文件的目录

  • dump_save_path – 保存 minidump 文件的目录

  • test_name – 在崩溃输出中使用的名称

  • quiet – 如果为 True，则不将 PROCESS-CRASH 消息打印到 stdout

返回:

自上次调用以来检测到的崩溃次数

cleanup(*args, **kwargs)

清理所有运行器状态

property command

返回要运行的命令列表。

property returncode

远程进程的返回值。

值为 None 表示进程仍在运行。否则返回 0，因为目前尚无已知方法可以检索真实的退出代码。

start(*args, **kwargs)

在正确的环境中运行 self.command。

参数:

  • debug_args – 调试器的参数

  • interactive – 直接使用 subprocess.Popen

  • timeout – 请参阅 process_handler.run()

  • outputTimeout – 请参阅 process_handler.run()

返回:

进程 ID

引发:

RunnerNotStartedError

stop(sig=None)

终止进程。

参数:

  • sig – 用于终止进程的信号，默认为 SIGKILL（对 Windows 无效）。

  • timeout – 等待进程退出最长时间（对 Windows 无效）。

返回:

如果进程已停止，则为进程返回值，如果进程被终止，则为 -<signal>（仅限 Unix）

引发:

RunnerNotStartedError

wait(timeout=None)

等待远程进程退出。

参数:

timeout – 如果不为 None，将在 timeout 秒后返回。

返回:

进程返回值，如果达到超时且进程仍在运行，则为 None。

设备 API 文档

通常不需要直接使用设备类，但在某些情况下可能需要。

设备

class mozrunner.devices.Device(app_ctx, logdir=None, serial=None, restore=True)
cleanup()

清理设备。

connect()

连接到正在运行的设备。如果在构造函数中未指定 serial，则默认为 adb devices 中的第一个条目。

pull_minidumps()

将远程配置文件中找到的任何 minidump 保存到本地文件系统上。

返回:

包含转储的目录的路径。

reboot()

通过 adb 重启设备。

property remote_profiles

设备上的远程配置文件列表。

setup_profile(profile)

将配置文件复制到设备，并更新远程 profiles.ini 以指向新配置文件。

参数:

profile – 要复制的 mozprofile 对象。

EmulatorAVD

class mozrunner.devices.EmulatorAVD(app_ctx, binary, avd, port=5554, **kwargs)

基类: BaseEmulator

property args

传递给模拟器二进制文件的参数。

start()

启动一个新的模拟器。