Appium

shake

Perform a shake action on the device.

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

Usage

driver.shake()

Support

---

lock

Lock the device.

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

Usage

driver.lock(seconds)

Parameters

Name	Type	Details
seconds optional	number	how long to lock the screen (iOS only)

Support

---

unlock

Unlock the device.

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

Usage

driver.unlock()

Support

---

isLocked

Check whether the device is locked or not.

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

Usage

driver.isLocked()

Returns

• <boolean> isLocked: True if the device is locked, false if not

Support

---

startRecordingScreen

Start recording the screen.

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

Usage

driver.startRecordingScreen(options)

Parameters

Name	Type	Details
options optional	object	command parameters that can contain keys like: remotePath, username, password, method, forceRestart, timeLimit, videoType, videoQuality, videoFps, bitRate, videoSize, bugReport (see more description in Appium docs)

Support

---

stopRecordingScreen

Stop recording screen

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

Usage

driver.stopRecordingScreen(remotePath, username, password, method)

Parameters

Name	Type	Details
remotePath optional	string	The path to the remote location, where the resulting video should be uploaded. The following protocols are supported http/https, ftp. This option only has an effect if there is screen recording process in progreess and forceRestart parameter is not set to true. Null or empty string value (the default setting) means the content of resulting file should be encoded as Base64.
username optional	string	The name of the user for the remote authentication.
password optional	string	The password for the remote authentication.
method optional	string	The http multipart upload method name. The 'PUT' one is used by default.

Returns

• <string> response: Base64 encoded string. If remote_path is set, the response is empty string

Support

---

getPerformanceDataTypes

Returns the information types of the system state which is supported to read as like cpu, memory, network traffic, and battery.

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

Usage

driver.getPerformanceDataTypes()

Returns

• <string[]> performanceTypes: The available performance data types (cpuinfo|batteryinfo|networkinfo|memoryinfo)

Support

---

getPerformanceData

Returns the information of the system state which is supported to read as like cpu, memory, network traffic, and battery.

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

Usage

driver.getPerformanceData(packageName, dataType, dataReadTimeout)

Parameters

Name	Type	Details
packageName	string	the package name of the application
dataType	string	the type of system state which wants to read. It should be one of the supported performance data types
dataReadTimeout optional	number	the number of attempts to read

Returns

• <string[]> performanceData: The information type of the system state which is supported to read as like cpu, memory, network traffic, and battery

Support

---

pressKeyCode

Press a particular key on the device.

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

Usage

driver.pressKeyCode(keycode, metastate, flags)

Parameters

Name	Type	Details
keycode	number	keycode to press
metastate optional	number	meta state to press the keycode with
flags optional	number	flags for the keypress

Support

---

longPressKeyCode

Press and hold a particular key code on the device.

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

Usage

driver.longPressKeyCode(keycode, metastate, flags)

Parameters

Name	Type	Details
keycode	number	keycode to press on the device
metastate optional	number	metastate for the keypress
flags optional	number	flags for the keypress

Support

---

sendKeyEvent

Send a key code to the device.

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

Usage

driver.sendKeyEvent(keycode, metastate)

Parameters

Name	Type	Details
keycode	string	keycode to press
metastate optional	string	meta state to press the keycode with

---

rotateDevice

Rotate the device in three dimensions.

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

Usage

driver.rotateDevice(x, y, radius, rotation, touchCount, duration, element)

Parameters

Name	Type	Details
x	number	x offset to use for the center of the rotate gesture
y	number	y offset to use for the center of the rotate gesture
radius	number	the distance in points from the center to the edge of the circular path
rotation	number	the length of rotation in radians
touchCount	number	the number of touches to use in the specified gesture
duration	number	the length of hold time for the specified gesture, in seconds
element optional	string	the id of an element returned in a previous call to execute the rotation on

Support

---

getCurrentActivity

Get the name of the current Android activity.

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

Usage

driver.getCurrentActivity()

Returns

• <string> activity: Name of the current activity

Support

---

getCurrentPackage

Get the name of the current Android package.

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

Usage

driver.getCurrentPackage()

Returns

• <string> package: Name of the current package

Support

---

installApp

Install the given app onto the device.

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

Usage

driver.installApp(appPath)

Parameters

Name	Type	Details
appPath	string	path to application .apk file

Support

---

activateApp

Activate the given app onto the device

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

Usage

driver.activateApp(appId)

Parameters

Name	Type	Details
appId	string	App ID (package ID for Android, bundle ID for iOS)

Support

---

removeApp

Remove an app from the device.

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

Usage

driver.removeApp(appId)

Parameters

Name	Type	Details
appId	string	App ID (package ID for Android, bundle ID for iOS)

Support

---

terminateApp

Terminate the given app on the device

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

Usage

