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(netspeed)
Parametersβ
Name | Type | Details |
---|---|---|
netspeed | string | Network type - 'full','gsm', 'edge', 'hscsd', 'gprs', 'umts', 'hsdpa', 'lte', 'evdo' |
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β
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β
// 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: {},
},
]);
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 actualmode
andoptions
values. See the documentation onappium-support
module for more details.