[译]Android monkeyrunner 官方文档

-> 说明：本系列文章翻译自Android官方文档。

分为四篇：
android monkeyrunner 官方文档
android MonkeyRunner 类接口文档
android MonkeyDevice 类接口文档（待翻译）
android MonkeyImage 类接口文档（待翻译）

monkeyrunner 工具提供了在 Android 代码外编写控制 Android 设备或虚拟机程序的 API。你可以使用 monkeyrunner 编写 Python 程序来安装 Android 应用程序或测试包，运行应用，向应用发送按键，截图并把图片存放到工作目录。monkeyrunner 工具主要用来在功能/框架层测试应用和设备，执行单元测试组，但你也可以用作其他目的。

monkeyrunner 工具不像 UI/Application Exerciser Monkey（也就是monkey工具）。monkey工具直接通过 adb shell 运行，生成随机的用户或系统事件流作用于设备。相比而言， monkeyrunner 工具通过发送 API 中明确的指令或事件，在工作目录控制设备或模拟器。

monkeyrunner 工具为 Android 测试提供了以下独特功能：

多设备控制：monkeyrunner API 可以在多个设备或模拟器间执行一或多个测试组。你可以一次性手动链接所有设备或启动所有模拟器（或两者同时进行），也可以通过编程方式操作，然后执行一或多组测试。你还可以通过编程启动一台模拟器，执行疑惑多组测试，最后终止模拟器。
功能测试：monkeyrunner 可以在 Android 应用上执行完整的自动化测试。你可以提供一些按键和触摸事件输入，然后通过截图查看测试结果。
回归测试：monkeyrunner 可以通过运行应用并将截图与已知正确的截图集合相比较来测试应用稳定性。
可扩展的自动化：由于 monkeyrunner 是一组 API 工具集，你可以开发一个完整的基于 Python 的控制 Android 设备的模块或程序。另外，使用 monkeyrunner API，你可以使用 Python 标准的os和subprocess模块调用 Android 工具，比如Android Debug Bridge。

你也可以向 monkeyrunner API 中添加你自己的类。在用插件扩展monkeyrunner章节中有详细的介绍。

monkeyrunner 工具使用 Jython，一个使用Java语言实现的 Python。Jython 允许 monkeyrunner API 方便的与 Android 框架层交互。在 Jythong 中，你可以使用 Python 语法访问 API 中的常量，类，和方法等。

一个简单的 monkeyrunner 程序

这时一个简单的 monkeyrunner 程序，该程序会连接设备，创建一个MonkeyDevice对象。使用MonkeyDevice对象执行安装 Android 应用，启动应用的一个 activity，给 activity 发送按键事件。然后截图作为结果，创建MonkeyImage对象。程序使用此对象将包含截图的.png文件保存到本地。

# Imports the monkeyrunner modules used by this program
from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice

# Connects to the current device, returning a MonkeyDevice object
device = MonkeyRunner.waitForConnection()

# Installs the Android package. Notice that this method returns a boolean, so you can test
# to see if the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')

# sets a variable with the package's internal name
package = 'com.example.android.myapplication'

# sets a variable with the name of an Activity in the package
activity = 'com.example.android.myapplication.MainActivity'

# sets the name of the component to start
runComponent = package + '/' + activity

# Runs the component
device.startActivity(component=runComponent)

# Presses the Menu button
device.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)

# Takes a screenshot
result = device.takeSnapshot()

# Writes the screenshot to a file
result.writeToFile('myproject/shot1.png','png')

monkeyrunner API

在com.android.monkeyrunner包中有三个 monkeyrunner API ：

MonkeyRunner：为 monkeyrunner 程序提供工具的类。此类提供了 monkeyrunner 连接设备或模拟器的方法。还为创建 monkeyrunner 程序 UI 和呈现内建帮助提供了方法。
MonkeyDevice：代表一个设备或模拟器。此类提供了安装/卸载程序、启动Activity和向应用发送按键或触摸事件的方法。也可以使用此类执行测试程序。
MonkeyImage：代表一个截屏图像。此类提供了截屏、转换bitmap到其他格式、比较两个MonkeyImage对象和将图像写入文件的方法。

在一个 Python 程序中，你可以将每个类都当作一个 Python 模块访问。monkeyrunner 工具不会自动导入这些模块，你可以使用 Python 的import语句导入模块：

from com.android.monkeyrunner import

代表了一个你想要导入的类名。你可以在一个from语句中导入多个模块，模块之间用逗号分割。

执行 monkeyrunner

你既可以通过一个文件执行 monkeyrunner，也可以在 monkeyrunner 的交互式进程中输入语句。在 Android SDK 目录下的tools/子目录下通过调用monkeyrunner命令即可执行上述操作。如果你提供了一个文件名作为参数，monkeyrunner会将该文件中的内容作为 Python 程序执行；否则将会启动交互式进程。

monkeyrunner命令语法如下：

monkeyrunner -plugin

表1解释了标记和参数代表的意思。

表1. monkeyrunner标记和参数。

参数	描述
-plugin	（可选）指定一个包含 monkeyrunner 插件的`.jar`文件。查看扩展 monkeyrunner 插件了解更多。如果要指定多个文件，多次调用此参数就可以了。
	如果提供了此参数，`monkeyrunner` 命令会将该文件内容作为程序执行。如果没有提供此参数，则开启交互式进程。
	（可选）中的标记和参数

monkeyrunner 内建帮助

你可以通过执行以下命令为monkeyrunner生成一个 API 参考：

monkeyrunner help.py

参数分别是：

如果是text则输出普通文本，如果是html则输出HTML文件。
输出文件的合法路径名

扩展 monkeyrunner 插件

你可以使用 Java 语言扩展 monkeyrunner API 并把它们集成到一个或多个的.jar文件中。你可以使用此特性写自己的类继承 monkeyrunner API 或者继承已存在的类。你也可以使用此特性初始化 monkeyrunner 环境。

在调用 monkeyrunner 命令时加入-plugin 参数可以使用插件，参考表1。

在你的插件代码中，可以导入并继承包com.android.monkeyrunner中 monkeyrunner 主要的类：MonkeyDevice，MonkeyImage，和MonkeyRunner（参考monkeyrunner API）。

需要注意的是，插件并没有赋予你访问 Android SDK 的权限。你不能导入类似com.android.app这样的包。因为 monkeyrunner 是基于框架层以下的 API 与设备和模拟器交互的。

插件启动类

一个插件的.jar文件可以指定一个类在脚本执行之前实例化。只需要将MonkeyRunnerStartupRunner键加入.jar文件的清单中即可。值则应该是启动类的类名。下面的片段将向你展示你需要在ant构建文件中需要怎么做：

为了可以接入 monkeyrunner 的运行时环境，启动类可以实现com.google.common.base.Predicate。例如，下面的类在默认命名空间中设置了一些变量：

package com.android.example;

import com.google.common.base.Predicate;
import org.python.util.PythonInterpreter;

public class Main implements Predicate {
    @Override
    public boolean apply(PythonInterpreter anInterpreter) {

        /*
        * Examples of creating and initializing variables in the monkeyrunner environment's
        * namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
        * and "use_emulator"
        *
        */
        anInterpreter.set("newtest", "enabled");
        anInterpreter.set("use_emulator", 1);

        return true;
    }
}