Skip to main content

Appium

getLogTypes​

Get available log types.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getLogTypes()

Returns​

  • <String[]> logTypes: The list of available log types, example: browser, driver.

getLogs​

Get the log for a given log type. Log buffer is reset after each request.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getLogs(type)

Parameters​

NameTypeDetails
typestringthe log type

Returns​

  • <Object[]> logs: The list of log entries.

getSession​

Retrieve the capabilities of the current session.

Appium command. More details can be found in the official protocol docs.

caution

This protocol command is deprecated
Use getAppiumSessionCapabilities instead

Usage​

await driver.getSession()

Returns​

  • <Object> capabilities: An object describing the session's capabilities.

getAppiumContext​

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getAppiumContext()

Returns​

  • <Context> context: a string representing the current context or null representing 'no context'

switchAppiumContext​

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.switchAppiumContext(name)

Parameters​

NameTypeDetails
namestringa string representing an available context

getAppiumContexts​

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getAppiumContexts()

Returns​

  • <Context[]> contexts: an array of strings representing available contexts, e.g. 'WEBVIEW', or 'NATIVE'

getAppiumCommands​

Retrieve the endpoints and BiDi commands supported in the current session.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getAppiumCommands()

Returns​

  • <Object> commands: Supported endpoints and BiDi commands, each grouped into common, driver-specific, and plugin-specific endpoints/commands.

getAppiumExtensions​

Retrieve the extension commands supported in the current session.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getAppiumExtensions()

Returns​

  • <Object> commands: Supported extension commands, grouped into driver-specific and plugin-specific commands.

getAppiumSessionCapabilities​

Retrieve the capabilities of the current session.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getAppiumSessionCapabilities()

Returns​

  • <Object> capabilities: An object describing the session's capabilities.

startRecordingScreen​

Start recording the screen.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.startRecordingScreen(options)

Parameters​

NameTypeDetails
options
optional		objectAppium driver-specific recording options (refer to driver docs)

Returns​

  • <string> response: Empty string, or the base64 encoded string of a previous screen recording, if forceRestart and remotePath are not set

Support​

Support for XCUITest (9.3+) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

stopRecordingScreen​

Stop recording the screen.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.stopRecordingScreen(options)

Parameters​

NameTypeDetails
options
optional		objectAppium driver-specific recording options (refer to driver docs)

Returns​

  • <string> response: Base64 encoded string of the screen recording, or an empty string if the remotePath option is set

Support​

Support for XCUITest (9.3+) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

rotateDevice​

Rotate the device in three dimensions.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.rotateDevice(x, y, z)

Parameters​

NameTypeDetails
xnumberx offset to use for the center of the rotate gesture
ynumbery offset to use for the center of the rotate gesture
znumberz offset to use for the center of the rotate gesture

Support​

Support for UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+)

  • iOS: UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)

installApp​

Install the given app onto the device.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.installApp(appPath, options)

Parameters​

NameTypeDetails
appPathstringPath to application .apk file
options
optional		objectDriver-specific installation options

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)

activateApp​

Activate the given app on the device

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.activateApp(appId, bundleId, options)

Parameters​

NameTypeDetails
appId
optional		stringApp package ID (required for Android)
bundleId
optional		stringBundle ID (required for iOS)
options
optional		objectDriver-specific launch options

Support​

Support for XCUITest (9.3+) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+)
  • Android: UiAutomator (4.2+)

removeApp​

Remove an app from the device.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.removeApp(appId, bundleId, options)

Parameters​

NameTypeDetails
appId
optional		stringApp package ID (required for Android)
bundleId
optional		stringBundle ID (required for iOS)
options
optional		objectDriver-specific uninstall options

Returns​

  • <boolean> didRemovalSucceed: Return true if uninstall was successful, false if not

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)

terminateApp​

Terminate the given app on the device

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.terminateApp(appId, bundleId, options)

Parameters​

NameTypeDetails
appId
optional		stringApp package ID (required for Android)
bundleId
optional		stringBundle ID (required for iOS)
options
optional		objectDriver-specific termination options

Support​

Support for XCUITest (9.3+) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+)
  • Android: UiAutomator (4.2+)

isAppInstalled​

Check whether the specified app is installed on the device.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.isAppInstalled(appId, bundleId)

Parameters​

NameTypeDetails
appId
optional		stringApp package ID (required for Android)
bundleId
optional		stringBundle ID (required for iOS)

Returns​

  • <boolean> isAppInstalled: Return true if installed, false if not

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)

queryAppState​

Get the given app status on the device

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.queryAppState(appId, bundleId)

Parameters​

NameTypeDetails
appId
optional		stringApp package ID (required for Android)
bundleId
optional		stringBundle ID (required for iOS)

Returns​

  • <number> appStatus: 0 is not installed. 1 is not running. 2 is running in background suspended. 3 is running in background. 4 is running in foreground

Support​

Support for XCUITest (9.3+) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+)
  • Android: UiAutomator (4.2+)

hideKeyboard​

Hide soft keyboard.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.hideKeyboard(strategy, key, keyCode, keyName)

Parameters​

NameTypeDetails
strategy
optional		stringhide keyboard strategy (UIAutomation only), available strategies - 'press', 'pressKey', 'swipeDown', 'tapOut', 'tapOutside', 'default'
key
optional		stringkey value if strategy is 'pressKey'
keyCode
optional		stringkey code if strategy is 'pressKey'
keyName
optional		stringkey name if strategy is 'pressKey'

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

isKeyboardShown​

Whether or not the soft keyboard is shown.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.isKeyboardShown()

Returns​

  • <boolean> isKeyboardShown: True if the keyboard is shown

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

pushFile​

Place a file onto the device in a particular place.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.pushFile(path, data)

Parameters​

NameTypeDetails
pathstringpath to install the data to
datastringcontents of file in base64

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

pullFile​

Retrieve a file from the device's file system.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.pullFile(path)

Parameters​

NameTypeDetails
pathstringpath on the device to pull file from

Returns​

  • <string> response: Contents of file in base64

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

pullFolder​

Retrieve a folder from the device's file system.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.pullFolder(path)

Parameters​

NameTypeDetails
pathstringpath to an entire folder on the device

Returns​

  • <string> response: Zip file of the folder contents in base64

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

getDeviceTime​

Get the time on the device.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getDeviceTime()

Returns​

  • <string> time: Time on the device

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)

getSettings​

Retrieve the current session settings.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getSettings()

Returns​

  • <object> settings: JSON hash of all the currently specified settings, see Settings API

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

updateSettings​

Update the session settings.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.updateSettings(settings)

Parameters​

NameTypeDetails
settingsobjectkey/value object with settings to update

Support​

Support for XCUITest (9.3+), UIAutomation (8.0 to 9.3) Support for UiAutomator (4.2+) Support for Windows (10+)

  • iOS: XCUITest (9.3+), UIAutomation (8.0 to 9.3)
  • Android: UiAutomator (4.2+)
  • Windows: Windows (10+)

executeDriverScript​

Execute a script in a child process. This approach helps minimize potential latency associated with each command. Using this command in Appium 2 or later requires installing the execute-driver plugin.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.executeDriverScript(script, type, timeout)

Parameters​

NameTypeDetails
scriptstringThe script to execute. It has access to a 'driver' object which represents a WebdriverIO session attached to the current server.
type
optional		stringThe language/framework used in the script. Currently, only 'webdriverio' is supported and is the default.
timeout
optional		numberThe number of milliseconds the script should be allowed to run before being killed by the Appium server. Defaults to the equivalent of 1 hour.

Returns​

  • <object> result: An object containing two fields: 'result', which is the return value of the script itself, and 'logs', which contains 3 inner fields, 'log', 'warn', and 'error', which hold an array of strings logged by console.log, console.warn, and console.error in the script's execution.

getEvents​

Get events logged in the current session.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getEvents(type)

Parameters​

NameTypeDetails
type
optional		string, string[]One or more event types to filter the returned events

Returns​

  • <object> result: A JSON hash of events like {'commands' => [{'cmd' => 123455, ....}], 'startTime' => 1572954894127, }.

Support​

Support for UiAutomator (4.2+) Support for XCUITest (9.3+)

  • Android: UiAutomator (4.2+)
  • iOS: XCUITest (9.3+)

logEvent​

Log a custom event.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.logEvent(vendor, event)

Parameters​

NameTypeDetails
vendorstringName of the namespace (vendor) used to prefix the event
eventstringName of the event

Support​

Support for UiAutomator (4.2+) Support for XCUITest (9.3+)

  • Android: UiAutomator (4.2+)
  • iOS: XCUITest (9.3+)

compareImages​

Compare two images using the specified mode of comparison. Using this command in Appium 2 or later requires installing the images plugin.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.compareImages(mode, firstImage, secondImage, options)

Parameters​

NameTypeDetails
modestringOne of possible comparison modes: 'matchFeatures', 'getSimilarity', 'matchTemplate'.
firstImagestringBase64-encoded image file.
secondImagestringBase64-encoded image file.
options=[object Object]
optional		objectThe supported values of this property depend on the mode value. See Appium documentation for more details.

Returns​

  • <object> result: The content of the resulting dictionary depends on the mode and options values. See Appium documentation for more details.

availableIMEEngines​

List all available IME engines on the device. To use an engine, it has to be present in this list.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.availableIMEEngines()

Returns​

  • <String[]> engines: A list of available engines

Support​

Support for UiAutomator (4.2+)

  • Android: UiAutomator (4.2+)

getActiveIMEEngine​

Get the name of the active IME engine. The name string is platform specific.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getActiveIMEEngine()

Returns​

  • <String> engine: The name of the active IME engine

Support​

Support for UiAutomator (4.2+)

  • Android: UiAutomator (4.2+)

isIMEActivated​

Indicates whether IME input is active at the moment

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.isIMEActivated()

Returns​

  • <Boolean> isActive: true if IME input is available and currently active, false otherwise

Support​

Support for UiAutomator (4.2+)

  • Android: UiAutomator (4.2+)

deactivateIMEEngine​

De-activates the currently-active IME engine.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.deactivateIMEEngine()

Support​

Support for UiAutomator (4.2+)

  • Android: UiAutomator (4.2+)

activateIMEEngine​

Activates an IME engine.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.activateIMEEngine(engine)

Parameters​

NameTypeDetails
enginestringname of the engine to activate

Support​

Support for UiAutomator (4.2+)

  • Android: UiAutomator (4.2+)

getOrientation​

Get the current device orientation.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getOrientation()

Returns​

  • <String> orientation: The current orientation corresponding to a value defined in ScreenOrientation: LANDSCAPE|PORTRAIT.

Support​

Support for UiAutomator (4.2+) Support for XCUITest (9.3+)

  • Android: UiAutomator (4.2+)
  • iOS: XCUITest (9.3+)

setOrientation​

Set the device orientation

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.setOrientation(orientation)

Parameters​

NameTypeDetails
orientationstringthe new browser orientation as defined in ScreenOrientation: LANDSCAPE|PORTRAIT

Support​

Support for UiAutomator (4.2+) Support for XCUITest (9.3+)

  • Android: UiAutomator (4.2+)
  • iOS: XCUITest (9.3+)

getGeoLocation​

Get the current geo location.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.getGeoLocation()

Returns​

  • <Object> location: The current geo location.

setGeoLocation​

Set the current geo location.

Appium command. More details can be found in the official protocol docs.

Usage​

await driver.setGeoLocation(location)

Parameters​

NameTypeDetails
locationobjectthe new location ({latitude: number, longitude: number, altitude: number})

Welcome! How can I help?

WebdriverIO AI Copilot