{"id":28375259,"url":"https://github.com/openstf/adbkit-monkey","last_synced_at":"2025-06-26T05:32:40.131Z","repository":{"id":12121138,"uuid":"14711443","full_name":"openstf/adbkit-monkey","owner":"openstf","description":"A Node.js interface to the Android monkey tool.","archived":false,"fork":false,"pushed_at":"2020-08-15T13:56:03.000Z","size":60,"stargazers_count":47,"open_issues_count":5,"forks_count":36,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-06-24T06:04:47.930Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openstf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-11-26T08:47:58.000Z","updated_at":"2025-01-22T10:45:18.000Z","dependencies_parsed_at":"2022-09-02T22:10:43.379Z","dependency_job_id":null,"html_url":"https://github.com/openstf/adbkit-monkey","commit_stats":null,"previous_names":["cyberagent/adbkit-monkey"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/openstf/adbkit-monkey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openstf%2Fadbkit-monkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openstf%2Fadbkit-monkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openstf%2Fadbkit-monkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openstf%2Fadbkit-monkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openstf","download_url":"https://codeload.github.com/openstf/adbkit-monkey/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openstf%2Fadbkit-monkey/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261618106,"owners_count":23185091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T22:36:51.166Z","updated_at":"2025-06-26T05:32:40.117Z","avatar_url":"https://github.com/openstf.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adbkit-monkey\n\n# Warning\n# This project along with other ones in [OpenSTF](https://github.com/openstf) organisation is provided as is for community, without active development.\n# You can check any other forks that may be actively developed and offer new/different features [here](https://github.com/openstf/stf/network).\n# Active development has been moved to [DeviceFarmer](https://github.com/DeviceFarmer) organisation.\n\n**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.\n\n## Getting started\n\nInstall via NPM:\n\n```bash\nnpm install --save adbkit-monkey\n```\n\nNote 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.\n\n### Examples\n\nThe 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.\n\n#### Press the home button\n\n```javascript\nvar assert = require('assert');\nvar monkey = require('adbkit-monkey');\n\nvar client = monkey.connect({ port: 1080 });\n\nclient.press(3 /* KEYCODE_HOME */, function(err) {\n  assert.ifError(err);\n  console.log('Pressed home button');\n  client.end();\n});\n```\n\n#### Drag out the notification bar\n\n```javascript\nvar assert = require('assert');\nvar monkey = require('adbkit-monkey');\n\nvar client = monkey.connect({ port: 1080 });\n\nclient.multi()\n  .touchDown(100, 0)\n  .sleep(5)\n  .touchMove(100, 20)\n  .sleep(5)\n  .touchMove(100, 40)\n  .sleep(5)\n  .touchMove(100, 60)\n  .sleep(5)\n  .touchMove(100, 80)\n  .sleep(5)\n  .touchMove(100, 100)\n  .sleep(5)\n  .touchUp(100, 100)\n  .sleep(5)\n  .execute(function(err) {\n    assert.ifError(err);\n    console.log('Dragged out the notification bar');\n    client.end();\n  });\n```\n\n#### Get display size\n\n```javascript\nvar assert = require('assert');\nvar monkey = require('adbkit-monkey');\n\nvar client = monkey.connect({ port: 1080 });\n\nclient.getDisplayWidth(function(err, width) {\n  assert.ifError(err);\n  client.getDisplayHeight(function(err, height) {\n    assert.ifError(err);\n    console.log('Display size is %dx%d', width, height);\n    client.end();\n  });\n});\n```\n\n#### Type text\n\nNote that you should manually focus a text field first.\n\n```javascript\nvar assert = require('assert');\nvar monkey = require('adbkit-monkey');\n\nvar client = monkey.connect({ port: 1080 });\n\nclient.type('hello monkey!', function(err) {\n  assert.ifError(err);\n  console.log('Said hello to monkey');\n  client.end();\n});\n```\n\n## API\n\n### Monkey\n\n#### monkey.connect(options)\n\nUses [Net.connect()][node-net] to open a new TCP connection to monkey. Useful when combined with `adb forward`.\n\n* **options** Any options [`Net.connect()`][node-net] accepts.\n* Returns: A new monkey `Client` instance.\n\n#### monkey.connectStream(stream)\n\nAttaches a monkey client to an existing monkey protocol stream.\n\n* **stream** The monkey protocol [`Stream`][node-stream].\n* Returns: A new monkey `Client` instance.\n\n### Client\n\nImplements `Api`. See below for details.\n\n#### Events\n\nThe following events are available:\n\n* **error** **(err)** Emitted when an error occurs.\n    * **err** An `Error`.\n* **end** Emitted when the stream ends.\n* **finish** Emitted when the stream finishes.\n\n#### client.end()\n\nEnds the underlying stream/connection.\n\n* Returns: The `Client` instance.\n\n#### client.multi()\n\nReturns 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.\n\n* Returns: A new `Multi` instance. See `Multi` below.\n\n#### client.send(command, callback)\n\nSends a raw protocol command to monkey.\n\n* **command** The command to send. When `String`, a single command is sent. When `Array`, a series of commands is sent at once.\n* **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.\n    * **err** `null` when successful, `Error` otherwise.\n    * **value** The response value, if any.\n    * **command** The command the response is for.\n* Returns: The `Client` instance.\n\n### Api\n\nThe monkey API implemented by `Client` and `Multi`.\n\n#### api.done(callback)\n\nCloses the current monkey session and allows a new session to connect.\n\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.flipClose(callback)\n\nSimulates closing the keyboard.\n\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.flipOpen(callback)\n\nSimulates opening the keyboard.\n\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.get(name, callback)\n\nGets the value of a variable. Use `api.list()` to retrieve a list of supported variables.\n\n* **name** The name of the variable.\n* **callback(err, value)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n    * **value** The value of the variable.\n* Returns: The `Api` implementation instance.\n\n#### api.getAmCurrentAction(callback)\n\nAlias for `api.get('am.current.action', callback)`.\n\n#### api.getAmCurrentCategories(callback)\n\nAlias for `api.get('am.current.categories', callback)`.\n\n#### api.getAmCurrentCompClass(callback)\n\nAlias for `api.get('am.current.comp.class', callback)`.\n\n#### api.getAmCurrentCompPackage(callback)\n\nAlias for `api.get('am.current.comp.package', callback)`.\n\n#### api.getCurrentData(callback)\n\nAlias for `api.get('am.current.data', callback)`.\n\n#### api.getAmCurrentPackage(callback)\n\nAlias for `api.get('am.current.package', callback)`.\n\n#### api.getBuildBoard(callback)\n\nAlias for `api.get('build.board', callback)`.\n\n#### api.getBuildBrand(callback)\n\nAlias for `api.get('build.brand', callback)`.\n\n#### api.getBuildCpuAbi(callback)\n\nAlias for `api.get('build.cpu_abi', callback)`.\n\n#### api.getBuildDevice(callback)\n\nAlias for `api.get('build.device', callback)`.\n\n#### api.getBuildDisplay(callback)\n\nAlias for `api.get('build.display', callback)`.\n\n#### api.getBuildFingerprint(callback)\n\nAlias for `api.get('build.fingerprint', callback)`.\n\n#### api.getBuildHost(callback)\n\nAlias for `api.get('build.host', callback)`.\n\n#### api.getBuildId(callback)\n\nAlias for `api.get('build.id', callback)`.\n\n#### api.getBuildManufacturer(callback)\n\nAlias for `api.get('build.manufacturer', callback)`.\n\n#### api.getBuildModel(callback)\n\nAlias for `api.get('build.model', callback)`.\n\n#### api.getBuildProduct(callback)\n\nAlias for `api.get('build.product', callback)`.\n\n#### api.getBuildTags(callback)\n\nAlias for `api.get('build.tags', callback)`.\n\n#### api.getBuildType(callback)\n\nAlias for `api.get('build.type', callback)`.\n\n#### api.getBuildUser(callback)\n\nAlias for `api.get('build.user', callback)`.\n\n#### api.getBuildVersionCodename(callback)\n\nAlias for `api.get('build.version.codename', callback)`.\n\n#### api.getBuildVersionIncremental(callback)\n\nAlias for `api.get('build.version.incremental', callback)`.\n\n#### api.getBuildVersionRelease(callback)\n\nAlias for `api.get('build.version.release', callback)`.\n\n#### api.getBuildVersionSdk(callback)\n\nAlias for `api.get('build.version.sdk', callback)`.\n\n#### api.getClockMillis(callback)\n\nAlias for `api.get('clock.millis', callback)`.\n\n#### api.getClockRealtime(callback)\n\nAlias for `api.get('clock.realtime', callback)`.\n\n#### api.getClockUptime(callback)\n\nAlias for `api.get('clock.uptime', callback)`.\n\n#### api.getDisplayDensity(callback)\n\nAlias for `api.get('display.density', callback)`.\n\n#### api.getDisplayHeight(callback)\n\nAlias for `api.get('display.height', callback)`. Note that the height may exclude any virtual home button row.\n\n#### api.getDisplayWidth(callback)\n\nAlias for `api.get('display.width', callback)`.\n\n#### api.keyDown(keyCode, callback)\n\nSends a key down event. Should be coupled with `api.keyUp()`. Note that `api.press()` performs the two events automatically.\n\n* **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.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.keyUp(keyCode, callback)\n\nSends a key up event. Should be coupled with `api.keyDown()`. Note that `api.press()` performs the two events automatically.\n\n* **keyCode** See `api.keyDown()`.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.list(callback)\n\nLists supported variables.\n\n* **callback(err, vars)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n    * **vars** An array of supported variable names, to be used with `api.get()`.\n* Returns: The `Api` implementation instance.\n\n#### api.press(keyCode, callback)\n\nSends a key press event.\n\n* **keyCode** See `api.keyDown()`.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.quit(callback)\n\nCloses the current monkey session and quits monkey.\n\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.sleep(ms, callback)\n\nSleeps for the given duration. Can be useful for simulating gestures.\n\n* **ms** How many milliseconds to sleep for.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.tap(x, y, callback)\n\nTaps the given coordinates.\n\n* **x** The x coordinate.\n* **y** The y coordinate.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.touchDown(x, y, callback)\n\nSends a touch down event on the given coordinates.\n\n* **x** The x coordinate.\n* **y** The y coordinate.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.touchMove(x, y, callback)\n\nSends a touch move event on the given coordinates.\n\n* **x** The x coordinate.\n* **y** The y coordinate.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.touchUp(x, y, callback)\n\nSends a touch up event on the given coordinates.\n\n* **x** The x coordinate.\n* **y** The y coordinate.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.trackball(x, y, callback)\n\nSends a trackball event on the given coordinates.\n\n* **x** The x coordinate.\n* **y** The y coordinate.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.type(text, callback)\n\nTypes the given text.\n\n* **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.\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n#### api.wake(callback)\n\nWakes the device from sleep and allows user input.\n\n* **callback(err)** Called when monkey responds.\n    * **err** `null` when successful, `Error` otherwise.\n* Returns: The `Api` implementation instance.\n\n### Multi\n\nBuffers `Api` commands and delivers them simultaneously for greater control over timing.\n\nImplements all `Api` methods, but without the last `callback` parameter.\n\n#### multi.execute(callback)\n\nSends all buffered commands.\n\n* **callback(err, values)** Called when monkey has responded to all commands (i.e. just once at the end).\n    * **err** `null` when successful, `Error` otherwise.\n    * **values** An array of all response values, identical to individual `Api` responses.\n\n## More information\n\n* [Monkey][monkey-site]\n    - [Source code][monkey-source]\n    - [Protocol][monkey-proto]\n* [Monkeyrunner][monkeyrunner-site]\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nSee [LICENSE](LICENSE).\n\nCopyright © CyberAgent, Inc. All Rights Reserved.\n\n[nodejs]: \u003chttp://nodejs.org/\u003e\n[monkey-site]: \u003chttp://developer.android.com/tools/help/monkey.html\u003e\n[monkey-source]: \u003chttps://github.com/android/platform_development/blob/master/cmds/monkey/\u003e\n[monkey-proto]: \u003chttps://github.com/android/platform_development/blob/master/cmds/monkey/README.NETWORK.txt\u003e\n[monkeyrunner-site]: \u003chttp://developer.android.com/tools/help/monkeyrunner_concepts.html\u003e\n[node-net]: \u003chttp://nodejs.org/api/net.html\u003e\n[node-stream]: \u003chttp://nodejs.org/api/stream.html\u003e\n[android-keycodes]: \u003chttp://developer.android.com/reference/android/view/KeyEvent.html\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenstf%2Fadbkit-monkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenstf%2Fadbkit-monkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenstf%2Fadbkit-monkey/lists"}