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
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)endSession()
Ends the active session or cancels any pending session requests.
await client.endSession()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)biometryEnrollment()
Sets the biometry enrollment status (iOS Only)
await session.biometryEnrollment(true/false)biometry()
Simulate a matching fingerprint (Android 8+ only) or Face ID (iOS)
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:
HOMEVOLUME_UP(Android)VOLUME_DOWN(Android)ANDROID_KEYCODE_MENU(Android)LOCK_SCREEN(Android)UNLOCK_SCREEN(Android)TOGGLE_SCREEN_LOCK(iOS)
openUrl()
Opens a deep-link or web URL
await session.openUrl("https://appetize.io")launchApp(appId)
Launches the specified application using the provided appId.
await session.launchApp(appId)Parameters
appId
string
Android:
The app's package name / appId (e.g., com.example.app) or packageName/activityName. If no activity name is specified, it defaults to the main launch activity.
iOS:
The app's bundle identifier (e.g., com.example.app).
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
await session.shake()toggleSoftKeyboard()
Toggles the soft keyboard (iOS only)
await session.toggleSoftKeyboard()setLanguage()
Changes the current language.
await session.setLanguage("fr")If your app does not automatically handle language/locale changes, you would need to explicitly call restartApp for this to take effect. Some apps might also cache data in the previously used language. In these cases use reinstallApp to clear any previous cached data.
type()
Types the given text
await session.type("hello")Typing is limited to 1000 characters at a time to ensure optimal performance and prevent potential disruptions. For larger payloads, you can use multiple 'type' operations.
addMedia(file)
Upload media to the device.
await session.addMedia(file)Last updated