Overview

MonkeyRunner is a tool built using Jython (a Python implementation on the Java platform) that provides an API for controlling Android devices or emulators from outside of Android code. It allows writing Python scripts to install applications, run tests, send input events, and capture screenshots for debugging purposes.

The tool is primarily used for functional testing and unit test suites but can be adapted for other automation tasks.

Path: Android_SDK\tools

Key Features

1. Multi-device control: Supports running test suites across multiple devices simultaneously.
2. Functional testing: Enables automated execution of functional tests and captures output screenshots.
3. Extensible automation: Offers an API-based approach to build custom systems for controlling Android devices.

MonkeyRunner vs. Monkey

MonkeyRunner differs from Monkey in that it uses APIs to send specific commands and events rather than generating random events via adb shell commands.

Setup Instructions

• Install and configure JDK
• Install Android SDK
• Install Python
• Set environment variables to include {Path}\Android_SDK\tools

Verification

Run the command 'monkeyrunner' in the console. If the following output appears, the setup was successful:

C:\Users\Shuqing>monkeyrunner

Jython 2.5.3 (2.5:c56500f08d34+, Aug 13 2012, 14:54:35) [Java HotSpot(TM) 64-Bit Server VM (Oracle Corporation)] on java1.8.0_05 >>>

Tip: Exit the MonkeyRunner CLI by pressing Ctrl+D.

MonkeyRunner API

Three main classes are used:

1. MonkeyRunner
2. MonkeyDevice
3. MonkeyImage

Official API documentation: http://www.android-doc.com/tools/help/monkeyrunner_concepts.html#

Class: MonkeyRunner

Provides methods for connecting to devices, sending input, pausing, and displaying alerts.

Common Methods

waitForConnection(float timeout, string deviceid)

from com.android.monkeyrunner import MonkeyRunner as mr print("connect devices...") device = mr.waitForConnection()

Class: MonkeyDevice

Offers functions for installing/uninstalling apps, starting activities, sending key events, and running tests.

Common Methods

• installPackage(string path)
• removePackage(string package)
• startActivity(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, flags)
• touch(integer x, integer y, integer type)

Parameters for touch: integer x: x-coordinate integer y: y-coordinate integer type: event type (DOWN, UP, DOWN_AND_UP)

• drag(tuple start, tuple end, float duration, integer steps)

Parameters for drag: tuple start: starting point (x,y) tuple end: ending point (x,y) float duration: gesture duration (default 1.0s) integer steps: number of interpolation points (default 10)

Example

Connect to device, install app, and launch it

from com.android.monkeyrunner import MonkeyRunner as mr
from com.android.monkeyrunner import MonkeyDevice as md

print("connect devices...")
device = mr.waitForConnection()

print("install app...")
device.installPackage(r'C:\Users\Shuqing\Desktop\kaoyan3.1.0.apk')

package = 'com.tal.kaoyan'
activity = 'com.tal.kaoyan.ui.activity.SplashActivity'
runComponent = package + '/' + activity

print("launch App...")
device.startActivity(component=runComponent)

Class: MonkeyImage

Used to save screenshots and perform image comparisons during testing.

Common Methods

• takeSnapshot(): Capture screen screenshot
• writeToFile(): Save image file to specified path

Example

from com.android.monkeyrunner import MonkeyImage as mi print("takeSnapshot") screenshot = device.takeSnapshot() screenshot.writeToFile(r'E:\monkeyrunner_script\test.png', 'png')

Test Scenario

• Connect device
• Install and launch app
• Log in with username and password
• Take screenshot

Script Implementation

from com.android.monkeyrunner import MonkeyRunner as mr
from com.android.monkeyrunner import MonkeyDevice as md
from com.android.monkeyrunner import MonkeyImage as mi

print("connect devices...")
device = mr.waitForConnection()

print("install app")
device.installPackage(r'C:\Users\Shuqing\Desktop\kaoyan3.1.0.apk')

print("launch app...")
package = 'com.tal.kaoyan'
activity = 'com.tal.kaoyan.ui.activity.SplashActivity'
runComponent = package + '/' + activity

device.startActivity(component=runComponent)
mr.sleep(3)

print("touch cancel button")
device.touch(618, 895, 'DOWN_AND_UP')
mr.sleep(1)

print("touch skip button")
device.touch(804, 67, 'DOWN_AND_UP')
mr.sleep(1)

print("input username and password")
device.touch(57, 373, 'DOWN_AND_UP')
mr.sleep(2)
device.type('zxw1234')

device.touch(152, 480, 'DOWN_AND_UP')
mr.sleep(2)
device.type('zxw123456')
mr.sleep(2)

print("touch login button")
device.touch(331, 634, 'DOWN_AND_UP')

print("takeSnapshot")
screenshot = device.takeSnapshot()
screenshot.writeToFile(r'D:\monkeyrunner\kyb.png', 'png')

Notes

Method call errors: AttributeError: type object 'com.android.monkeyrunner.XXXXX' has no attribute XXXXXX Check method names for typos, especially case sensitivity.

Encoding errors: SyntaxError: Non-ASCII character in file 'E:\monkeyrunner_script\kyb.py', but no encoding declared; Add # -- coding: utf-8 -- at the top of the script or remove non-ASCII characters.