Command Reference

Commands

background

POST /session/:sessionId/appium/app/background

Close app (simulate device home button). It is possible to restore the app after the timeout or keep it minimized based on the parameter value.

Parameters

Name	Type	Description
seconds	number | { timeout: null | number }	any positive number of seconds: come back after X seconds - any negative number of seconds or zero: never come back - undefined/null: never come back - {timeout: 5000}: come back after 5 seconds - {timeout: null}, {timeout: -2}: never come back

Response

any

closeApp

POST /session/:sessionId/appium/app/close

Stop the session without stopping the session

Response

null

launchApp

POST /session/:sessionId/appium/app/launch

Start the session after it has been started.

Response

null

reset

POST /session/:sessionId/appium/app/reset

Reset the current session (run the delete session and create session subroutines)

Deprecated

Use explicit session management commands instead

Response

null

getStrings

POST /session/:sessionId/appium/app/strings

Return the language-specific strings for an app

Parameters

Name	Type	Default value	Description
language?	string	undefined	the language to retrieve strings for
stringFile?	null | string	null	the path to the localized strings file if not in the default location

Response

Object

A record of localized keys to localized text

queryAppState

POST /session/:sessionId/appium/device/app_state

Get the running state of an app

Response

AppState

A number representing the state. 0 means not installed, 1 means not running, 2 means running in background but suspended, 3 means running in the background, and 4 means running in the foreground

getClipboard

POST /session/:sessionId/appium/device/get_clipboard

Gets the content of the primary clipboard on the device under test.

Parameters

Name	Type	Description
contentType?	string	The type of the content to get. Only plaintext, 'image and 'url' are supported.

Response

string

The actual clipboard content encoded into base64 string. An empty string is returned if the clipboard contains no data.

isLocked

POST /session/:sessionId/appium/device/is_locked

Determine whether the device is locked

Response

boolean

true if the device is locked, false otherwise

lock

POST /session/:sessionId/appium/device/lock

Lock the device (and optionally unlock the device after a certain amount of time)

Default Value

0

Parameters

Name	Type	Description
seconds?	string | number	the number of seconds after which to unlock the device. Set to 0 or leave empty to require manual unlock (do not automatically unlock).

Response

null

setClipboard

POST /session/:sessionId/appium/device/set_clipboard

Sets the primary clipboard's content on the device under test.

Parameters

Name	Type	Description
content	string	The content to be set as base64 encoded string.
contentType?	string	The content to be set as base64 encoded string.
label?	string	The type of the content to set. Only plaintext, 'image and 'url' are supported.

Response

null

mobileShake

POST /session/:sessionId/appium/device/shake

Shake the device

Response

null

unlock

POST /session/:sessionId/appium/device/unlock

Unlock the device

Response

null

setValueImmediate

POST /session/:sessionId/appium/element/:elementId/value

Deprecated

Parameters

Name	Type
text	string

Response

null

receiveAsyncResponse

POST /session/:sessionId/appium/receive_async_response

Collect the response of an async script execution

Deprecated

Parameters

Name	Type
response	any

Response

null

toggleEnrollTouchId

POST /session/:sessionId/appium/simulator/toggle_touch_id_enrollment

Toggle whether the device is enrolled in the touch ID program

Parameters

Name	Type	Default value	Description
enabled?	boolean	true	whether to enable or disable the touch ID program

Response

null

touchId

POST /session/:sessionId/appium/simulator/touch_id

Trigger a touch/fingerprint match or match failure

Parameters

Name	Type	Default value	Description
match	boolean	true	whether the match should be a success or failure

Response

null

startRecordingScreen

POST /session/:sessionId/appium/start_recording_screen

Direct Appium to start recording the device screen

Record the display of devices running iOS Simulator since Xcode 9 or real devices since iOS 11 (ffmpeg utility is required: 'brew install ffmpeg'). It records screen activity to a MPEG-4 file. Audio is not recorded with the video file. If screen recording has been already started then the command will stop it forcefully and start a new one. The previously recorded video file will be deleted.

Throws

If screen recording has failed to start.

Parameters

Name	Type	Description
options?	StartRecordingScreenOptions	The available options.

Response

string

Base64-encoded content of the recorded media file if any screen recording is currently running or an empty string.

stopRecordingScreen

POST /session/:sessionId/appium/stop_recording_screen

Direct Appium to stop screen recording and return the video

If no screen recording process is running then the endpoint will try to get the recently recorded file. If no previously recorded file is found and no active screen recording processes are running then the method returns an empty string.

Throws

If there was an error while getting the name of a media file or the file content cannot be uploaded to the remote location.

Parameters

Name	Type	Description
options?	StopRecordingScreenOptions	The available options.

Response

null | string

Base64-encoded content of the recorded media file if remotePath parameter is empty or null or an empty string.

getLocation

GET /session/:sessionId/element/:elementId/location

Get the position of an element on screen

Deprecated

Use XCUITestDriver.getElementRect instead

Response

Position

The position of the element

getLocationInView

GET /session/:sessionId/element/:elementId/location_in_view

Alias for XCUITestDriver.getLocation

Deprecated

Use XCUITestDriver.getElementRect instead

Response

Position

The position of the element

getSize

GET /session/:sessionId/element/:elementId/size

Get the size of an element

Response

Size

The position of the element

submit

POST /session/:sessionId/element/:elementId/submit

Submit the form an element is in

Response

null

keys

POST /session/:sessionId/keys

Send keys to the app

Deprecated

Use XCUITestDriver.setValue instead

Parameters

Name	Type	Description
value	string[]	Array of keys to send

Response

null

moveTo

POST /session/:sessionId/moveto

Move the mouse pointer to a particular screen location

Deprecated

Use XCUITestDriver.performActions instead

Parameters

Name	Type	Default value	Description
element?	string | Element<string>	undefined	the element ID if the move is relative to an element
xoffset?	number	0	the x offset
yoffset?	number	0	the y offset

Response

null

asyncScriptTimeout

POST /session/:sessionId/timeouts/async_script

Alias for XCUITestDriver.scriptTimeoutW3C.

Deprecated

Use XCUITestDriver.scriptTimeoutW3C instead

Parameters

Name	Type	Description
ms	number	the timeout

Response

null

implicitWait

POST /session/:sessionId/timeouts/implicit_wait

Set the implicit wait timeout

Deprecated

Use timeouts instead

Parameters

Name	Type	Description
ms	string | number	the timeout in ms

Response

null

click

POST /session/:sessionId/touch/click

Click/tap an element

See

https://w3c.github.io/webdriver/#element-click

Parameters

Name	Type
element	any

Response

any

performMultiAction

POST /session/:sessionId/touch/multi/perform

Perform a set of touch actions

Deprecated

Use XCUITestDriver.performActions instead

Parameters

Name	Type	Description
actions	any[]	the old MJSONWP style touch action objects
elementId?	any[]	the old MJSONWP style touch action objects

Response

any

performTouch

POST /session/:sessionId/touch/perform

Perform a set of touch actions

Deprecated

Use XCUITestDriver.performActions instead

Parameters

Name	Type	Description
actions	any[]	the old MJSONWP style touch action objects

Response

any

getWindowSize

GET /session/:sessionId/window/:windowhandle/size

Get the window size

Deprecated

Use XCUITestDriver.getWindowRect instead.

Response

any

getPageSource

GET /session/:sessionId/source

Get the current page/app source as HTML/XML

See

https://w3c.github.io/webdriver/#get-page-source

Response

any

The UI hierarchy in a platform-appropriate format (e.g., HTML for a web page)

getSettings

GET /session/:sessionId/appium/settings

Get the current settings for the session

Response

StringRecord<any>

The settings object

updateSettings

POST /session/:sessionId/appium/settings

Get the current settings for the session

Required Parameters

• settings

Response

StringRecord<any>

The settings object

createSession

POST /session

Historically the first two arguments were reserved for JSONWP capabilities. Appium 2 has dropped the support of these, so now we only accept capability objects in W3C format and thus allow any of the three arguments to represent the latter.

See

https://w3c.github.io/webdriver/#new-session

Parameters

Name	Type	Description
desiredCapabilities?	any	the new session capabilities
requiredCapabilities?	any	another place the new session capabilities could be sent (typically left undefined)
capabilities?	any	another place the new session capabilities could be sent (typically left undefined)

Response

[string, DriverCaps<{ absoluteWebLocations: { isBoolean: true = true } ; additionalWebviewBundleIds: {} = {}; agentPath: { isString: true = true } ; allowProvisioningDeviceRegistration: { isBoolean: true = true } ; app: { isString: true = true } ; appInstallStrategy: { inclusionCaseInsensitive: readonly ["serial", "parallel", "ios-deploy"] ; isString: true = true } ; appPushTimeout: { isNumber: true = true } ; autoAcceptAlerts: { isBoolean: true = true } ; autoDismissAlerts: { isBoolean: true = true } ; bootstrapPath: { isString: true = true } ; browserName: { isString: true = true } ; bundleId: { isString: true = true } ; calendarAccessAuthorized: { isBoolean: true = true } ; calendarFormat: { isString: true = true } ; clearSystemFiles: { isBoolean: true = true } ; commandTimeouts: {} = {}; connectHardwareKeyboard: { isBoolean: true = true } ; customSSLCert: { isString: true = true } ; derivedDataPath: { isString: true = true } ; deviceName: { isString: true = true } ; disableAutomaticScreenshots: { isBoolean: true = true } ; enableAsyncExecuteFromHttps: { isBoolean: true = true } ; enablePerformanceLogging: { isBoolean: true = true } ; enforceAppInstall: { isBoolean: true = true } ; enforceFreshSimulatorCreation: { isBoolean: true = true } ; forceAppLaunch: { isBoolean: true = true } ; forceTurnOnSoftwareKeyboardSimulator: { isBoolean: true = true } ; fullContextList: { isBoolean: true = true } ; ignoreAboutBlankUrl: { isBoolean: true = true } ; includeDeviceCapsToSessionInfo: { isBoolean: true = true } ; includeSafariInWebviews: { isBoolean: true = true } ; iosInstallPause: { isNumber: true = true } ; iosSimulatorLogsPredicate: { isString: true = true } ; isHeadless: { isBoolean: true = true } ; keepKeyChains: { isBoolean: true = true } ; keychainPassword: { isString: true = true } ; keychainPath: { isString: true = true } ; keychainsExcludePatterns: { isString: true = true } ; launchWithIDB: { isBoolean: true = true } ; localizableStringsDir: { isString: true = true } ; maxTypingFrequency: { isNumber: true = true } ; mjpegScreenshotUrl: { isString: true = true } ; mjpegServerPort: { isNumber: true = true } ; nativeTyping: { isBoolean: true = true } ; nativeWebTap: { isBoolean: true = true } ; nativeWebTapStrict: { isBoolean: true = true } ; otherApps: { isString: true = true } ; permissions: { isString: true = true } ; platformName: { inclusionCaseInsensitive: readonly ["iOS", "tvOS"] ; isString: true = true; presence: true = true } ; prebuildWDA: { isBoolean: true = true } ; processArguments: {} = {}; reduceMotion: { isBoolean: true = true } ; reduceTransparency: { isBoolean: true = true } ; remoteDebugProxy: { isString: true = true } ; resetLocationService: { isBoolean: true = true } ; resetOnSessionStartOnly: { isBoolean: true = true } ; resultBundlePath: { isString: true = true } ; resultBundleVersion: { isNumber: true = true } ; safariAllowPopups: { isBoolean: true = true } ; safariGarbageCollect: { isBoolean: true = true } ; safariGlobalPreferences: { isObject: true = true } ; safariIgnoreFraudWarning: { isBoolean: true = true } ; safariIgnoreWebHostnames: { isString: true = true } ; safariInitialUrl: { isString: true = true } ; safariLogAllCommunication: { isBoolean: true = true } ; safariLogAllCommunicationHexDump: { isBoolean: true = true } ; safariOpenLinksInBackground: { isBoolean: true = true } ; safariShowFullResponse: { isBoolean: true = true } ; safariSocketChunkSize: { isNumber: true = true } ; safariWebInspectorMaxFrameLength: { isNumber: true = true } ; scaleFactor: { isString: true = true } ; screenshotQuality: { isNumber: true = true } ; shouldTerminateApp: { isBoolean: true = true } ; shouldUseSingletonTestManager: { isBoolean: true = true } ; showIOSLog: { isBoolean: true = true } ; showSafariConsoleLog: { isBoolean: true = true } ; showSafariNetworkLog: { isBoolean: true = true } ; showXcodeLog: { isBoolean: true = true } ; shutdownOtherSimulators: { isBoolean: true = true } ; simpleIsVisibleCheck: { isBoolean: true = true } ; simulatorDevicesSetPath: { isString: true = true } ; simulatorPasteboardAutomaticSync: { isString: true = true } ; simulatorStartupTimeout: { isNumber: true = true } ; simulatorTracePointer: { isBoolean: true = true } ; simulatorWindowCenter: { isString: true = true } ; skipLogCapture: { isBoolean: true = true } ; udid: { isString: true = true } ; updatedWDABundleId: { isString: true = true } ; useJSONSource: { isBoolean: true = true } ; useNativeCachingStrategy: { isBoolean: true = true } ; useNewWDA: { isBoolean: true = true } ; usePrebuiltWDA: { isBoolean: true = true } ; useSimpleBuildTest: { isBoolean: true = true } ; useXctestrunFile: { isBoolean: true = true } ; waitForIdleTimeout: { isNumber: true = true } ; waitForQuiescence: { isBoolean: true = true } ; wdaBaseUrl: { isString: true = true } ; wdaConnectionTimeout: { isNumber: true = true } ; wdaEventloopIdleDelay: { isNumber: true = true } ; wdaLaunchTimeout: { isNumber: true = true } ; wdaLocalPort: { isNumber: true = true } ; wdaStartupRetries: { isNumber: true = true } ; wdaStartupRetryInterval: { isNumber: true = true } ; webDriverAgentUrl: { isString: true = true } ; webkitResponseTimeout: { isNumber: true = true } ; webviewConnectRetries: { isNumber: true = true } ; webviewConnectTimeout: { isNumber: true = true } ; xcodeConfigFile: { isString: true = true } ; xcodeOrgId: { isString: true = true } ; xcodeSigningId: { isString: true = true } }>]

The capabilities object representing the created session

deleteSession

DELETE /session/:sessionId

Get session capabilities merged with what WDA reports This is a library command but needs to call 'super' so can't be on a helper object

Response

any

A session data object

getSession

GET /session/:sessionId

Get session capabilities merged with what WDA reports This is a library command but needs to call 'super' so can't be on a helper object

Response

any

A session data object

findElement

POST /session/:sessionId/element

Find a UI element given a locator strategy and a selector, erroring if it can't be found

See

https://w3c.github.io/webdriver/#find-element

Parameters

Name	Type	Description
using	string	the locator strategy
value	string	the selector to combine with the strategy to find the specific element

Response

Element<string>

The element object encoding the element id which can be used in element-related commands

findElementFromElement

POST /session/:sessionId/element/:elementId/element

Find a UI element given a locator strategy and a selector, erroring if it can't be found. Only look for elements among the set of descendants of a given element

See

https://w3c.github.io/webdriver/#find-element-from-element

Parameters

Name	Type	Description
using	string	the locator strategy
value	string	the selector to combine with the strategy to find the specific element

Response

Element<string>

The element object encoding the element id which can be used in element-related commands

findElementFromShadowRoot

POST /session/:sessionId/shadow/:shadowId/element

Find an element from a shadow root

See

https://w3c.github.io/webdriver/#find-element-from-shadow-root

Parameters

Name	Type	Description
using	string	the locator strategy
value	string	the selector to combine with the strategy to find the specific elements

Response

Element<string>

The element inside the shadow root matching the selector

findElements

POST /session/:sessionId/elements

Find a a list of all UI elements matching a given a locator strategy and a selector

See

https://w3c.github.io/webdriver/#find-elements

Parameters

Name	Type	Description
using	string	the locator strategy
value	string	the selector to combine with the strategy to find the specific elements

Response

Element<string>[]

A possibly-empty list of element objects

findElementsFromElement

POST /session/:sessionId/element/:elementId/elements

Find a a list of all UI elements matching a given a locator strategy and a selector. Only look for elements among the set of descendants of a given element

See

https://w3c.github.io/webdriver/#find-elements-from-element

Parameters

Name	Type	Description
using	string	the locator strategy
value	string	the selector to combine with the strategy to find the specific elements

Response

Element<string>[]

A possibly-empty list of element objects

findElementsFromShadowRoot

POST /session/:sessionId/shadow/:shadowId/elements

Find elements from a shadow root

See

https://w3c.github.io/webdriver/#find-element-from-shadow-root

Parameters

Name	Type	Description
using	string	the locator strategy
value	string	the selector to combine with the strategy to find the specific elements

Response

Element<string>[]

A possibly empty list of elements inside the shadow root matching the selector

getLog

POST /session/:sessionId/log

Get the log for a given log type.

Parameters

Name	Type	Description
type	string	Name/key of log type as defined in ILogCommands.supportedLogTypes.

Response

unknown[]

getLog

POST /session/:sessionId/se/log

Get the log for a given log type.

Parameters

Name	Type	Description
type	string	Name/key of log type as defined in ILogCommands.supportedLogTypes.

Response

unknown[]

getLogEvents

POST /session/:sessionId/appium/events

Get a list of events that have occurred in the current session

Parameters

Name	Type	Description
type?	string | string[]	filter the returned events by including one or more types

Response

EventHistory | Record<string, number>

The event history for the session

getLogTypes

GET /session/:sessionId/log/types

Get available log types as a list of strings

Response

string[]

getLogTypes

GET /session/:sessionId/se/log/types

Get available log types as a list of strings

Response

string[]

getSessions

GET /sessions

Get data for all sessions running on an Appium server

Response

MultiSessionData<Constraints>[]

A list of session data objects

getStatus

GET /status

Summary

Retrieve the server's current status.

Description

Returns information about whether a remote end is in a state in which it can create new sessions and can additionally include arbitrary meta information that is specific to the implementation.

The readiness state is represented by the ready property of the body, which is false if an attempt to create a session at the current time would fail. However, the value true does not guarantee that a New Session command will succeed.

Implementations may optionally include additional meta information as part of the body, but the top-level properties ready and message are reserved and must not be overwritten.

Examples

JavaScript

// webdriver.io example
await driver.status();

Python

driver.get_status()

Java

driver.getStatus();

Ruby

# ruby_lib example
remote_status

# ruby_lib_core example
@driver.remote_status

Response

Object

getTimeouts

GET /session/:sessionId/timeouts

Set the various timeouts associated with a session

See

https://w3c.github.io/webdriver/#set-timeouts

Response

null

timeouts

POST /session/:sessionId/timeouts

Set the various timeouts associated with a session

See

https://w3c.github.io/webdriver/#set-timeouts

Parameters

Name	Type	Description
type?	string	used only for the old (JSONWP) command, the type of the timeout
ms?	string | number	used only for the old (JSONWP) command, the ms for the timeout
script?	number	the number in ms for the script timeout, used for the W3C command
pageLoad?	number	the number in ms for the pageLoad timeout, used for the W3C command
implicit?	string | number	the number in ms for the implicit wait timeout, used for the W3C command

Response

null

logCustomEvent

POST /session/:sessionId/appium/log_event

Add a custom-named event to the Appium event log

Parameters

Name	Type	Description
vendor	string	the name of the vendor or tool the event belongs to, to namespace the event
event	string	the name of the event itself

Response

null

Execute Methods

Script: mobile: activateApp

Route

POST /session/:sessionId/execute

Parameters

Name	Type
bundleId	string

Response

any

Script: mobile: activeAppInfo

Returns ActiveApp info.

Throws

if an error raised by command

Route

POST /session/:sessionId/execute

Response

any

The response of /wda/activeAppInfo'

Script: mobile: alert

Route

POST /session/:sessionId/execute

Parameters

Name	Type
action	AlertAction
buttonLabel?	AlertAction

Response

any

Script: mobile: batteryInfo

Reads the battery information from the device under test. This endpoint only returns reliable result on real devices.

Route

POST /session/:sessionId/execute

Response

BatteryInfo

The actual battery info

Script: mobile: clearKeychains

Clears keychains on Simulator.

Throws

If current device is not a Simulator or there was an error while clearing keychains.

Route

POST /session/:sessionId/execute

Response

null

Script: mobile: configureLocalization

Change localization settings on the currently booted simulator

Throws

If there was a failure while setting the preferences

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
keyboard?	KeyboardOptions	Keyboard options
language?	LanguageOptions	Language options
locale?	LocaleOptions	Locale options

Response

boolean

true if any of settings has been successfully changed

Script: mobile: deepLink

Opens the given URL with the default or the given application

Route

POST /session/:sessionId/execute

Parameters

Name	Type
url	string
bundleId?	string

Response

any

Script: mobile: deleteFile

Delete a remote file from the device.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
remotePath	string	The full path to the remote file or a specially formatted path, which points to an item inside app bundle. See the documentation for pullFromRealDevice and pullFromSimulator to get more information on acceptable values.

Response

null

Script: mobile: deleteFolder

Delete a remote folder from the device.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
remotePath	string	The full path to the remote folder or a specially formatted path, which points to an item inside app bundle. See the documentation for pullFromRealDevice and pullFromSimulator to get more information on acceptable values.

Response

null

Script: mobile: deviceInfo

Returns device info.

Throws

if an error raised by command

Route

POST /session/:sessionId/execute

Response

any

The response of /wda/device/info'

Script: mobile: deviceScreenInfo

memoized in constructor

Route

POST /session/:sessionId/execute

Response

any

Script: mobile: disableConditionInducer

Disable condition inducer this call upon driver deletion

Route

POST /session/:sessionId/execute

Response

boolean

true if disable the condition succeeded

Script: mobile: doubleTap

Route

POST /session/:sessionId/execute

Parameters

Name	Type
elementId?	string | Element<string>
x?	number
y?	number

Response

any

Script: mobile: dragFromToForDuration

Route

POST /session/:sessionId/execute

Parameters

Name	Type
duration	number
fromX	number
fromY	number
toX	number
toY	number
elementId?	number

Response

any

Script: mobile: dragFromToWithVelocity

Route

POST /session/:sessionId/execute

Parameters

Name	Type
pressDuration	number
holdDuration	number
velocity	number
fromElementId?	number
toElementId?	number
fromX?	number
fromY?	string | Element<string>
toX?	string | Element<string>
toY?	number

Response

any

Script: mobile: enableConditionInducer

Enable a "condition inducer". You can create a condition on a connected device to test your app under adverse conditions, such as poor network connectivity or thermal constraints. When you start a device condition, the operating system on the device behaves as if its environment has changed. The device condition remains active until you stop the device condition or disconnect the device. For example, you can start a device condition, run your app, monitor your app’s energy usage, and then stop the condition.

(Note: the socket needs to remain connected during operation) (Note: Device conditions are available only for real devices running iOS 13.0 and later.)

Throws

If you try to start another Condition and the previous Condition has not stopped

Since

4.9.0

See

https://help.apple.com/xcode/mac/current/#/dev308429d42

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
conditionID	string	Determine which condition IDs are available with the listConditionInducers command
profileID	string	Determine which profile IDs are available with the listConditionInducers command

Response

boolean

true if enabling the condition succeeded

Script: mobile: enrollBiometric

Enrolls biometric authentication on Simulator.

Throws

If enrollment fails or the device is not a Simulator.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
isEnabled?	boolean	true	Whether to enable/disable biometric enrollment.

Response

null

Script: mobile: expectNotification

Blocks until the expected notification is delivered.

This method is a thin wrapper over XCTNSNotificationExpectation and XCTDarwinNotificationExpectation entities.

Throws

TimeoutError if the expected notification has not been delivered within the given timeout

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
name	string	undefined	The name of the notification to expect
type?	string	undefined	The name of the notification to expect
timeoutSeconds?	NotificationType	'plain'	Which notification type to expect.

Response

any

Script: mobile: forcePress

Route

POST /session/:sessionId/execute

Parameters

Name	Type
x?	number
y?	number
duration?	number
pressure?	number
elementId?	string | Element<string>

Response

any

Script: mobile: getAppStrings

Return the language-specific strings for an app

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
language?	string	undefined	the language to retrieve strings for
stringFile?	null | string	null	the path to the localized strings file if not in the default location

Response

Object

A record of localized keys to localized text

Script: mobile: getAppearance

Get the device's UI appearance style.

Since

Xcode SDK 11

Route

POST /session/:sessionId/execute

Response

Object

Script: mobile: getContexts

Get the contexts available, with information about the url and title of each webview

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
waitForWebviewMs?	number	0	The period to poll for available webviews (in ms)

Response

Context[]

List of Context objects

Script: mobile: getDeviceTime

Retrieves the current device time

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
format?	string	MOMENT_FORMAT_ISO8601	See getDeviceTime.format

Response

string

Formatted datetime string or the raw command output if formatting fails

Script: mobile: getPasteboard

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value
encoding?	string	'utf8'

Response

any

Script: mobile: getPermission

Gets application permission state on Simulator.

This method requires WIX applesimutils to be installed on the server host.

Throws

If permission getting fails or the device is not a Simulator.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
bundleId	string	Bundle identifier of the target application
service	GetPermissionService	Service name

Response

"yes" | "no" | "unset" | "limited"

Either 'yes', 'no', 'unset' or 'limited'

Script: mobile: getSimulatedLocation

Retrieves simulated geolocation value. Only works since Xcode 14.3/iOS 16.4

Throws

If the device under test does not support gelolocation simulation.

Route

POST /session/:sessionId/execute

Response

GeolocationInfo

All entry values are set to null if no simulated location has been set prior to calling this API.

Script: mobile: hideKeyboard

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value
keys?	string[]	[]

Response

null

Script: mobile: installApp

Route

POST /session/:sessionId/execute

Parameters

Name	Type
app	string
strategy?	string
timeoutMs?	number

Response

null

Script: mobile: installCertificate

Installs a custom certificate onto the device. Since Xcode SDK 11.4 Apple has added a dedicated simctl subcommand to quickly handle certificates on Simulator over CLI. On real devices or simulators before Xcode 11.4 SDK Apple provides no official way to do it via the command line. In such case (and also as a fallback if CLI setup fails) this method tries to wrap the certificate into .mobileconfig format and then deploys the wrapped file to the internal HTTP server, so one can open it via mobile Safari. Then the algorithm goes through the profile installation procedure by clicking the necessary buttons using WebDriverAgent.

Route

POST /session/:sessionId/execute

Parameters

Name	Type
content	string
commonName?	string
isRoot?	string

Response

undefined | string

The content of the generated .mobileconfig file as base64-encoded string. This config might be useful for debugging purposes. If the certificate has been successfully set via CLI then nothing is returned.

Script: mobile: installXCTestBundle

Install an XCTestBundle

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
xctestApp	string	Path of the XCTest app (URL or filename with extension .app)

Response

null

Script: mobile: isAppInstalled

Route

POST /session/:sessionId/execute

Parameters

Name	Type
bundleId	string

Response

any

Script: mobile: isBiometricEnrolled

Checks whether biometric is currently enrolled or not.

Throws

If the detection fails or the device is not a Simulator.

Route

POST /session/:sessionId/execute

Response

boolean

true if biometric is enrolled.

Script: mobile: isKeyboardShown

Route

POST /session/:sessionId/execute

Response

boolean

Script: mobile: isLocked

Determine whether the device is locked

Route

POST /session/:sessionId/execute

Response

boolean

true if the device is locked, false otherwise

Script: mobile: killApp

Kill the given bundle id process via instruments service.

See

https://github.com/YueChen-C/py-ios-device/blob/51f4683c5c3c385a015858ada07a5f1c62d3cf57/ios_device/cli/base.py#L220

Route

POST /session/:sessionId/execute

Parameters

Name	Type
bundleId	string

Response

boolean

Returns true if the bundle id process was killed. Otherwise false.

Script: mobile: launchApp

Route

POST /session/:sessionId/execute

Parameters

Name	Type
bundleId	string
arguments?	string
environment?	any

Response

any

Script: mobile: listApps

List applications installed on the real device under test

Route

POST /session/:sessionId/execute

Parameters

Name	Type
applicationType?	"User" | "System"

Response

Record<string, any>[]

A list of apps, where each item is a map where keys are bundle identifiers and values are maps of platform-specific app properties.

Script: mobile: listCertificates

Lists installed certificates for real devices only if py-ios-device tool is available on the server machine.

Throws

If attempting to list certificates for simulated device or if py-ios-device is not installed

Route

POST /session/:sessionId/execute

Response

any

Returns map of certificates installed on the real device

Script: mobile: listConditionInducers

Get all ConditionInducer configuration information We will use conditionID and profileID in the mobileEnableConditionInducer

Route

POST /session/:sessionId/execute

Response

Condition[]

[{ "profiles": [ { "name": "100% packet loss", "identifier": "SlowNetwork100PctLoss", // MobileEnableConditionInducer profileID "description": "Name: 100% Loss Scenario\n Downlink Bandwidth: 0 Mbps\n Downlink Latency:0 ms\n Downlink Packet Loss Ratio: 100%\n Uplink Bandwidth: 0 Mbps\n Uplink Latency: 0 ms\n Uplink Packet Loss Ratio: 100%" } ], "profilesSorted": true, "identifier": "SlowNetworkCondition", // MobileEnableConditionInducer conditionID "isDestructive": false, "isInternal": false, "activeProfile": "", "name": "Network Link", "isActive": false }]

Script: mobile: listXCTestBundles

List XCTest bundles that are installed on device

Route

POST /session/:sessionId/execute

Response

string[]

List of XCTest bundles (e.g.: "XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance")

Script: mobile: listXCTestsInTestBundle

List XCTests in a test bundle

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
bundle	string	Bundle ID of the XCTest

Response

string[]

The list of xctests in the test bundle (e.g., ['XCTesterAppUITests.XCTesterAppUITests/testExample', 'XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance'])

Script: mobile: lock

Lock the device (and optionally unlock the device after a certain amount of time)

Default Value

0

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
seconds?	string | number	the number of seconds after which to unlock the device. Set to 0 or leave empty to require manual unlock (do not automatically unlock).

Response

null

Script: mobile: performIoHidEvent

Emulates triggering of the given low-level IO HID device event.

See this source header for possible constants

Popular constants: - kHIDPage_Consumer = 0x0C - kHIDUsage_Csmr_VolumeIncrement = 0xE9 (Volume Up) - kHIDUsage_Csmr_VolumeDecrement = 0xEA (Volume Down) - kHIDUsage_Csmr_Menu = 0x40 (Home) - kHIDUsage_Csmr_Power = 0x30 (Power) - kHIDUsage_Csmr_Snapshot = 0x65 (Power + Home)

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
page	string | number	The event page identifier
usage	string | number	The event usage identifier (usages are defined per-page)
durationSeconds	string | number	The event duration in float seconds (XCTest uses 0.005 for a single press event)

Response

any

Script: mobile: pinch

Route

POST /session/:sessionId/execute

Parameters

Name	Type
scale	number
velocity	number
elementId?	number

Response

any

Script: mobile: pressButton

Emulates press the given devive button name.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
name	string	The name of the button to be pressed.
durationSeconds?	string	The name of the button to be pressed.

Response

any

Script: mobile: pullFile

Pulls a remote file from the device.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
remotePath	string	The full path to the remote file or a specially formatted path, which points to an item inside app bundle. See the documentation for pullFromRealDevice and pullFromSimulator to get more information on acceptable values.

Response

string

The same as in pullFile

Script: mobile: pullFolder

Pulls the whole folder from the device under test.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
remotePath	string	The full path to the remote folder

Response

string

The same as pullFolder

Script: mobile: pushFile

Pushes the given data to a file on the remote device.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
remotePath	string	The full path to the remote file or a specially formatted path, which points to an item inside an app bundle.
payload	string	Base64-encoded content of the file to be pushed.

Response

null

Script: mobile: pushNotification

Simulates push notification delivery to Simulator.

Only application remote push notifications are supported. VoIP, Complication, File Provider, and other types are unsupported.

Since

Xcode SDK 11.4

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
bundleId	string	the target application‘s bundle identifier
payload	PushPayload	The push payload

Response

any

Script: mobile: queryAppState

Returns the current application state

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
bundleId	string	Options set, which must contain bundleId property

Response

AppState

The actual application state code. See https://developer.apple.com/documentation/xctest/xcuiapplicationstate?language=objc to get the list of possible values.

Script: mobile: removeApp

Route

POST /session/:sessionId/execute

Parameters

Name	Type
bundleId	string

Response

boolean

Script: mobile: resetLocationService

Reset the location service on real device. Raises not implemented error for simulator.

Throws

If the device is simulator, or 'resetLocation' raises an error.

Route

POST /session/:sessionId/execute

Response

null

Script: mobile: resetPermission

Resets the given permission for the active application under test. Works for both Simulator and real devices using Xcode SDK 11.4+

Throws

If permission reset fails on the device.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
service	number | "calendar" | "camera" | "contacts" | "health" | "homekit" | "keyboardnet" | "location" | "medialibrary" | "microphone" | "photos" | "reminders" | "systemroot" | "userdesktop" | "userdocuments" | "userdownloads" | "bluetooth"	One of the available service names. This could also be an integer protected resource identifier; see this list

Response

null

Script: mobile: resetSimulatedLocation

Resets simulated geolocation value. Only works since Xcode 14.3/iOS 16.4. ! Do not forget to reset the simulated geolocation value after your automated test is finished. ! If the value is not reset explcitly then the simulated one will remain until the next device restart.

Throws

If the device under test does not support gelolocation simulation.

Route

POST /session/:sessionId/execute

Response

any

Script: mobile: rotateElement

Route

POST /session/:sessionId/execute

Parameters

Name	Type
elementId	string | Element<string>
rotation	number
velocity	number

Response

any

Script: mobile: runXCTest

Run an XCTest.

Launches a subprocess that runs the XC Test and blocks until it is complete. Parses the stdout of the process and returns result as an array.

See the idb docs for reference.

Throws

Error thrown if subprocess returns non-zero exit code

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
testRunnerBundleId	string	undefined	Test app bundle (e.g.: io.appium.XCTesterAppUITests.xctrunner)
appUnderTestBundleId	string	undefined	App-under-test bundle
xctestBundleId	string	undefined	XCTest bundle ID
args?	string	undefined	Test app bundle (e.g.: io.appium.XCTesterAppUITests.xctrunner)
testType?	string	undefined	App-under-test bundle
env?	string	undefined	XCTest bundle ID
timeout?	string[]	[]	Launch arguments to start the test with (see reference documentation)

Response

RunXCUITestResponse

Script: mobile: scroll

Route

POST /session/:sessionId/execute

Parameters

Name	Type
name?	string
direction?	Direction
predicateString?	string
toVisible?	boolean
distance?	number
elementId?	string | Element<string>

Response

any

Script: mobile: scrollToElement

See https://github.com/facebook/WebDriverAgent/blob/master/WebDriverAgentLib/Commands/FBElementCommands.m to get the info about available WDA gestures API

See https://developer.apple.com/reference/xctest/xcuielement and https://developer.apple.com/reference/xctest/xcuicoordinate to get the detailed description of all XCTest gestures

Route

POST /session/:sessionId/execute

Parameters

Name	Type
elementId	string | Element<string>

Response

any

Script: mobile: selectPickerWheelValue

Performs selection of the next or previous picker wheel value. This might be useful if these values are populated dynamically (so you don't know which one to select) or if value selection using the sendKeys API does not work due to an XCTest bug. The method throws an exception if it fails to change the current picker value.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
elementId	string | Element<string>	The element id for the picker wheel
order	"next" | "previous"	The order in which to select the value. Either next or previous
offset?	string | Element<string>	The element id for the picker wheel

Response

any

Script: mobile: sendBiometricMatch

Emulates biometric match/non-match event on Simulator. The biometric feature is expected to be already enrolled before executing this.

Throws

If matching fails or the device is not a Simulator.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
type?	string	'touchId'	The biometric feature name.
match?	boolean	true	If true, simulate biometic match. If false, simulate biometric non-match..

Response

null

Script: mobile: setAppearance

Set the device's UI appearance style

Since

iOS 12.0

Throws

if the current platform does not support UI appearance changes

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
style	"dark" | "light"	The appearance style to set

Response

null

Script: mobile: setPasteboard

Route

POST /session/:sessionId/execute

Parameters

Name	Type
content	string
encoding?	string

Response

any

Script: mobile: setPermission

Set application permission state on Simulator.

Since

Xcode SDK 11.4

Throws

If permission setting fails or the device is not a Simulator.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
access	Record<Partial<AccessRule>, PermissionState>	One or more access rules to set.
bundleId	string	Bundle identifier of the target application

Response

null

Script: mobile: setSimulatedLocation

Sets simulated geolocation value. Only works since Xcode 14.3/iOS 16.4

Throws

If the device under test does not support gelolocation simulation.

Route

POST /session/:sessionId/execute

Parameters

Name	Type
latitude	GeolocationInfo

Response

any

Script: mobile: shake

Shake the device

Route

POST /session/:sessionId/execute

Response

null

Script: mobile: siriCommand

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
text	string	Text to be sent to Siri

Response

any

Script: mobile: source

Route

POST /session/:sessionId/execute

Parameters

Name	Type
format?	"xml" | "json"
excludedAttributes?	any

Response

any

Script: mobile: startAudioRecording

Records the given hardware audio input and saves it into an .mp4 file.

To use this command, the audio_record security feature must be enabled and FFMpeg must be installed on the Appium server.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
audioInput	string | number	undefined	The name of the corresponding audio input device to use for the capture. The full list of capture devices could be shown by executing ffmpeg -f avfoundation -list_devices true -i ""
timeLimit?	string | number	undefined	The name of the corresponding audio input device to use for the capture. The full list of capture devices could be shown by executing ffmpeg -f avfoundation -list_devices true -i ""
audioCodec?	string | number	180	The maximum recording time, in seconds.
audioBitrate?	string	'aac'	The name of the audio codec.
audioChannels?	string	'128k'	The bitrate of the resulting audio stream.
audioRate?	string | number	2	The count of audio channels in the resulting stream. Setting it to 1 will create a single channel (mono) audio stream.
forceRestart?	string | number	44100	The sampling rate of the resulting audio stream (in Hz).

Response

null

Script: mobile: startLogsBroadcast

Starts iOS system logs broadcast websocket on the same host and port where Appium server is running at /ws/session/:sessionId:/appium/syslog endpoint. The method will return immediately if the web socket is already listening.

Each connected webcoket listener will receive syslog lines as soon as they are visible to Appium.

Route

POST /session/:sessionId/execute

Response

null

Script: mobile: startPcap

Records the given network traffic capture into a .pcap file.

Throws

If network traffic capture has failed to start.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
timeLimitSec?	number	180	The maximum recording time, in seconds. The maximum value is 43200 (12 hours).
forceRestart?	boolean	false	Whether to restart traffic capture process forcefully when startPcap is called (true) or ignore the call until the current traffic capture is completed (false, the default value).

Response

null

Script: mobile: startPerfRecord

Starts performance profiling for the device under test.

Relaxing security is mandatory for simulators. It can always work for real devices.

Since XCode 14 the method tries to use xctrace tool to record performance stats.

The instruments developer utility is used as a fallback for this purpose if xctrace is not available.

It is possible to record multiple profiles at the same time.

Read Recording, Pausing, and Stopping Traces for more details.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
timeout?	number	DEFAULT_TIMEOUT_MS	The maximum count of milliseconds to record the profiling information.
profileName?	string	DEFAULT_PROFILE_NAME	The name of existing performance profile to apply. Can also contain the full path to the chosen template on the server file system. Note: not all profiles are supported on mobile devices.
pid?	number | "current"	undefined	The ID of the process to measure the performance for. Set it to current in order to measure the performance of the process, which belongs to the currently active application. All processes running on the device are measured if pid is unset (the default setting).

Response

null

Script: mobile: stopAudioRecording

Stop recording of the audio input. If no audio recording process is running then the endpoint will try to get the recently recorded file. If no previously recorded file is found and no active audio recording processes are running then the method returns an empty string.

Throws

If there was an error while getting the recorded file.

Route

POST /session/:sessionId/execute

Response

string

Base64-encoded content of the recorded media file or an empty string if no audio recording has been started before.

Script: mobile: stopLogsBroadcast

Stops the previously started syslog broadcasting wesocket server. This method will return immediately if no server is running.

Route

POST /session/:sessionId/execute

Response

null

Script: mobile: stopPcap

Stop capture of the device network traffic. If no traffic capture process is running then the endpoint will try to get the recently recorded file. If no previously recorded file is found and no active traffic capture processes are running then the method returns an empty string.

Throws

If there was an error while getting the capture file.

Route

POST /session/:sessionId/execute

Response

string

Base64-encoded content of the recorded pcap file or an empty string if no traffic capture has been started before.

Script: mobile: stopPerfRecord

Stops performance profiling for the device under test.

The resulting file in .trace format can be either returned directly as base64-encoded zip archive or uploaded to a remote location (such files can be pretty large). Afterwards it is possible to unarchive and open such files with Xcode Dev Tools.

Throws

If no performance recording with given profile name/device udid combination has been started before or the resulting .trace file has not been generated properly.

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Default value	Description
remotePath?	string	undefined	The path to the remote location, where the resulting zipped .trace file should be uploaded. The following protocols are supported: http, https, ftp. Null or empty string value (the default setting) means the content of resulting file should be zipped, encoded as Base64 and passed as the endpoint response value. An exception will be thrown if the generated file is too big to fit into the available process memory.
user?	string	undefined	The name of the user for the remote authentication. Only works if remotePath is provided.
pass?	string	undefined	The password for the remote authentication. Only works if remotePath is provided.
method?	Method	undefined	The http multipart upload method name. Only works if remotePath is provided. Defaults to PUT
profileName?	string	DEFAULT_PROFILE_NAME	The name of an existing performance profile for which the recording has been made.
headers?	Record<string, any>	undefined	Additional headers mapping for multipart http(s) uploads
fileFieldName?	string	undefined	The name of the form field, where the file content BLOB should be stored for http(s) uploads. Defaults to file
formFields?	[string, any][] | Record<string, any>	undefined	Additional form fields for multipart http(s) uploads

Response

string

Either an empty string if the upload was successful or base-64 encoded content of zipped .trace file.

Script: mobile: swipe

Route

POST /session/:sessionId/execute

Parameters

Name	Type
direction	Direction
velocity?	Direction
elementId?	number

Response

any

Script: mobile: tap

Route

POST /session/:sessionId/execute

Parameters

Name	Type
x	number
y	number
elementId?	number

Response

any

Script: mobile: tapWithNumberOfTaps

Route

POST /session/:sessionId/execute

Parameters

Name	Type
numberOfTouches	string | Element<string>
numberOfTaps	number
elementId?	string | Element<string>

Response

any

Script: mobile: terminateApp

Route

POST /session/:sessionId/execute

Parameters

Name	Type
bundleId	string

Response

any

Script: mobile: touchAndHold

Route

POST /session/:sessionId/execute

Parameters

Name	Type
duration	number
x?	number
y?	number
elementId?	number

Response

any

Script: mobile: twoFingerTap

Route

POST /session/:sessionId/execute

Parameters

Name	Type
elementId?	string | Element<string>

Response

any

Script: mobile: unlock

Unlock the device

Route

POST /session/:sessionId/execute

Response

null

Script: mobile: updateSafariPreferences

Updates preferences of Mobile Safari on Simulator

*

Route

POST /session/:sessionId/execute

Parameters

Name	Type	Description
preferences	any	An object containing Safari settings to be * updated. The list of available setting names and their values could be * retrieved by changing the corresponding Safari settings in the UI and then * inspecting Library/Preferences/com.apple.mobilesafari.plist file inside * of com.apple.mobilesafari app container. The full path to the Mobile * Safari's container could be retrieved from xcrun simctl get_app_container <sim_udid> com.apple.mobilesafari data command output. Use the xcrun simctl spawn <sim_udid> defaults read <path_to_plist> command to print the * plist content to the Terminal. *

Response

null

Script: mobile: viewportRect

Route

POST /session/:sessionId/execute

Response

Object

Script: mobile: viewportScreenshot

Route

POST /session/:sessionId/execute

Response

any