1.    背景

使用SDK自带的NotePad应用作为实践目标应用，目的是对MonkeyDevice拥有的成员方法做一个初步的了解。

以下是官方列出的方法的Overview。

其实官方这个表是没有及时更新的，我现在手头上用到的MonkeyRunner是当前最新的，里面就拥有好几个官网没有列出来的API，我怀疑是不是自从UIAutomator在03年出来后，google就不打算再继续维护MonkeyRunner了？如果有朋友知道事实的话，还麻烦告知。

以下是我整理出来的源码多出来的可用公共API列表

但可惜的是在本人尝试以上多出来的API的时候，发现除了最上面两个可用之外，其他的都不可用并抛出错误。且网上资料少的可怜，别人碰到同样的问题也找不到解决办法。所以本人怀疑这些“隐藏”API是不是并没有完善，或者说google不准备完善，所以才没有列出到官网上面去。本人用的SDK tools和Platform tools已经是当前最新的23.0.2和20.

一个台湾网友碰到的问题描述：http://imsardine.simplbug.com/note/monkeyrunner/api/hierarchy-viewer.html

2.    Void broadcastIntent 

(string uri, string action,string data, string mimetype, iterable categories dictionary extras, componentcomponent, iterable flags)

2.1 分析

本人理解的此方法的本意是想广播一个Intent给我们的AndroidDevice，目标应用接收到该Intent做相应的处理，比如打开一个Activity等。但在我的多次尝试下并没有成功！

targetDevice.broadcastIntent(action='android.intent.action.INSERT',
                           mimetype='vnd.android.cursor.dir/contact',
                           extras = {'name':'user1501488', 'phone':'123-15489'}

如果使用同样的参数，使用下面的startActivity是没有问题的。

targetDevice.startActivity(action='android.intent.action.INSERT',
                           mimetype='vnd.android.cursor.dir/contact',
                           extras = {'name':'user1501488', 'phone':'123-15489'})

google了半天网上根本找不到这个方法的使用例子，倒是stackOverFlow上有人建议用Shell来达到同样的效果。

targetDevice.shell("am start -a android.intent.action.INSERT -t vnd.android.cursor.dir/contact -e name 'Donald Duck' -e phone 555-1234").

所以可见这个方法并没有多少人在用，原因应该是它完全可以用上面介绍的两个方法替代。

3. void startActivity 

(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, flags)

3.1 示例

targetDevice.startActivity(action='android.intent.action.VIEW',
                          mimetype='vnd.android.cursor.dir/vnd.google.note')

targetDevice.startActivity(component="com.example.android.notepad/com.example.android.notepad.NotesList")

targetDevice.startActivity(action='android.intent.action.INSERT',
                           mimetype='vnd.android.cursor.dir/contact',
                           extras = {'name':'user1501488', 'phone':'123-15489'})

4.  void drag (tuple start, tuple end, floatduration, integer steps)

这个方法的目的是按住一个控件然后把她拖动到其他位置

4.1 实例

viewer = targetDevice.getHierarchyViewer()
note = viewer.findViewById('id/text1')
point = viewer.getAbsoluteCenterOfView(note)
startX = point.x
startY = point.y

targetDevice.drag((startX,startY),(startX,startY),1)

targetDevice.press('KEYCODE_BACK', MonkeyDevice.DOWN_AND_UP)

4.2 分析和建议

以上示例是通过drag的方法来模拟LongPress，只要把参数中的起始坐标和目标坐标都设置成同样一个值，然后时常设置成一个有效的值就好了。

5 Object getProperty (string key)

 通过环境变量的key来获得其对应的值。以下是官方提供的可用化境变量列表

5.1示例

displayWidth =targetDevice.getProperty ('display.width')
printdisplayWidth.encode('utf-8')
 
displayHight =targetDevice.getProperty('display.width')
printdisplayHight.encode('utf-8')
 

5.2  分析和建议

以上示例的目的是获得目标设备的长和高，当我们使用坐标点来操作控件的时候，调试的时候在一台机器上通过了，但是如果换了另外一个屏幕大小不一样的机器的话就会失败，因为控件的坐标点位置可能就变了。这个时候我们就需要用到示例中的连个属性来动态计算控件在不同屏幕大小的设备上面的坐标点了。

这里需要注意参数应该填写的格式是以上列表中前两列的组合PropertyGroup.Property

6． Object getSystemProperty (string key)

6.1 示例

displayWidth = targetDevice.getSystemProperty ('service.adb.tcp.port')
print displayWidth.encode('utf-8')

6.2 分析和建议

根据官网的描述，这个函数和getProperty函数应该有同样的功能（Synonym for getProperty().），使用的属性表也如上面的属性列表一样。但是按照我的实践并非如此，不过它确实如官方描述的等同于命令“adb shell getprop <key>.”倒是真的。

以上的例子是获取adb这个服务所打开的TCP端口，等同于如下的shell命令：“adb shell getprop service.adb.tcp.port“

如果我尝试使用下面的方法去获得设备的长度，返回的结果其实会是None

displayWidth = targetDevice.getSystemProperty ('display.width')
print displayWidth.encode('utf-8')

7 Boolean installPackage (string path)

7.1示例

if True == targetDevice.installPackage('D:\\Projects\\Workspace\\PythonMonkeyRunnerDemo\\apps\\MPortal.apk'):
   print "Installationfinished successfully"
else:
    print "Failedto install the apk"

7.2 分析和建议

这里有两点需要注意的：

• 官方网站描述的这个API是没有返回值的（见背景中的表），而最新版本的API里面是Boolean值。
• 参数输入的应该是PC端这边的Local路径而非目标系统的Local路径。

注意这里碰到一个路径问题，如果我的路径写成：

‘D:\Projects\Workspace\PythonMonkeyRunnerDemo\apps\MPortal.apk‘

那么会出现下图这样的错误：

如果在“apps”前面加多个转义符就没有问题：

‘D:\Projects\Workspace\PythonMonkeyRunnerDemo\\apps\MPortal.apk‘

所以这里MonkeyRunner处理路径字串应该是存在Bug的，但是时间问题就先不去研究，建议所有路径的话“\“都加上转义符就好了

‘D:\\Projects\\Workspace\\PythonMonkeyRunnerDemo\\apps\MPortal.apk‘

8 boolean removePackage(string package)

8.1 示例

if True == targetDevice.removePackage('com.majcit.portal'):
   print "Succeed toremove the package"
else:
    print "Failedto remove teh package"

8.2 注意事项

·        如上面的installPackageAPI一样，官网描述的该API是没有返回值的，而最新的是返回boolean值

9. dictionary instrument (string className, dictionary args)

9.1 示例

只指定第一个参数（将会跑所有指定Component下的所有case+ NotePad项目本身的使用了Instrumentation的用例，具体意思请看下一节的分析）

dict = targetDevice.instrument('com.example.android.notepad.tryout/android.test.InstrumentationTestRunner')
print dict

指定只跑其中的一个Case：

dict = dict = targetDevice.instrument('com.example.android.notepad.tryout/android.test.InstrumentationTestRunner',
                                      {'class':'com.example.android.notepad.tryout.TCCreateNote'})
print dict

9.2 分析

这里首先需要看下官方的描述

Runs the specifiedcomponent under Android instrumentation, and returns the results in adictionary whose exact format is dictated by the component being run. Thecomponent must already be present on this device

这里重点是第一句“Runs the specified component under Android instrumentation“，剩下的是说返回值根据模块不一样而有所差别。那么第一句翻译过来就是”运行使用了Anroid Instrumentation的指定模块“。那么究竟什么是使用了Android Instrumentation的指定模块呢？其实如果你有用过Robotium的话应该知道，脚本的每个case都是从Instrumentation相关的类中继承下来的。

以下是本人之前写的一个Robotium的测试case（具体请查看本人之前的一篇《Robotium创建一个Note的实例》，可以看到它是继承于“ActivityInstrumentationTestCase2”的，其实它就满足了刚才的描述“使用了Anroid Instrumentation的指定模块“

package com.example.android.notepad.tryout;

import com.robotium.solo.Solo;

import android.test.ActivityInstrumentationTestCase2;
import android.app.Activity;

@SuppressWarnings("rawtypes")
public class TCCreateNote extends ActivityInstrumentationTestCase2{

	private static Solo solo = null;
	public Activity activity;
	
	private static final int NUMBER_TOTAL_CASES = 2;
	private static int run = 0;
	
	private static Class<?> launchActivityClass;

	//对应re-sign.jar生成出来的信息框里的两个值
	private static String mainActiviy = "com.example.android.notepad.NotesList";
	private static String packageName = "com.example.android.notepad";

	static {

		try {

			launchActivityClass = Class.forName(mainActiviy);

		} catch (ClassNotFoundException e) {

			throw new RuntimeException(e);

		}

	}
	
	
	@SuppressWarnings("unchecked")
	public TCCreateNote() {
		super(packageName, launchActivityClass);
	}

	
	@Override
	public void setUp() throws Exception {
		//setUp() is run before a test case is started. 
		//This is where the solo object is created.
		super.setUp(); 
		//The variable solo has to be static, since every time after a case's finished, this class TCCreateNote would be re-instantiated
		// which would lead to soto to re-instantiated to be null if it's not set as static
		if(solo == null) {
			TCCreateNote.solo = new Solo(getInstrumentation(), getActivity());
		}
	}
	
	@Override
	public void tearDown() throws Exception {
		//Check whether it's the last case executed.
		run += countTestCases();
		if(run >= NUMBER_TOTAL_CASES) {
			solo.finishOpenedActivities();
		}
	}

	public void testAddNoteCNTitle() throws Exception {
		
		solo.clickOnMenuItem("Add note");
		solo.enterText(0, "中文标签笔记");
		solo.clickOnMenuItem("Save");
		solo.clickInList(0);
		solo.clearEditText(0);
		solo.enterText(0, "Text 1");
		solo.clickOnMenuItem("Save");
		solo.assertCurrentActivity("Expected NotesList Activity", "NotesList");
		
		solo.clickLongOnText("中文标签笔记");
		solo.clickOnText("Delete");
	}
	
	
	public void testAddNoteEngTitle() throws Exception {
		solo.clickOnMenuItem("Add note");
		solo.enterText(0, "English Title Note");
		solo.clickOnMenuItem("Save");
		solo.clickInList(0);
		solo.clearEditText(0);
		solo.enterText(0, "Text 1");
		solo.clickOnMenuItem("Save");
		solo.assertCurrentActivity("Expected NotesList Activity", "NotesList");
		
		solo.clickLongOnText("English Title Note");
		solo.clickOnText("Delete");
	}
}

那么我们先在目标机器上执行命令“pm list instrumentation”看是否能列出这个“Component”：

这其中哪一个是我们想要的呢？这要看我们的Robotium测试项目中的AndroidManifest.xml的定义了，根据下图的packageName再对照上图的输出我们就定位到我们想要的Component了：

如果我们调用这个方法的时候只是填写了第一个参数的话，上图处在”com.example.andriod.notepad.tryout”这个Component下的所有三个方法都会执行。但在我的测试中，发现除了跑这个Case之外，它还跑多了一些步骤，就是额外的多创建了一个Note1。我查了半天，发现原来我之前除了编写了基于ActivityInstrumentationTestCase2的Robotium的这个项目之外，还在NoetePad这个项目上直接用InstrumentationTestCase写了一个基于Instrumentation的测试用例，做得事情就是增加一个Note1，具体请看本人另外一篇blog《SDK Instrumentation创建一个Note的实例》

其实调用这个方法相当于在shell脚本上执行如下的命令：

am instrument -w -r -e class com.example.android.notepad.tryout.TCCreateNote com.example.android.notepad.tryout/android.test.InstrumentationTestRunner

最后提一下的是，我们的脚本在执行示例的时候大概5秒左右就会失败，但事实上在设备端所有的指定component的测试用例已经在执行的了。要解决这个问题需要重新编译源码，这里就免了，具体请查看：http://stackoverflow.com/questions/4264057/android-cts-is-showing-shellcommandunresponsiveexception-on-emulator

这里尝试做一个简单的总结

• 调用此方法之前先要找到第一个参数怎么写：执行命令“pm list instrumentation”
•  调用次方法如果不指定第一个参数会执行指定Component下面的所有测试脚本和目标应用包中所有用到Instrumentation的测试用例
• 调用此方法最终事实上是在目标机器上根据指定的参数执行“am instrument xxxx”

10 void press (string name, integer type)

10.1 示例

targetDevice.press('KEYCODE_BACK',MonkeyDevice.DOWN_AND_UP)

10.2 分析

这个方法的目的是发送一个指定的Key事件到Android设备以触发相应的动作，比如示例中发送“KEYCODE_BACK”这个key到设备端去触发”返回“键的按下和升起（也就是点击）的动作。

具体Key的Code请查看：http://developer.android.com/reference/android/view/KeyEvent.html

第二个参数是指导该Key应该如何Behave，比如先按下去，休眠一秒再弹起来（其实就相当于一个长按的动作）。具体支持behavior在本MonkeyDevice这个类的成员变量里有定义好：

11. void touch (integer x,integer y, integer type)

11.1 示例

viewer = targetDevice.getHierarchyViewer()
note = viewer.findViewById('id/text1')
point = viewer.getAbsoluteCenterOfView(note)
startX = point.x
startY = point.y

targetDevice.touch(startX,startY，MonkeyDevice.DOWN_AND_UP)

11.2 分析

这个和上面的press方法在结果上有点类似，但是本方法是接受坐标进行点击的，而上面方法接受的是keycode。

第二个参数同上。

12. void type (string message)

viewer =targetDevice.getHierarchyViewer()

note = viewer.findViewById(‘id/text1‘)

point = viewer.getAbsoluteCenterOfView(note)

startX = point.x

startY = point.y

targetDevice.touch(startX,startY,MonkeyDevice.DOWN_AND_UP)

MonkeyRunner.sleep(3)

targetDevice.type(‘NewContent‘)

12.1 示例

viewer = targetDevice.getHierarchyViewer()
note = viewer.findViewById('id/text1')
point = viewer.getAbsoluteCenterOfView(note)
startX = point.x
startY = point.y
targetDevice.touch(startX,startY,MonkeyDevice.DOWN_AND_UP)
MonkeyRunner.sleep(3)
targetDevice.type('NewContent')

12.2 分析

指定一串字符串进行模拟键盘输入，等同于调用press方法按照一个一个的keycode用MonkeyDevice的DOWN_AND_UP进行输入。

尝试时发现中文不支持，鉴于项目不需要用到这种手机键盘，所以节省时间暂不研究。

13. Wake()

13.1示例

targetDevice.wake()

13.2 分析

注意这里只是唤醒屏保，如果手机已经锁屏的话你是不能唤醒的。所以尝试这个API的时候要注意把锁屏功能先关闭掉。

14. MonkeyImange takeSnapshot()

14.1 示例

#Connect to the target targetDevice
targetDevice = MonkeyRunner.waitForConnection()

easy_device = EasyMonkeyDevice(targetDevice)  #touch a button by id would need this
targetDevice.startActivity(component="com.example.android.notepad/com.example.android.notepad.NotesList")

#invoke the menu options
MonkeyRunner.sleep(6)
#targetDevice.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP);

'''
     public ViewNode findViewById(String id) 
     * @param id id for the view.
     * @return view with the specified ID, or {@code null} if no view found.
'''
#MonkeyRunner.alert("Continue?", "help", "Ok?")

pic = targetDevice.takeSnapshot()
pic = pic.getSubImage((0,38,480,762))

newPic = targetDevice.takeSnapshot()
newPic = newPic.getSubImage((0,38,480,762))

print (newPic.sameAs(pic,1.0))
newPic.writeToFile('./shot1.png','png')

14 object shell（string cmd）

14.1 示例

res = targetDevice.shell('ls /data/local/tmp|grep note')
print res

14.2 分析

这个命令等同于你直接在命令行上“adb shell $command”

15 void reboot(string into)

其他参数没有用到所以也就没有尝试，仅仅尝试了不带参数的情况，结果就是直接reboot目标设备了

targetDevice.reboot()