adbkit-monkey

A Node.js interface to the Android monkey tool.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
adbkit-monkey
4851.0.19 years ago9 years agoMinified + gzip package size for adbkit-monkey in KB

Readme

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

Getting started

Install via NPM:
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.

Examples

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

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

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

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.
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

Monkey

monkey.connect(options)

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

monkey.connectStream(stream)

Attaches a monkey client to an existing monkey protocol stream.

Client

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.

Api

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 codeandroid-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 codesandroid-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.

Multi

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

- [Source code][monkey-source]
- [Protocol][monkey-proto]

Contributing

See CONTRIBUTING.md.

License

See LICENSE.
Copyright © CyberAgent, Inc. All Rights Reserved.