description
The Session in Appetize makes it easy to manage and interact with device sessions, including simulating user actions, toggling device states, retrieving device information and more.

Session

Methods

on()

Listens for an event of the given name

session.on(event, data => {
   console.log(data)
})

Event	Data Type	Description
action	RecordedAction	A user action has been recorded. This can be played back later with playAction. Requires record to be set to `true`
appLaunch	`void`	App launch event occurred.
audio	`{` `buffer: Uint8Array, codec: 'aac',` `duration: number` `}`	Audio frames of the current session. Requires audio to be set to `true`
error	`{ message: string }`	An error has occurred on the session
firstFrameReceived	`void`	First video frame received.
inactivityWarning	`{ secondsRemaining: number }`	Session is about to timeout due to inactivity. Any user interaction or a heartbeat will reset the timeout.
interaction	UserInteraction	User has interacted with the device.
log	`{ message: string }`	Debug log from the device Requires debug to be set to `true`
network	NetworkRequest \| NetworkResponse	Intercepted network request or responses. Requires proxy to be set to `intercept`
orientationChanged	`'portrait' \| 'landscape'`	The device has changed orientation
video	`{` `buffer: Uint8Array,` `width: number,` `height: number,` `codec: string` `}`	Video frames of the current session. These frames can be muxed (e.g. using jmuxer) to turn it into a video format. When codec is `jpeg` the buffers are of jpeg images.
end	`void`	The session has ended

end()

Ends the session

await session.end()

rotate()

Rotates the device 90 degrees

await session.rotate('right')

Parameters

Name	Type	Description
direction	`"left" \| "right"`	The direction to rotate

screenshot(format)

Takes a screenshot of the device and returns the data

const { data, mimeType } = await session.screenshot(format)

Parameters

Name	Type	Description
format?	`"buffer" \| "base64"`	The format of the screenshot data to return. Defaults to `buffer`

heartbeat()

Sends a heartbeat to the server, resetting the inactivity timer

await session.heartbeat()

tap(target, options)

Taps on the screen at the given position, coordinate or element

await session.tap({ position: { x: '50%', y: '50%' } })
await session.tap({ coordinates: { x: 100, y: 100 } })
await session.tap({ element: { attributes: { text: 'OK' } } })

Parameters

Name	Type	Description
target.coordinates?	`{` `x: number` `y: number` `}`	The coordinates in dip units
target.position?	`{` `x: string` `y: string` `}`	The position on screen in %
target.element?	`ElementSelector`	An element selector
target.duration?	`number`	Duration of the tap
options.timeout?	`number`	If an element is provided, the amount of time to wait for it to appear in ms (defaults 10s)
options.matchIndex?	`number`	If multiple elements match the element selector, select the nth one

swipe(target, options)

Swipes on the screen at the given position, coordinate or element

await session.swipe({ position: { x: '50%', y: '50%' }, gesture: 'up' })
await session.swipe({ coordinates: { x: 100, y: 100 }, gesture: 'up' })
await session.swipe({ element: { attributes: { text: 'OK' } }, gesture: 'up' })


target.coordinates?	`{` `x: number` `y: number` `}`	The coordinates in dip units to start the swipe
target.position?	`{` `x: string` `y: string` `}`	The position on screen in %
target.element?	`ElementSelector`	An element selector
target.duration?	`number`	Duration of the swipe
target.gesture	`string \| function`	The gesture of the swipe. See swipe for more details
options.timeout?	`number`	If an element is provided, the amount of time to wait for it to appear in ms (defaults 10s)
options.matchIndex?	`number`	If multiple elements match the element selector, select the nth one

type(text)

Types the given text on the device

await session.type("hello")

Parameters

Name	Type	Description
text	`string`	Text to type

{% hint style="warning" %} 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. {% endhint %}

keypress(character, options)

Sends a single key press to the device

await session.keypress("a")

Parameters

Name	Type	Description
key	`string`	Key to send to the device ('a', 'b', etc.) Also takes special values for hardware keys: `HOME` Android Only: `VOLUME_UP` `VOLUME_DOWN` `ANDROID_KEYCODE_MENU` `LOCK_SCREEN` `UNLOCK_SCREEN` iOS Only: `TOGGLE_SCREEN_LOCK`
options.shift?	`boolean`

setAppearance(appearance)

(iOS 13+ and Android 10+) Sets dark or light mode UI.

await session.setAppearance("dark")

Parameters

Name	Type
appearance	`"dark" \| "light"`

setLanguage(language)

Changes the current language and restarts the app

await session.setLanguage("fr")

{% hint style="warning" %} 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. {% endhint %}

Parameters

Name	Type	Description
language	`string`	Language code

setLocation(lat, long)

Sets the simulated location of the device.

await setLocation(-33.924434, 18.418391)

Parameters

Name	Type	Description
latitude	`number`	Decimal number between -90 and 90, representing the degrees of north or south of the Equator. Negative numbers indicate south of the Equator, and positive numbers indicate north of the Equator.
longitude	`number`	Decimal number between -180 and 180, representing the degrees of east or west of the Prime Meridian. Negative numbers indicate west of the Prime Meridian, and positive numbers indicate east of the Prime Meridian.

openUrl(url)

Opens a deep-link or web URL

await session.openUrl("https://appetize.io")

Parameters

Name	Type	Description
`url`	`string`	The URL

shake()

Shakes device

await session.shake()

toggleSoftKeyboard()

Toggles the soft keyboard (iOS only)

await session.toggleSoftKeyboard()

biometryEnrollment(isEnrolled)

Sets the biometry enrollment status (iOS Only)

await session.biometryEnrollment(true/false)

biometry(match)

Simulate a matching fingerprint (Android 8+ only) or Face ID (iOS)

await session.biometry({
    match: true/false
})

allowInteractions(enabled)

Enables or disables all interactions on the device. Default is true.

await session.allowInteractions(true/false)

adbShellCommand(command)

Executes an adb shell command on the device (Android only)

await session.adbShellCommand("am start -a android.intent.action.VIEW -d https://appetize.io/")

launchApp(appId)

Launches the specified application using the provided appId.

{% hint style="info" %} If the app is already running, it will be brought to the foreground instead of being relaunched. If the app was originally launched with params or a launchUrl, these will also be passed with this method. {% endhint %}

await session.launchApp(appId)

Parameters

Name	Type	Description
`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()

getUI()

Returns the UI as an XML string

await session.getUI()

{% hint style="warning" %} Experimental
The data structure of the response is subject to change {% endhint %}

{% tabs %} {% tab title="Old Engine" %} Returns an array of elements, with app and system content separated into two sections.

[
  {
    "type": "app",
    "appId": {running app},
    "children": [ ... ] // Your app content
  },
  {
    "type": "app",
    "appId": "com.apple.springboard",
    "children": [ ... ] // Springboard (system UI) content
  }
]

{% endtab %}

{% tab title="New Engine" %} A single combined hierarchy is returned, representing what’s actually visible to the user.

[
  {
    "type": "app",
    "appId": {possible appId},
    "children": [ ... ] // All visible content on screen (e.g. Springboard/Navigation etc. related content too)
  }
]

{% endtab %} {% endtabs %}

addMedia(file)

{% hint style="info" %} The maximum file size for uploading media is 50 MB. {% endhint %}

Upload media to the device.

await session.addMedia(file)

Platform specific format support applies. See the Media - Supported File Types documentation for supported file types on Android and iOS.

findElement(selector)

Returns an element that matches the selector. See Targeting Elements.

This is useful for waiting until an element appears.

const element = await session.findElement({
    attributes: {
        text: "Home"
    }
})

If multiple elements are found it will return the first element.

findElements(selector)

Returns an array of all elements matching that selector. See Targeting Elements.

const elements = await session.findElements({
    attributes: { 
       accessibilityLabel: 'Like post'
    }
})

playAction(action, options)

Play an automation Action or array of Actions.

await session.playAction(action)

Parameters

Name	Type	Description
action	`Record<string, any>`	Actions emitted from the `session.on('action')` event
options.timeout?	`number`	Amount of time in ms to wait for the action to succeed (default 10s)

playActions(actions, options)

Plays an array of actions.

await session.playActions(actions)

Parameters

Name	Type	Description
actions	`Array<Record<string, any>>`	Actions emitted from the `session.on('action')` event
options.timeout?	`number`	Amount of time in ms to wait for an action to succeed (default 10s)

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)

Parameters

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)

waitForEvent(event, options)

Waits for an event to occur

const networkEvent = await session.waitForEvent('network')

const requestEvent = await session.waitForEvent('network', event => {
    // resolves only when this condition is met
    return event.type === 'request'
})

Parameters

Name	Type	Description
event	`string`	One of the session events.
options.timeout?	`number \| null`	The maximum time (in milliseconds) to wait for the event to be emitted.
options.predicate?	`(data: T) => boolean`	The predicate condition to be satisfied, otherwise the function will continue to wait for the event.

waitForTimeout(timeout)

Waits for the given time to elapse (in ms)

await session.waitForTimeout(5000)

Parameters

Name	Type	Description
timeout	`number`	Timeout in milliseconds.

waitUntilReady()

Waits until the session is fully initialised and ready for use.

Properties

adbConnection

Info for connecting to the Android devices via adb. Requires enableAdb to be true.

See AdbConnectionInfo.

app

The Appetize app for the session, if applicable.

See AppetizeApp.

config

The config applied to the current session.

See SessionConfig.

device

The current device. See DeviceInfo.

networkInspectorUrl

The URL to chrome dev tools to inspect network logs. Requires proxy to be set to intercept.

path

The URL to the Appetizer server.

token

The token of the Appetize session.

FilesExpand file tree

session.md

Latest commit

History

session.md

File metadata and controls

Session

Methods

on()

action

appLaunch

audio

error

firstFrameReceived

inactivityWarning

interaction

log

network

orientationChanged

video

end

end()

rotate()

screenshot(format)

heartbeat()

tap(target, options)

swipe(target, options)

type(text)

keypress(character, options)

setAppearance(appearance)

setLanguage(language)

setLocation(lat, long)

Parameters

openUrl(url)

shake()

toggleSoftKeyboard()

biometryEnrollment(isEnrolled)

biometry(match)

allowInteractions(enabled)

adbShellCommand(command)

launchApp(appId)

restartApp()

reinstallApp()

getUI()

addMedia(file)

findElement(selector)

findElements(selector)

playAction(action, options)

playActions(actions, options)

waitForAnimations(options)

waitForEvent(event, options)

waitForTimeout(timeout)

waitUntilReady()

Properties

adbConnection

app

config

device

networkInspectorUrl

path

token