appium-android-bootstrap

appium-android-bootstrap

JavaScript interface, and Java code, for interacting with Android UI Automator. The system allows ad hoc commands to be sent to the device, which are executed using Android's UIAutomator testing framework.

Technical details

The system works by a com.android.uiautomator.testrunner.UiAutomatorTestCase placed on the Android device, which opens a SocketServer on port 4724. This server receives commands, converts them to appropriate Android UI Automator commands, and runs them in the context of the device.

The commands are sent through the JavaScript interface.

UiAutomator interface

Appium's UiAutomator interface has two methods start and shutdown.

async start (uiAutomatorBinaryPath, className, startDetector, ...extraParams)

start will push uiAutomatorBinary to device and start UiAutomator with className and return the SubProcess. startDetector and extraParams are optional arguments. startDetector will be used as condition to check against your output stream of test if any. extraParams will be passed along as command line arguments when starting the subProcess.

shutdown will kill UiAutomator process on the device and also kill the subProcess.

import { UiAutomator } from 'appium-android-bootstrap';
import ADB from 'appium-adb';

let adb = await ADB.createADB();
let uiAutomator = new UiAutomator(adb);

let startDetector = (s) => { return /Appium Socket Server Ready/.test(s); };
await uiAutomator.start('foo/bar.jar', 'io.appium.android.bootstrap.Bootstrap',
                        startDetector, '-e', 'disableAndroidWatchers', true);
await uiAutomator.shutdown();

Usage

The module provides an AndroidBootstrap class, which is instantiated with an instance of appium-adb, a system port (defaults to 4724) and an optional web socket. The object then has four async methods:

async start (appPackage, disableAndroidWatchers)

• appPackage - The package name for the application under test (e.g., 'com.example.android.apis').
• disableAndroidWatchers - Whether or not to watch Android events. Defaults to false.

import AndroidBootstrap from 'appium-android-bootstrap';

let androidBootstrap = new AndroidBootstrap();
await androidBootstrap.start('com.example.android.apis', false);

async shutdown ()

Shuts down all services. Stops UI Automator process on device, and kills communication.

await androidBootstrap.shutdown();

async sendCommand (type, extra, cmdTimeout)

Send a command to the device.

• type - The type of command being sent. The two valid types are action and shutdown. These are exported as the enumeration COMMAND_TYPES
• extra - A hash of extra parameters to send to the device.
• cmdTimeout - The amount of time, in ms, to wait for the device to respond. Defaults to 10000.

let dataDir = await androidBootstrap.sendCommand(COMMAND_TYPES.ACTION, {action: 'getDataDir'});
// dataDir === '/data'

async sendAction (action, params)

Send an action command to the device. Equavalent to sendCommand ('action', {action: action, params: params}).

• action - The action to be sent.
• params - Parameters for the action.

let dataDir = await androidBootstrap.sendAction('getDataDir');
// dataDir === '/data'

COMMAND_TYPES

An enumeration of the available types of commands, to be used for sendCommand. The members are ACTION, and SHUTDOWN.

Development

Building the Bootstrap Jar

This package builds with an older version of the Android tools, using ant.

To build the Java system, make sure ant is installed.

In order to have both the current Android tools and the ones needed for this package, do the following:

1. Copy your $ANDROID_HOME directory (where the Android SDK is installed) to another location.
2. Download the Android 22 tools
   • MacOS: http://dl-ssl.google.com/android/repository/tools_r22-macosx.zip
   • Linux: http://dl-ssl.google.com/android/repository/tools_r22-linux.zip
   • Windows: http://dl-ssl.google.com/android/repository/tools_r22-windows.zip
3. Replace the tools directory in the copied Android SDK directory with the Android 22 tools just downloaded
4. Create/edit bootstrap/local.properties file, adding
   • sdk.dir=/path/to/copied/android/sdk

Now you should be able to build the Jar file by running

npm run build:jar

Watch

npm run watch

Test

npm run test

npm run e2e-test