adbkit-monkey

Warning

This project along with other ones in OpenSTF organisation is provided as is for community, without active development.

You can check any other forks that may be actively developed and offer new/different features here.

Active development has been moved to DeviceFarmer organisation.

adbkit-monkey provides a [Node.js][nodejs] interface for working with the Android [monkey tool][monkey-site]. Albeit undocumented, they monkey program can be started in TCP mode with the --port argument. In this mode, it accepts a [range of commands][monkey-proto] that can be used to interact with the UI in a non-random manner. This mode is also used internally by the [monkeyrunner tool][monkeyrunner-site], although the documentation claims no relation to the monkey tool.

Getting started

Install via NPM:

``bash
npm install --save adbkit-monkey
`

Note that while adbkit-monkey is written in CoffeeScript, it is compiled to JavaScript before publishing to NPM, which means that you are not required to use CoffeeScript.

$3

The following examples assume that monkey is already running (via adb shell monkey --port 1080) and a port forwarding (adb forward tcp:1080 tcp:1080) has been set up.

#### Press the home button

`javascript
var assert = require('assert');
var monkey = require('adbkit-monkey');

var client = monkey.connect({ port: 1080 });

client.press(3 / KEYCODE_HOME /, function(err) {
assert.ifError(err);
console.log('Pressed home button');
client.end();
});
`

#### Drag out the notification bar

`javascript
var assert = require('assert');
var monkey = require('adbkit-monkey');

var client = monkey.connect({ port: 1080 });

client.multi()
.touchDown(100, 0)
.sleep(5)
.touchMove(100, 20)
.sleep(5)
.touchMove(100, 40)
.sleep(5)
.touchMove(100, 60)
.sleep(5)
.touchMove(100, 80)
.sleep(5)
.touchMove(100, 100)
.sleep(5)
.touchUp(100, 100)
.sleep(5)
.execute(function(err) {
assert.ifError(err);
console.log('Dragged out the notification bar');
client.end();
});
`

#### Get display size

`javascript
var assert = require('assert');
var monkey = require('adbkit-monkey');

var client = monkey.connect({ port: 1080 });

client.getDisplayWidth(function(err, width) {
assert.ifError(err);
client.getDisplayHeight(function(err, height) {
assert.ifError(err);
console.log('Display size is %dx%d', width, height);
client.end();
});
});
`

#### Type text

Note that you should manually focus a text field first.

`javascript
var assert = require('assert');
var monkey = require('adbkit-monkey');

var client = monkey.connect({ port: 1080 });

client.type('hello monkey!', function(err) {
assert.ifError(err);
console.log('Said hello to monkey');
client.end();
});
`

API

$3

#### monkey.connect(options)

Uses [Net.connect()][node-net] to open a new TCP connection to monkey. Useful when combined with adb forward.

* options Any options [Net.connect()][node-net] accepts.
* Returns: A new monkey Client instance.

#### monkey.connectStream(stream)

Attaches a monkey client to an existing monkey protocol stream.

* stream The monkey protocol [Stream][node-stream].
* Returns: A new monkey Client instance.

$3

Implements Api. See below for details.

#### Events

The following events are available:

* error (err) Emitted when an error occurs.
* err An Error.
* end Emitted when the stream ends.
* finish Emitted when the stream finishes.

#### client.end()

Ends the underlying stream/connection.

* Returns: The Client instance.

#### client.multi()

Returns a new API wrapper that buffers commands for simultaneous delivery instead of sending them individually. When used with api.sleep(), allows simple gestures to be executed.

* Returns: A new Multi instance. See Multi below.

#### client.send(command, callback)

Sends a raw protocol command to monkey.

* command The command to send. When String, a single command is sent. When Array, a series of commands is sent at once.
* callback(err, value, command) Called when monkey responds to the command. If multiple commands were sent, the callback will be called once for each command.
* err null when successful, Error otherwise.
* value The response value, if any.
* command The command the response is for.
* Returns: The Client instance.

$3

The monkey API implemented by Client and Multi.

#### api.done(callback)

Closes the current monkey session and allows a new session to connect.

* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.flipClose(callback)

Simulates closing the keyboard.

* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.flipOpen(callback)

Simulates opening the keyboard.

* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.get(name, callback)

Gets the value of a variable. Use api.list() to retrieve a list of supported variables.

* name The name of the variable.
* callback(err, value) Called when monkey responds.
* err null when successful, Error otherwise.
* value The value of the variable.
* Returns: The Api implementation instance.

#### api.getAmCurrentAction(callback)

Alias for api.get('am.current.action', callback).

#### api.getAmCurrentCategories(callback)

Alias for api.get('am.current.categories', callback).

#### api.getAmCurrentCompClass(callback)

Alias for api.get('am.current.comp.class', callback).

#### api.getAmCurrentCompPackage(callback)

Alias for api.get('am.current.comp.package', callback).

#### api.getCurrentData(callback)

Alias for api.get('am.current.data', callback).

#### api.getAmCurrentPackage(callback)

Alias for api.get('am.current.package', callback).

#### api.getBuildBoard(callback)

Alias for api.get('build.board', callback).

#### api.getBuildBrand(callback)

Alias for api.get('build.brand', callback).

#### api.getBuildCpuAbi(callback)

Alias for api.get('build.cpu_abi', callback).

#### api.getBuildDevice(callback)

Alias for api.get('build.device', callback).

#### api.getBuildDisplay(callback)

Alias for api.get('build.display', callback).

#### api.getBuildFingerprint(callback)

Alias for api.get('build.fingerprint', callback).

#### api.getBuildHost(callback)

Alias for api.get('build.host', callback).

#### api.getBuildId(callback)

Alias for api.get('build.id', callback).

#### api.getBuildManufacturer(callback)

Alias for api.get('build.manufacturer', callback).

#### api.getBuildModel(callback)

Alias for api.get('build.model', callback).

#### api.getBuildProduct(callback)

Alias for api.get('build.product', callback).

#### api.getBuildTags(callback)

Alias for api.get('build.tags', callback).

#### api.getBuildType(callback)

Alias for api.get('build.type', callback).

#### api.getBuildUser(callback)

Alias for api.get('build.user', callback).

#### api.getBuildVersionCodename(callback)

Alias for api.get('build.version.codename', callback).

#### api.getBuildVersionIncremental(callback)

Alias for api.get('build.version.incremental', callback).

#### api.getBuildVersionRelease(callback)

Alias for api.get('build.version.release', callback).

#### api.getBuildVersionSdk(callback)

Alias for api.get('build.version.sdk', callback).

#### api.getClockMillis(callback)

Alias for api.get('clock.millis', callback).

#### api.getClockRealtime(callback)

Alias for api.get('clock.realtime', callback).

#### api.getClockUptime(callback)

Alias for api.get('clock.uptime', callback).

#### api.getDisplayDensity(callback)

Alias for api.get('display.density', callback).

#### api.getDisplayHeight(callback)

Alias for api.get('display.height', callback). Note that the height may exclude any virtual home button row.

#### api.getDisplayWidth(callback)

Alias for api.get('display.width', callback).

#### api.keyDown(keyCode, callback)

Sends a key down event. Should be coupled with api.keyUp(). Note that api.press() performs the two events automatically.

* keyCode The [key code][android-keycodes]. All monkeys support numeric keycodes, and some support automatic conversion from key names to key codes (e.g. 'home' to KEYCODE_HOME). This will not work for number keys however. The most portable method is to simply use numeric key codes.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.keyUp(keyCode, callback)

Sends a key up event. Should be coupled with api.keyDown(). Note that api.press() performs the two events automatically.

* keyCode See api.keyDown().
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.list(callback)

Lists supported variables.

* callback(err, vars) Called when monkey responds.
* err null when successful, Error otherwise.
* vars An array of supported variable names, to be used with api.get().
* Returns: The Api implementation instance.

#### api.press(keyCode, callback)

Sends a key press event.

* keyCode See api.keyDown().
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.quit(callback)

Closes the current monkey session and quits monkey.

* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.sleep(ms, callback)

Sleeps for the given duration. Can be useful for simulating gestures.

* ms How many milliseconds to sleep for.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.tap(x, y, callback)

Taps the given coordinates.

* x The x coordinate.
* y The y coordinate.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.touchDown(x, y, callback)

Sends a touch down event on the given coordinates.

* x The x coordinate.
* y The y coordinate.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.touchMove(x, y, callback)

Sends a touch move event on the given coordinates.

* x The x coordinate.
* y The y coordinate.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.touchUp(x, y, callback)

Sends a touch up event on the given coordinates.

* x The x coordinate.
* y The y coordinate.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.trackball(x, y, callback)

Sends a trackball event on the given coordinates.

* x The x coordinate.
* y The y coordinate.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.type(text, callback)

Types the given text.

* text A text String. Note that only characters for which [key codes][android-keycodes] exist can be entered. Also note that any IME in use may or may not transform the text.
* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

#### api.wake(callback)

Wakes the device from sleep and allows user input.

* callback(err) Called when monkey responds.
* err null when successful, Error otherwise.
* Returns: The Api implementation instance.

$3

Buffers Api commands and delivers them simultaneously for greater control over timing.

Implements all Api methods, but without the last callback parameter.

#### multi.execute(callback)

Sends all buffered commands.

* callback(err, values) Called when monkey has responded to all commands (i.e. just once at the end).
* err null when successful, Error otherwise.
* values An array of all response values, identical to individual Api` responses.

More information

* [Monkey][monkey-site]
- [Source code][monkey-source]
- [Protocol][monkey-proto]
* [Monkeyrunner][monkeyrunner-site]

Contributing

See CONTRIBUTING.md.

License

See LICENSE.

Copyright © CyberAgent, Inc. All Rights Reserved.

[nodejs]:
[monkey-site]:
[monkey-source]:
[monkey-proto]:
[monkeyrunner-site]:
[node-net]:
[node-stream]:
[android-keycodes]: