adbkit-monkey

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]: