uiautomator2-ts

TypeScript client for automating Android devices through the uiautomator2 JSON-RPC service.

Acknowledgement

This project is heavily inspired by the original Python uiautomator2 project by openatx.

• Original project: https://github.com/openatx/uiautomator2
• This project: a TypeScript/Node.js implementation designed for direct usage in scripts, agents, and npm distribution.

Project Layout

uiautomator2-ts/
  src/                # TypeScript source
  dist/esm/           # ESM build output
  dist/cjs/           # CommonJS build output
  README.md
  SKILL.md            # LLM automation playbook
  PUBLISHING.md       # GitHub + npm release guide
  package.json
  tsconfig.json
  tsconfig.cjs.json

Requirements

• Node.js >= 18
• Android device with uiautomator2 JSON-RPC service running
• Typical RPC endpoint: http://<device-ip>:9008/jsonrpc/0

Install and Build

npm install
npm run build

Build artifacts:

• ESM: dist/esm/index.js
• CJS: dist/cjs/index.js
• Types: dist/esm/index.d.ts

Usage

As an npm package (recommended)

CommonJS:

const { Device } = require('@uiautomator2/typescript-device');

ESM:

import { Device } from '@uiautomator2/typescript-device';

Local repository usage

const { Device } = require('./dist/cjs/device');

Device Initialization

const d = new Device({
  rpcUrl: 'http://192.168.50.27:9008/jsonrpc/0',
  defaultTimeoutMs: 30000,
});

await d.ping();
console.log(await d.app_current());

Core Capabilities

• d.xpath(...): recommended primary locator API for dynamic UI
• d.$({...}): Python-style selector facade
• watcher/watch_context: lightweight watchers
• app_*: app lifecycle helpers
• send_keys/set_text/clear_text: input APIs with Chinese input fallback logic

Quick Examples

// app lifecycle
await d.app_start('com.twitter.android');
console.log(await d.app_current());

// xpath
const btn = d.xpath('//*[@text="Post"]');
if (await btn.exists()) await btn.click();

// Python-like selector
const field = d.$({ className: 'android.widget.EditText' });
await field.set_text('Hello from automation');

// relative selector
await d.$({ text: 'Wi-Fi' }).right({ className: 'android.widget.Switch' }).click();

Before Publishing to npm

1. Replace placeholder repository metadata in package.json:

• homepage
• repository.url
• bugs.url

2. Bump version
3. Run:

npm run clean && npm run build
npm run typecheck
npm pack

4. Follow PUBLISHING.md

License

MIT