MonkeyRunner

The monkeyrunner tool provides an API for writing programs that control an Android device or emulator from outside of Android code. With monkeyrunner, you can write a Python program that installs an Android application or test package, runs it, sends keystrokes to it, takes screenshots of its user interface, and stores screenshots on the workstation. The monkeyrunner tool is primarily designed to test applications and devices at the functional/framework level and for running unit test suites, but you are free to use it for other purposes.

Monkeyrunner工具提供了API去编写一个程序实现控制安卓设备或者虚拟机的代码，使用monkeyrunner,你可以编写一个python程序去安装一个安卓应用或测试包，运行它，发送按键，截取用户界面，并保存到工作站。monkeyrunner工具主要是用来测试应用程序和设备的功能/框架水平和运行单元测试套件,但你可以自由地使用它用于其他目的。

The monkeyrunner tool is not related to the UI/Application Exerciser Monkey, also known as the monkey tool. The monkey tool runs in an adb shell directly on the device or emulator and generates pseudo-random streams of user and system events. In comparison, the monkeyrunner tool controls devices and emulators from a workstation by sending specific commands and events from an API.

Monkeyrunner工具与UI/APP运动monkey不相关，但是统称为monkey工具。monkey工具通过发送一个adb命令对设备或者模拟器生成伪随机的用户和系统事件流。相比之下，monkerunner工具控制设备和模拟器通过工作站发送特定的命令

The monkeyrunner tool provides these unique features for Android testing:

Multiple device control: The monkeyrunner API can apply one or more test suites across multiple devices or emulators. You can physically attach all the devices or start up all the emulators (or both) at once, connect to each one in turn programmatically, and then run one or more tests. You can also start up an emulator configuration programmatically, run one or more tests, and then shut down the emulator.Functional testing: monkeyrunner can run an automated start-to-finish test of an Android application. You provide input values with keystrokes or touch events, and view the results as screenshots.Regression testing - monkeyrunner can test application stability by running an application and comparing its output screenshots to a set of screenshots that are known to be correct.Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire system of Python-based modules and programs for controlling Android devices. Besides using the monkeyrunner API itself, you can use the standard Python os and subprocess modules to call Android tools such as Android Debug Bridge.You can also add your own classes to the monkeyrunner API. This is described in more detail in the section Extending monkeyrunner with plugins.

The monkeyrunner tool uses Jython, a implementation of Python that uses the Java programming language. Jython allows the monkeyrunner API to interact easily with the Android framework. With Jython you can use Python syntax to access the constants, classes, and methods of the API.

monkeyrunner为安卓提供了这些独特的测试特征：
多设备控制： monkeyrunner API可以应用一个或多个测试套件跨多个设备或模拟器。你可以在同一时间接上所有的设备或启动全部模拟器(或两者),依据程序依次连接到每一个,然后运行一个或多个测试。你也可以用程序启动一个模拟器配置,运行一个或多个测试,然后关闭模拟器
功能测试： monkeyrunner可以运行Android应用程序的自动化测试。您提供按键或触摸事件的输入值,并查看结果的截屏。
回归测试： monkeyrunner可以测试应用程序运行一个应用程序和比较稳定的输出一组截图,截图是已知是正确的。
可扩展的自动化：由于monkeyrunner API工具包,您可以开发整个系统的面向Android设备控制模块和程序。除了使用monkeyrunner API,您可以使用标准的Python Android操作系统和子过程模块调用工具,如Android调试桥。
你也可以添加自己的类monkeyrunner API。这是更详细地描述使用插件扩展monkeyrunner的部分。
monkeyrunner工具使用Jython,Python,使用Java编程语言的实现。Jython允许monkeyrunner API进行交互与Android框架。用Jython可以使用Python语法访问常量,类和方法的API。
A Simple monkeyrunner Program
Here is a simple monkeyrunner program that connects to a device, creating a MonkeyDevice object. Using the MonkeyDevice object, the program installs an Android application package, runs one of its activities, and sends key events to the activity. The program then takes a screenshot of the result, creating a MonkeyImage object. From this object, the program writes out a .png file containing the screenshot.

#imports the monkeyrunner modules used by this programimport com.android.monkeyrunner import MonkeyRunner,MonkeyDevice#连接设备，并返回monkeydevice对象device=MonkeyRunner.waitForConnection()#安装应用，该语句返回boolean值device.installPackage('myprogram/myapplication.apk')#为包名设置一个变量package='com.android.myapplication.apk'# sets a variable with the name of an Activity in the packageactivity = 'com.example.android.myapplication.MainActivity'# sets the name of the component to startrunComponent = package + '/' + activity# Runs the componentdevice.startActivity(component=runComponent)# Presses the Menu buttondevice.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)# Takes a screenshotresult = device.takeSnapshot()# Writes the screenshot to a fileresult.writeToFile('myproject/shot1.png','png')

MonkeyRunner:

monkeyrunner类包含的静态实用方法：

Public Methods:

string alert(string  message,string  title,string okTitle) 

Arguments:
- message:显示信息
- title:显示对话框标题，默认“Alert”
- okTitle:对话框中显示的文本按钮，默认是“OK”
运行当前脚本时显示一个对话框，对话框是模态框(Modal：是覆盖在父窗体上的子窗体)，因此当前脚本暂停，直到用户点击对话框。

integer choice(string ,message,iterable choice,string title)

Arguments:
- message:显示信息
- choices:Python iterable包含一个或多个对象显示为字符串。推荐的形式是一个字符串数组。
- title：对话框标题，默认是”Input”
Return:
如果用户选择了列表中的项，将返回用户选择项的下标序列，如果用户选择取消，将返回“-1”
运行当前脚本显示一个对话框的列表选择，对话框是模态框，因此脚本暂停，直到用户选择对话框中的其中一个列表

void help(string format)

Arguments:
- format :在输出中使用的标记格式，可以是”text”或者“HTML”
使用指定的格式显示，monkeyrunner APi参考的风格类似于python的pydoc工具

 string input (string message string initialValue, string title, string okTitle, string cancelTitle) 

Arguments:
- initialValue:初始显示在对话框中的值，默认是空字符串
- title:默认值是input
- okTitle:默认值是Ok
- cancelTitle:默认值是Cancel
Return:点击OK,返回初始值或者用户输入的值，点击Cancel，返回空字符串

void sleep(float secodes)

暂停当前脚本，指定时间

MonkeyDevice waitForConnection(float timeout,string deviceid)

Arguments:
- timeout:等待设备的时间，默认无限等待
- deviceid :设备序列号或模拟器
连接设备或者模拟器
Returns:
创建模拟器或者设备的monkeyDevice实例，用该实例对象去控制设备或模拟器

2、MonkeyImage:
描述：保存设备或者模拟器的截屏，图像从屏幕缓冲区中截图。对象的方法允许你将图像转化成各种存储格式，写图像到一个文件，复制部分图像，并比较其他MonkeyImage对象
不需要创建一个新的MonkeyImage实例，反而是使用MonkeyDevice.takeSnapshot()去创建一个实例截图，举例：
newimage=MonkeyDevice.takeSnapshot()
摘要：
public Methods
string convertToByte(string format)
转换成一个特定格式的MonkeyImage作为一个字符串返回结果。使用此获得rawpixels在一个特定的格式。字符串输出是有更好的表现
参数：
format:输出目标格式。支持所有常见的光栅输出格式。默认值是“PNG”(便携式网络图形)

tuple getRawPixel(integer x,integer y)
返回单个像素在图像的位置（x,y）,作为一个整数的一个元组（a,r,g,b）
integer getRawPixellint(integer x,integer y)
返回单个像素在图像的位置（x,y）,作为一个整数的一个元组（a,r,g,b）
MonkeyImage getSubImage(tuple rect)
复制图像的矩形区域
Arguments
x和y指定基于像素的左上角的位置选择，w指定区域的宽度，h指定它的高度，以像素为单位。
Boolean sameAs(MonkeyImage otherImage,float perent)
和另外一个monkeyImage对象进行比较，相似度达到指定比例
void writeToFile(string filename,string format)
完全输出文件名和扩展
format：默认png值

3、MonkeyDevice:
This class is used to control an Android device or emulator .The methods send UI events,retrieve information,install and remove applications,and run application.
通常不需要使用MonkeyDevice 来创建对象。应该使用MonkeyRUnner.waitForConnection() 来创建一个新的对象，连接设备或者虚拟机。

常量：
string DOWN
string UP
string DOWN_AND_UP

public methods
void broadcastIntent(string uri,string action,string data ,string mimetype,iterable categories, dictionary extras,component component,iterable flags)

void drag ( tuple start, tuple end, float duration, integer steps)
start(x,y)开始的位置
end(x,y)结束位置
duration：时长，默认1秒
steps:步长，默认10

object getProperty (string key)
设备上变量的名称，返回变量的值，参数为变量的名称
KEY值参考链接最下面的附录！
object getSystemProperty (string key)
和adb shell getprop一样，同getproperty

void instaollPackage(string path)
安装app,如果已经存在，覆盖安装

dictionary instrument ( string className, dictionary args)
使用这种方法开始一个测试用例,使用Android的一个测试用例类
//不明白

void press(string name,integer type)
name：KEYCODE
type:DOWN,UP,DOWN_AND_UP

void reboot(string boootloadType)
参数可以是：bootload recovery None

void removePackage(string package)
参数：包名

object shell(string cmd)
参数：调用adb shell 命令来执行

void startActivity ( string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)
开始一个活动

MonkeyImage takeSnapshot()
捕获整个屏幕缓冲装置，产生当前显示的屏幕截图

void touch(integer x,integer y,string type)
发送一个指定位置的触摸事件。

void type(string message)
adb shell input text ‘XXXX’

void wake()
唤醒屏幕