Links

Device commands

The client provides methods to configure the device and start a session, while the session provides methods for user interaction.

Client

startSession()

Starts a session with the requested app, device, operating system, and other launch options.
const session = await client.startSession()
Parameters
Name
Type
Description
config?
Record<string, any>
A JSON object describing the Configuration options for the device.

setConfig()

Update the configured app, device, operating system, or other launch options. See Configuration for acceptable values.
Note: This will end any active sessions.
await client.setConfig(config)

Session

adbShellCommand

Executes an adb shell command on the device (Android only)
await session.adbShellCommand("am start -a android.intent.action.VIEW -d https://appetize.io/")

allowInteractions()

Enables or disables all interactions on the device.
await session.allowInteractions(false)

biometry()

Simulate a matching fingerprint (Android 8+ only)
await session.biometry({
match: true/false
})

end()

Ends the session
await session.end()

getUI()

Experimental The data structure of the response is subject to change
Returns an array of elements describing the current UI on the device.
const ui = await session.getUI()
/*
[
{ type: 'app', appId: 'com.my.app', children: [...] },
{ type: 'app', appId: 'com.apple.springboard', children: [...] }
]
*/

heartbeat()

Sends a heartbeat to the server, resetting the inactivity timer of the session
await session.heartbeat()

keypress()

Sends a single key press to the device.
await session.keypress("a")
This can also be used to send hardware keys:
  • HOME
  • VOLUME_UP (Android)
  • VOLUME_DOWN (Android)
  • ANDROID_KEYCODE_MENU (Android)

openUrl()

Opens a deep-link or web URL
await session.openUrl("https://appetize.io")

restartApp()

Restarts the app
await session.restartApp()

reinstallApp()

Reinstalls the app
await session.reinstallApp()

rotate()

Rotates the device 90 degrees left or right
await session.rotate('left')
await session.rotate('right')

screenshot()

Takes a screenshot of the device and returns the data as a buffer.
const { data, mimeType } = await session.screenshot()
Alternatively, it can return the data as a base64 encoded string
const { data, mimeType } = await session.screenshot('base64')

shake()

Shakes device (iOS only)
await session.shake()

toggleSoftKeyboard()

Toggles the soft keyboard (iOS only)
await session.toggleSoftKeyboard()

setLanguage()

Changes the current language and restarts the app
await session.setLanguage("fr")

type()

Types the given text
await session.type("hello")

waitForAnimations(options)

Waits until the there are no ongoing animations on the screen by waiting for the image to stabilize for at least 1 second.
await session.waitForAnimations(options)
Name
Type
Description
options.imageThreshold?
number
The threshold for the amount of pixels (in %) that can change between frames before the image is considered to be stable. (default 0.001)
options.timeout?
number
The maximum amount of time (in ms) to wait for the image to stabilize. (default 10s)