@devicefarmer/adbkit-monkey
v1.2.1
Published
A Node.js interface to the Android monkey tool.
Downloads
303,559
Readme
adbkit-monkey
adbkit-monkey provides a Node.js interface for working with the Android monkey
tool. Albeit undocumented, they monkey program can be started in TCP mode with the --port
argument. In this mode, it accepts a range of commands that can be used to interact with the UI in a non-random manner. This mode is also used internally by the monkeyrunner
tool, 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() to open a new TCP connection to monkey. Useful when combined with adb forward
.
- options Any options
Net.connect()
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
. - Returns: A new monkey
Client
instance.
Client
Implements Api
. See below for details.
Events
The following events are available:
- error (err) Emitted when an error occurs.
- err An
Error
.
- err An
- 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. SeeMulti
below.
client.send(command, callback)
Sends a raw protocol command to monkey.
- command The command to send. When
String
, a single command is sent. WhenArray
, 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.
- err
- 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.
- err
- Returns: The
Api
implementation instance.
api.flipClose(callback)
Simulates closing the keyboard.
- callback(err) Called when monkey responds.
- err
null
when successful,Error
otherwise.
- err
- Returns: The
Api
implementation instance.
api.flipOpen(callback)
Simulates opening the keyboard.
- callback(err) Called when monkey responds.
- err
null
when successful,Error
otherwise.
- err
- 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.
- err
- 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. All monkeys support numeric keycodes, and some support automatic conversion from key names to key codes (e.g.
'home'
toKEYCODE_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.
- err
- 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.
- err
- 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()
.
- err
- 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.
- err
- 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.
- err
- 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.
- err
- 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.
- err
- 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.
- err
- 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.
- err
- 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.
- err
- 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.
- err
- 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 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.
- err
- 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.
- err
- 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.
- err
More information
Contributing
See CONTRIBUTING.md.
License
See LICENSE.
Copyright © CyberAgent, Inc. All Rights Reserved.