driver.terminateApp(appId)

Parameters

Name	Type	Details
appId	string	App ID (package ID for Android, bundle ID for iOS)

Support

---

isAppInstalled

Check whether the specified app is installed on the device.

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

Usage

driver.isAppInstalled(appId)

Parameters

Name	Type	Details
appId	string	App ID (package ID for Android, bundle ID for iOS)

Returns

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

Support

---

queryAppState

Get the given app status on the device

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

Usage

driver.queryAppState(appId)

Parameters

Name	Type	Details
appId	string	App ID (package ID for Android, bundle ID for iOS)

Returns

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

Support

---

hideKeyboard

Hide soft keyboard.

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

Usage

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

Parameters

Name	Type	Details
strategy optional	string	hide keyboard strategy (UIAutomation only), available strategies - 'press', 'pressKey', 'swipeDown', 'tapOut', 'tapOutside', 'default'
key optional	string	key value if strategy is 'pressKey'
keyCode optional	string	key code if strategy is 'pressKey'
keyName optional	string	key name if strategy is 'pressKey'

Support

---

isKeyboardShown

Whether or not the soft keyboard is shown.

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

Usage

driver.isKeyboardShown()

Returns

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

Support

---

pushFile

Place a file onto the device in a particular place.

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

Usage

driver.pushFile(path, data)

Parameters

Name	Type	Details
path	string	path to install the data to
data	string	contents of file in base64

Support

---

pullFile

Retrieve a file from the device's file system.

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

Usage

driver.pullFile(path)

Parameters

Name	Type	Details
path	string	path on the device to pull file from

Returns

• <string> response: Contents of file in base64

Support

---

pullFolder

Retrieve a folder from the device's file system.

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

Usage

driver.pullFolder(path)

Parameters

Name	Type	Details
path	string	path to an entire folder on the device

Support

---

toggleAirplaneMode

Toggle airplane mode on device.

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

Usage

driver.toggleAirplaneMode()

Support

---

toggleData

Switch the state of data service.

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

Usage

driver.toggleData()

Support

---

toggleWiFi

Switch the state of the wifi service.

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

Usage

driver.toggleWiFi()

Support

---

toggleLocationServices

Switch the state of the location service.

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

Usage

driver.toggleLocationServices()

Support

---

toggleNetworkSpeed

Set network speed (Emulator only)

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

Usage

driver.toggleNetworkSpeed()

Support

---

openNotifications

Open Android notifications (Emulator only).

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

Usage

driver.openNotifications()

Support

---

startActivity

Start an Android activity by providing package name and activity name.

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

Usage

driver.startActivity(appPackage, appActivity, appWaitPackage, appWaitActivity, intentAction, intentCategory, intentFlags, optionalIntentArguments, dontStopAppOnReset)

Parameters

Name	Type	Details
appPackage	string	name of app
appActivity	string	name of activity
appWaitPackage optional	string	name of app to wait for
appWaitActivity optional	string	name of activity to wait for
intentAction optional	string	intent action which will be used to start activity
intentCategory optional	string	intent category which will be used to start activity
intentFlags optional	string	flags that will be used to start activity
optionalIntentArguments optional	string	additional intent arguments that will be used to start activity
dontStopAppOnReset optional	string	doesn’t stop the process of the app under test, before starting the app using adb

Support

---

getSystemBars

Retrieve visibility and bounds information of the status and navigation bars.

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

Usage

driver.getSystemBars()

Returns

• <object[]> systemBars: Information about visibility and bounds of status and navigation bar

Support

---

getDeviceTime

Get the time on the device.

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

Usage

driver.getDeviceTime()

Returns

• <string> time: Time on the device

Support

---

getDisplayDensity

Get display density from device.

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

Usage

driver.getDisplayDensity()

Returns

• <*> displayDensity:

Support

---

touchId

Simulate a touch id event (iOS Simulator only). To enable this feature, the allowTouchIdEnroll desired capability must be set to true and the Simulator must be enrolled. When you set allowTouchIdEnroll to true, it will set the Simulator to be enrolled by default. The enrollment state can be toggled. This call will only work if Appium process or its parent application (e.g. Terminal.app or Appium.app) has access to Mac OS accessibility in System Preferences > Security & Privacy > Privacy > Accessibility list.

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

Usage

driver.touchId(match)

Parameters

Name	Type	Details
match	boolean	are we simulating a successful touch (true) or a failed touch (false)

Support

---

toggleEnrollTouchId

Toggle the simulator being enrolled to accept touchId (iOS Simulator only). To enable this feature, the allowTouchIdEnroll desired capability must be set to true. When allowTouchIdEnroll is set to true the Simulator will be enrolled by default, and the 'Toggle Touch ID Enrollment' changes the enrollment state. This call will only work if the Appium process or its parent application (e.g., Terminal.app or Appium.app) has access to Mac OS accessibility in System Preferences > Security & Privacy > Privacy > Accessibility list.

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

Usage

driver.toggleEnrollTouchId(enabled)

Parameters

Name	Type	Details
enabled optional	boolean	equals to true if TouchID enrollment should be enabled

Support

---

launchApp

Launch an app on device. iOS tests with XCUITest can also use the mobile: launchApp method. See detailed documentation.

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

Usage

driver.launchApp()

Support

---

closeApp

Close an app on device.

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

Usage

driver.closeApp()

Support

---

reset

Deprecated use 'resetApp' instead. This command will be removed with the upcoming major version release.

Appium command. More details can be found in the [official protocol docs](http://appium.io/docs/en/commands/device/app/reset-app/).

Usage

driver.reset()

Support

---

resetApp

Reset the currently running app for this session.

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

Usage

driver.resetApp()

Support

---

background

Send the currently running app for this session to the background. iOS tests with XCUITest can also use the mobile: terminateApp method to terminate the current app (see detailed documentation), and the mobile: activateApp to activate an existing application on the device under test and moves it to the foreground (see detailed documentation).

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

Usage

driver.background(seconds)

Parameters

Name	Type	Details
seconds	number, null	timeout to restore app, if 'null' app won't be restored

Support

---

endCoverage

Get test coverage data.

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

Usage

driver.endCoverage(intent, path)

Parameters

Name	Type	Details
intent	string	intent to broadcast
path	string	path to .ec file

Support

---

getStrings

Get app strings.

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

Usage

driver.getStrings(language, stringFile)

Parameters

Name	Type	Details
language optional	string	language code
stringFile optional	string	path to the string file

Returns

• <object> appStrings: all defined Strings from an app for the specified language and strings filename

Support

---

setValueImmediate

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

Usage

driver.setValueImmediate(elementId, value)

Parameters

Name	Type	Details
elementId	String	the id of an element returned in a previous call to Find Element(s)
value	string	value to set on element

Support

---

replaceValue

Replace the value to element directly.

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

Usage

driver.replaceValue(elementId, value)

Parameters

Name	Type	Details
elementId	String	the id of an element returned in a previous call to Find Element(s)
value	string	value to replace on element

Support

---

getSettings

Retrieve the current settings on the device.

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

Usage

driver.getSettings()

Returns

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

Support

---

updateSettings

Update the current setting on the device.

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

Usage

driver.updateSettings(settings)

Parameters

Name	Type	Details
settings	object	key/value object with settings to update

Support

---

receiveAsyncResponse

Callback url for asynchronous execution of JavaScript.

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

Usage

driver.receiveAsyncResponse(response)

Parameters

Name	Type	Details
response	object	response to receive on device

---

gsmCall

Make GSM call (Emulator only).

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

Usage

driver.gsmCall(phoneNumber, action)

Parameters

Name	Type	Details
phoneNumber	string	the phone number to call to
action	string	The action - 'call', 'accept', 'cancel', 'hold'

Support

---

gsmSignal

Set GSM signal strength (Emulator only).

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

Usage

driver.gsmSignal(signalStrength, signalStrengh)

Parameters

Name	Type	Details
signalStrength	string	signal strength in the range [0, 4]
signalStrengh optional	string	signal strength in the range [0, 4]. Please also set this parameter with the same value if you use Appium v1.11.0 or lower (see https://github.com/appium/appium/issues/12234).

Support

---

powerCapacity

Set the battery percentage (Emulator only).

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

Usage

driver.powerCapacity(percent)

Parameters

Name	Type	Details
percent	number	percentage value in range [0, 100]

Support

---

powerAC

Set the state of the battery charger to connected or not (Emulator only).

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

Usage

driver.powerAC(state)

Parameters

Name	Type	Details
state	string	set the state. on or off

Support

---

gsmVoice

Set GSM voice state (Emulator only).

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

Usage

driver.gsmVoice(state)

Parameters

Name	Type	Details
state	string	state of GSM voice - 'unregistered', 'home', 'roaming', 'searching', 'denied', 'off', 'on'

Support

---

sendSms

Simulate an SMS message (Emulator only).

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

Usage

driver.sendSms(phoneNumber, message)

Parameters

Name	Type	Details
phoneNumber	string	the phone number to send the SMS too
message	string	the SMS message

Support

---

fingerPrint

Authenticate users by using their finger print scans on supported emulators.

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

Usage

driver.fingerPrint(fingerprintId)

Parameters

Name	Type	Details
fingerprintId	number	finger prints stored in Android Keystore system (from 1 to 10)

Support

---

setClipboard

Set the content of the system clipboard

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

Usage

driver.setClipboard(content, contentType, label)

Parameters

Name	Type	Details
content	string	The actual base64 encoded clipboard content
contentType optional	string	The type of the content to get. Plaintext, Image, URL. Android supports only plaintext
label optional	string	Clipboard data label for Android

Returns

• <string> response: Response from Appium server

---

getClipboard

Get the content of the system clipboard

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

Usage

driver.getClipboard(contentType)

Parameters

Name	Type	Details
contentType optional	string	The type of the content to get. Plaintext, Image, URL. Android supports only plaintext

Returns

• <string> response: Clipboard content as base64-encoded string or an empty string if the clipboard is empty

---

touchPerform

This functionality is only available from within a native context. 'Touch Perform' works similarly to the other singular touch interactions, except that this allows you to chain together more than one touch action as one command. This is useful because Appium commands are sent over the network and there's latency between commands. This latency can make certain touch interactions impossible because some interactions need to be performed in one sequence. Vertical, for example, requires pressing down, moving to a different y coordinate, and then releasing. For it to work, there can't be a delay between the interactions.

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

Usage

driver.touchPerform(actions)

Parameters

Name	Type	Details
actions	object[]	The type of action to perform (e.g. moveTo, release, press, tap, wait)

Example

Asynchronous Mode

// do a horizontal swipe by percentage
const startPercentage = 10;
const endPercentage = 90;
const anchorPercentage = 50;

const { width, height } = driver.getWindowSize();
const anchor = height * anchorPercentage / 100;
const startPoint = width * startPercentage / 100;
const endPoint = width * endPercentage / 100;
driver.touchPerform([
  {
    action: 'press',
    options: {
      x: startPoint,
      y: anchor,
    },
  },
  {
    action: 'wait',
    options: {
      ms: 100,
    },
  },
  {
    action: 'moveTo',
    options: {
      x: endPoint,
      y: anchor,
    },
  },
  {
    action: 'release',
    options: {},
  },
]);

Synchronous Mode

// do a horizontal swipe by percentage
const startPercentage = 10;
const endPercentage = 90;
const anchorPercentage = 50;

const { width, height } = driver.getWindowSize();
const anchor = height * anchorPercentage / 100;
const startPoint = width * startPercentage / 100;
const endPoint = width * endPercentage / 100;
driver.touchPerform([
  {
    action: 'press',
    options: {
      x: startPoint,
      y: anchor,
    },
  },
  {
    action: 'wait',
    options: {
      ms: 100,
    },
  },
  {
    action: 'moveTo',
    options: {
      x: endPoint,
      y: anchor,
    },
  },
  {
    action: 'release',
    options: {},
  },
]);

caution

Synchronous Mode will depcrecated with Node.js v16. With an update to the
underlying Chromium version it became technically impossible to provide the
same synchronous behavior. We recommend to start transition to asynchronous
command execution. For more information, see our <a href="https://github.com/webdriverio/webdriverio/discussions/6702">RFC</a>.

Support

---

multiTouchPerform

This functionality is only available from within a native context. Perform a multi touch action sequence.

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

Usage

driver.multiTouchPerform(actions)

Parameters

Name	Type	Details
actions	object[]	The type of action to perform (e.g. moveTo, release, press, tap, wait)

Support

---

driverScript

This command allows you to define a webdriverio script in a string and send it to the Appium server to be executed locally to the server itself, thus reducing latency that might otherwise occur along with each command.

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

Usage

driver.driverScript(script, type, timeout)

Parameters

Name	Type	Details
script	string	The script to execute. It has access to a 'driver' object which represents a webdriverio session attached to the current server.
type optional	string	The language/framework used in the script. Currently, only 'webdriverio' is supported and is the default.
timeout optional	number	The 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 stored in appium server.

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

Usage

driver.getEvents(type)

Parameters

Name	Type	Details
type	string[]	Get events which are filtered with the type if the type is provided.

Returns

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

---

logEvent

Store a custom event.

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

Usage

driver.logEvent(vendor, event)

Parameters

Name	Type	Details
vendor	string	The name of vendor. It will be vendor in vendor:event.
event	string	The name of event. It will be event in vendor:event.

---

compareImages

Performs images comparison using OpenCV framework features. It is expected that both OpenCV framework and opencv4nodejs module are installed on the machine where Appium server is running.

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

Usage

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

Parameters

Name	Type	Details
mode	string	One of possible comparison modes: 'matchFeatures', 'getSimilarity', 'matchTemplate'. 'matchFeatures' is by default.
firstImage	string	An image data. All image formats, that OpenCV library itself accepts, are supported.
secondImage	string	An image data. All image formats, that OpenCV library itself accepts, are supported.
options	object	The content of this dictionary depends on the actual mode value. See the documentation on appium-support module for more details.

Returns

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