Execute Methods

Beside of standard W3C APIs the driver provides the following custom command extensions to execute platform specific scenarios:

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 value selection suing sendKeys API does not work because of an XCTest bug. The method throws an exception if it fails to change the current picker value.

Arguments

Name	Type	Required	Description	Example
elementId (element before version 1.22)	string	yes	PickerWheel's internal element id (as hexadecimal hash string) to perform value selection on. The element must be of type XCUIElementTypePickerWheel	abcdef12-1111-2222-3333-444444
order	string	yes	Either next to select the value next to the current one from the target picker wheel or previous to select the previous one.	next
offset	number	no	The value in range [0.01, 0.5]. It defines how far from picker wheel's center the click should happen. The actual distance is calculated by multiplying this value to the actual picker wheel height. Too small offset value may not change the picker wheel value and too high value may cause the wheel to switch two or more values at once. Usually the optimal value is located in range [0.15, 0.3]. 0.2 by default	0.15

mobile: alert

Tries to apply the given action to the currently visible alert.

Arguments

Name	Type	Required	Description	Example
action	string	yes	The actual action to apply. Could be either: accept, dismiss or getButtons	accept
buttonLabel	string	no	The name of the button used to perform the chosen alert action. Only makes sense if the action is accept or dismiss	Accept

Returned Result

The list of alert button names if the selected action is getButtons

mobile: setPasteboard

Sets the Simulator's pasteboard content to the given value. Does not work for real devices.

Arguments

Name	Type	Required	Description	Example
content	string	yes	The content to set	hello
encoding	string	no	The content's encoding. utf8 by default	ascii

mobile: getPasteboard

Gets the Simulator's pasteboard content. Does not work for real devices.

Arguments

Name	Type	Required	Description	Example
encoding	string	no	The expected encoding of the returned string. utf8 by default	ascii

Returned Result

The pasteboard content string.

mobile: source

Allows to retrieve the source tree of the current page in different representation formats.

Arguments

Name	Type	Required	Description	Example
format	string	yes	One of possible page tree source representation formats: xml (the default value), description and json. The xml format generates the output similar to what getPageSource standard API returns. description representation is how XCTest "sees" the page internally and is the same string as debugDescription API would return for the root application element. This source representation format is useful for debugging purposes and is the fastest one to fetch. json representation is similar to xml, but the tree hierarchy there is represented as JSON elements tree rather than as XML nodes.	description
excludedAttributes	string	no	One or more comma-separated attribute names to be excluded from the XML output, thus only makes sense if format is set to xml. It might be sometimes helpful to exclude, for example, the visible attribute, to significantly speed-up page source retrieval.	visible,accessible

Returned Result

The page source tree formatted according to the given format argument.

mobile: getContexts

Retrieves the list of available contexts including the extended context information, like urls and page names. This is different from the standard getContexts API, because the latter only has web view names without any additional information. In situation where multiple web views are available at once the client code would have to connect to each of them in order to detect the one, which needs to be interacted with. Although, this extra effort is not needed with the information provided by this extension.

Arguments

Name	Type	Required	Description	Example
waitForWebviewMs	number	no	Tells Appium for how long (in milliseconds) to wait for web view(s) to appear. 5000ms by default	10000

Returned Result

The list of available context objects along with their properties:

• id: The identifier of the context. The native context will be 'NATIVE_APP' and the webviews will be 'WEBVIEW_xxx'
• title: The title associated with the webview content. Could be null
• url: The url associated with the webview content. Could be null

mobile: installApp

Installs the given application to the device under test. Make sure the app is built for a correct architecture and is signed with a proper developer signature (for real devices) prior to install it.

Arguments

Name	Type	Required	Description	Example
app	string	yes	See the description of the appium:app capability	/path/to/my.app
timeoutMs	number	no	The maximum time to wait until app install is finished in milliseconds on real devices. If not provided then the value of appium:appPushTimeout capability is used. If the capability is not provided then equals to 240000ms	500000
strategy	string	no	One of possible app installation strategies on real devices. This argument is ignored on simulators. If not provided then the value of appium:appInstallStrategy is used. If the latter is also not provided then serial is used. See the description of appium:appInstallStrategy capability for more details on available values.	parallel

mobile: isAppInstalled

Checks whether the given application is installed on the device under test.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be checked	com.mycompany.myapp

Returned Result

Either true or false

mobile: removeApp

Removes the given application from the device under test.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be removed	com.mycompany.myapp

Returned Result

Either true if the app was successfully uninstalled, otherwise false

mobile: launchApp

Executes the given app on the device under test. If the app is already running then it would be activated. If the app is not installed or cannot be launched then an exception is thrown.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be launched	com.mycompany.myapp
arguments	string|array	no	One or more command line arguments for the app. If the app is already running then this argument is ignored.	['-s', '-m']
environment	dict	no	Environment variables mapping for the app. If the app is already running then this argument is ignored.	{'var': 'value'}

mobile: terminateApp

Terminates the given app on the device under test via XCTest's terminate API. If the app is not installed an exception is thrown. If the app is not running then nothing is done.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be terminated	com.mycompany.myapp

Returned Result

Either true if the app was successfully terminated, otherwise false

mobile: killApp

Kill the given app on the real device under test by instruments service. If the app is not running or failed to kill, then nothing is done.

XCUITest driver 4.4 and higher does not require py-ios-device. XCUITest driver 4.3 requires py-ios-device.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be terminated	com.mycompany.myapp

Returned Result

Either true if the app was successfully killed, otherwise false

mobile: queryAppState

Queries the state of an installed application from the device under test. An exception will be thrown if the app with given identifier is not installed.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be queried	com.mycompany.myapp

Returned Result

An integer number is returned, which encodes the application state. Possible values are described in XCUIApplicationState XCTest documentation topic.

mobile: activateApp

Puts the given application to foreground if it is running in the background. An error is thrown if the app is not installed or is not running. Nothing is done if the app is already running in the foreground.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the application to be activated	com.mycompany.myapp

mobile: listApps

List applications installed on the real device under test. This extension throws an error if called for a Simulator device.

Arguments

Name	Type	Required	Description	Example
applicationType	string	no	The type of applications to list. Either System or User (the default one)	System

Returned Result

A list of apps, where each item is a map where keys are bundle identifiers and values are maps of platform-specific app properties. Having UIFileSharingEnabled set to true in the app properties map means this app supports files upload and download into its documents container. Read Pushing/Pulling files for more details.

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 12 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 Instruments User Guide for more details. If the recording for the given profile is already running then nothing is done.

Arguments

Name	Type	Required	Description	Example
timeout	number	no	The maximum count of milliseconds to record the profiling information. It is recommended to always limit the maximum duration of perf record operation, since the resulting logs are pretty huge and may easily exceed the free space on th local storage volume. 300000ms by default (5 minutes)	600000
profileName	string	no	The name of existing performance profile to apply. Can also contain the full path to the chosen template on the server file system. Note, that not all profiles are supported on mobile devices. Activity Monitor by default.	Time Profile
pid	string or number	no	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).	current

mobile: stopPerfRecord

Stops the performance recording operation previosuly started by mobile: startPerfRecord call. If the previous call has already been completed due to the timeout then its result is returned immediately. An error is thrown if the performance recording has failed to start and recorded no data.

Arguments

Name	Type	Required	Description	Example
profileName	string	no	The name of existing performance profile to stop the recording for. Multiple recorders for different profile names could be executed at the same time. Activity Monitor by default.	Time Profile
remotePath	string	no	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.	https://myserver/upload
user	string	no	The name of the user for the remote authentication. Only works if remotePath is provided.	myuser
pass	string	no	The password for the remote authentication. Only works if remotePath is provided.	mypassword
method	string	no	The http multipart upload method name. Only works if remotePath is provided. PUT by default	POST
headers	dict	no	Additional headers mapping for multipart http(s) uploads	{'User-Agent': 'Myserver 1.0'}
fileFieldName	string	no	The name of the form field, where the file content BLOB should be stored for http(s) uploads. file by default	payload
formFields	dict or array	no	Additional form fields for multipart http(s) uploads	{'field2': 'value2'}

Returned Result

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

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 the certificate could be installed via CLI if py-ios-device tool is available on the server machine. On 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.

Arguments

Name	Type	Required	Description	Example
content	string	yes	Base64-encoded content of the public certificate in PEM format	a23234...
commonName	string	no	Common name of the certificate. If this is not set then the script will try to parse it from the given certificate content.	com.myorg
isRoot	boolean	no	This option defines where the certificate should be installed to: either Trusted Root Store (true, the default option) or the Keychain (false). On environments other than Xcode 11.4+ Simulator this option is ignored.	false

Returned Result

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.

mobile: listCertificates

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

Returned Result

Returns map of certificates installed on the real device. The response looks like:

{
    'OrderedIdentifiers': ['com.orgname.profile.mdmprofile'],
    'ProfileManifest': {
        'com.orgname.profile.mdmprofile': {
            'Description': 'MDM Profile',
            'IsActive': True
        }
    },
    'ProfileMetadata': {
        'com.orgname.profile.mdmprofile': {
            'PayloadDescription': 'MDM Profile for testing,
            'PayloadDisplayName': 'MDM Profile',
            'PayloadOrganization': 'My Org, Inc.',
            'PayloadRemovalDisallowed': False,
            'PayloadUUID': '9ab3fa27-cc45-4c23-a94a-714686397a86',
            'PayloadVersion': 1
        }
    },
    'Status': 'Acknowledged'
}

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. Read Using Mobile Execution Commands to Continuously Stream Device Logs with Appium Appium Pro article for more details on this feature.

mobile: stopLogsBroadcast

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

mobile: batteryInfo

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

Returned Result

The actual battery info map, which consists of the following entries:

• level: Battery level in range [0.0, 1.0], where 1.0 means 100% charge.
• state: Battery state as an integer number. The following values are possible:
• UIDeviceBatteryStateUnknown = 0
• UIDeviceBatteryStateUnplugged = 1 // on battery, discharging
• UIDeviceBatteryStateCharging = 2 // plugged in, less than 100%
• UIDeviceBatteryStateFull = 3 // plugged in, at 100%

mobile: deviceInfo

Returns the miscellaneous information about the device under test. It includes device information via lockdown in a real device since XCUITest driver 4.2.0.

Returned Result

Check the + (id<FBResponsePayload>)handleGetDeviceInfo:(FBRouteRequest *)request method in FBCustomCommands.m for more details on the available map entries.

mobile: getDeviceTime

Returns the actual device time.

Arguments

Name	Type	Required	Description	Example
format	string	no	The format specifier string. Read MomentJS documentation to get the full list of supported datetime format specifiers. The default format is YYYY-MM-DDTHH:mm:ssZ, which complies to ISO-8601	YYYY-MM-DD HHss

Returned Result

The retrieved datetime string formatted according to the given format specfier.

mobile: activeAppInfo

Returns information about the active application.

Returned Result

Check the + (id<FBResponsePayload>)handleActiveAppInfo:(FBRouteRequest *)request method in FBCustomCommands.m for more details on the available map entries.

mobile: pressButton

Emulates press action on the given physical device button. iOS is pressButton:, tvOS is pressButton: or pressButton:forDuration:. mobile: performIoHidEvent calls a more universal API to perform press with duration on any supported device.

Arguments

Name	Type	Required	Description	Example
name	string	yes	The name of the button to be pressed. Supported button names for iOS-based devices are (case-insensitive): home, volumeup, volumedown. For tvOS-based devices (case-insensitive): home, up, down, left, right, menu, playpause, select	home
durationSeconds	number	no	Duration in float seconds for tvOS-based devices since Appium 1.22.0	10

mobile: pushNotification

Simulates push notification delivery to Simulator. Only application remote push notifications are supported. VoIP, Complication, File Provider, and other types are not supported. Check the output of xcrun simctl help push command for more details.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the target application	com.apple.Preferences
payload	map	yes	Valid Apple Push Notification values. Read the Create the JSON Payload topic of the official Apple documentation for more details on the payload creation.	{"aps": {"alert": {"title": "This is a simulated notification!"}, "badge": 3, "sound": "default"} }

mobile: expectNotification

Blocks until the expected notification is delivered. It is a thin wrapper over XCTNSNotificationExpectation and XCTDarwinNotificationExpectation entities. The extension call throws TimeoutError if the expected notification has not been delivered within the given timeout.

Arguments

Name	Type	Required	Description	Example
name	string	yes	The name of the notification to expect	com.example.fooAllDone
type	string	no	Which notification type to expect. Either plain (the default value) to wait for a notification from the default notification center or darwin to wait for a system notification.	darwin
timeoutSeconds	number	no	For how long to wait until the notification is delivered in float seconds. 60 seconds by default	5.5

mobile: performIoHidEvent

Emulates triggering of the given low-level IO HID device event. Constants for possible events are defined in XNU kernel IO HID usage tables. For example, in order to emulate single press on Home button the extension should be called with the following arguments: - page: 0x0C (kHIDPage_Consumer, select the Customer page) - usage: 0x40 (kHIDUsage_Csmr_Menu, the Csmr prefix here means this usage is dedicated to the Customer page) - durationSeconds: 0.005 (The event duration should be 5 milliseconds to be recognized as a single press by iOS)

Some popular constants:

Name	Value	Description
kHIDPage_Consumer	0x0C	The page containing all usages prefixed with kHIDUsage_Csmr_
kHIDUsage_Csmr_VolumeIncrement	0xE9	Volume Up
kHIDUsage_Csmr_VolumeDecrement	0xEA	Volume Down
kHIDUsage_Csmr_Menu	0x40	Home
kHIDUsage_Csmr_Power	0x30	Power/Lock
kHIDUsage_Csmr_Snapshot	0x65	Power + Home

Arguments

Name	Type	Required	Description	Example
page	int	yes	The event page identifier. Look for constants perfixed with kHIDPage_ in the table above	0x0C
usage	int	yes	The event usage identifier (usages are defined per-page). Look for constants prefixed with kHIDUsage_ in the table above	0x40
durationSeconds	number	yes	The event duration in float seconds. XCTest uses 0.005 for a single press event duration	2.5

mobile: enrollBiometric

Enrolls biometric authentication on Simulator.

Arguments

Name	Type	Required	Description	Example
isEnabled	boolean	no	Whether to enable/disable biometric enrollment. true by default.	true

mobile: sendBiometricMatch

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

Arguments

Name	Type	Required	Description	Example
type	string	no	The biometric feature name. Either touchId or faceId. touchId by default.	faceId
match	boolean	no	Whether to simulate biometric match (true, the default value) or non-match (false).	true

mobile: isBiometricEnrolled

Checks whether biometric is currently enrolled or not on a Simulator device.

Returned Result

Either true or false

mobile: clearKeychains

Clears keychains on Simulator. An exception is thrown for real devices.

mobile: getPermission

Gets application permission state on Simulator. This method requires WIX applesimutils to be installed on the host where Appium server is running.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the destination app.	com.mycompany.myapp
service	string	yes	One of available service names. The following services are supported: calendar, camera, contacts, homekit, microphone, photos, reminders, medialibrary, motion, health, siri, speech.	true

Returned Result

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

mobile: setPermission

Set application permission state on Simulator. This method requires WIX applesimutils to be installed on the host where Appium server is running.

Arguments

Name	Type	Required	Description	Example
bundleId	string	yes	The bundle identifier of the destination app.	com.mycompany.myapp
access	map	yes	One or more access rules to set. The following keys are supported: all (Apply the action to all services), calendar (Allow access to calendar), contacts-limited (Allow access to basic contact info), contacts (Allow access to full contact details), location (Allow access to location services when app is in use), location-always (Allow access to location services at all times), photos-add (Allow adding photos to the photo library), photos (Allow full access to the photo library), media-library (Allow access to the media library), microphone (Allow access to audio input), motion (Allow access to motion and fitness data), reminders (Allow access to reminders), siri (Allow use of the app with Siri.). The following values are supported: yes (To grant the permission), no (To revoke the permission), unset (To reset the permission)	{'all': 'yes'}

mobile: resetPermission

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

Arguments

Name	Type	Required	Description	Example
service	string or int	yes	One of available service names. The supported service names are: calendar, camera, contacts, health, homekit, keyboardnet, location, medialibrary, microphone, photos, reminders, systemroot, userdesktop, userdocuments, userdownloads, bluetooth. This could also be an integer protected resource identifier taken from XCUIProtectedResource	photos

mobile: getAppearance

Get the device's UI appearance style.

Returned Result

An object, with the following entries: - style: The device's UI appearance value. This could be one of: light, dark, unknown, unsupported

mobile: setAppearance

Set the device's UI appearance style.

Arguments

Name	Type	Required	Description	Example
style	string	yes	Either light or dark	dark

mobile: siriCommand

Presents the Siri UI, if it is not currently active, and accepts a string which is then processed as if it were recognized speech. Check the documentation on activateWithVoiceRecognitionText XCTest method for more details.

Arguments

Name	Type	Required	Description	Example
text	string	yes	The actual command that will be passed to Siri service	Hello Siri

mobile: pullFile

Pulls a remote file from the device.

Arguments

Name	Type	Required	Description	Example
remotePath	string	yes	The path to an existing remote file on the device. This variable can be prefixed with bundle id, so then the file will be pulled from the corresponding application container instead of the default media folder. Use @<app_bundle_id>:<optional_container_type>/<path_to_the_file_or_folder_inside_container> format to pull a file from an application container of the given type. The only supported container type for real devices is documents. You could use listApps extension to check whether this container is available for the particluar app. Containers available for Simulators: app, data, groups, <A specific App Group container>. Eventually the whole Simulator file system is available directly from Finder, so you may pull any file from there by providing a path to it relatively to Simulator's file system root. If the file with the given name does not exist an exception will be thrown.	@com.mycompany.myapp:documents/myfile.txt

Returned Result

Base64-encoded string, which represents the content of the remote file.

mobile: pushFile

Pushes a local file to the device.

Arguments

Name	Type	Required	Description	Example
remotePath	string	yes	The path on the device to where the payload should be written. The value format is similar to the one used in pullFile extension. If the file with the same name already exists then it will be silently overridden.	@com.mycompany.myapp:documents/myfile.txt
payload	string	yes	Base64-encoded content of the file to be pushed.	QXBwaXVt

mobile: pullFolder

Pulls a remote folder from the device.

Arguments

Name	Type	Required	Description	Example
remotePath	string	yes	Same as for pullFile extension, but should be pointing to a remote folder	@com.mycompany.myapp:documents/myfolder/

Returned Result

Base64-encoded string, which represents the zipped content of the remote folder.

mobile: deleteFile

Deletes the given file from the device under test.

Arguments

Name	Type	Required	Description	Example
remotePath	string	yes	Same as for pullFile extension	@com.mycompany.myapp:documents/myfile.txt

mobile: deleteFolder

Deletes the given folder from the device under test.

Arguments

Name	Type	Required	Description	Example
remotePath	string	yes	Same value as for mobile: deleteFile except of the fact it should be pointing to a folder and should end with a single slash /	@com.mycompany.myapp:documents/myfolder/

mobile: configureLocalization

Change localization settings on the currently booted Simulator. The changed settings are only applied for the newly started applications/activities. Currently running applications will stay unchanged. This means, for example, that the keyboard should be hidden and shown again in order to observe the changed layout, and curresponding apps must be restarted in order to observe their interface using the newly set locale/language. Be careful while setting the actual arguments since their actual values are not strictly checked. This could lead to an unexpected behavior if an incorrect/unsupported language or locale abbreviation is provided.

Arguments

Name	Type	Required	Description	Example
keyboard	map	no	On-screen keyboard properties. The name key is required and should be set to a valid locale abbreviation. The layout key is also required. The hardware key is optional and could be omitted or set to Automated. You could switch the keyboard layout in system preferences of your booted simulator, run xcrun simctl spawn booted defaults read .GlobalPreferences.plist, and inspect the value of AppleKeyboards to see possible combinations.	{"name": "de_CH", "layout": "QWERTZ", "hardware": "Automated"}
language	map	no	System language properties. The name key is required and should be set to a valid language abbreviation. You could switch the system language in preferences of your booted simulator, run xcrun simctl spawn booted defaults read .GlobalPreferences.plist, and inspect the value of AppleLanguages to see possible combinations.	{"name": "zh-Hant-CN"}
locale	map	no	System locale properties. The name key is required and should be set to a valid language abbreviation. The calendarkey is optonal and could be set to a valid calendar format name. You could switch the system locale/calendar format in preferences of your booted simulator, run xcrun simctl spawn booted defaults read .GlobalPreferences.plist, and inspect the value of AppleLocale to see possible combinations.	{"name": "uk_UA", "calendar": "gregorian"}

Returned Result

true if any of settings has been successfully changed.

mobile: startAudioRecording

Records the given hardware audio input into an .mp4 file. You must allow the audio_record security feature in order to use this extension. Also it is required that FFMpeg is installed on the machibe where Appium server is running.

Arguments

Name	Type	Required	Description	Example
audioInput	string or int	yes	The name of the corresponding audio input device to use for the capture. The full list of capture devices could be shown using ffmpeg -f avfoundation -list_devices true -i "" Terminal command.	1
audioCodec	string	no	The name of the audio codec. The Advanced Audio Codec (aac) is used by default.	aac
audioBitrate	string	no	The bitrate of the resulting audio stream. 128k by default.	256k
audioChannels	string or int	no	The count of audio channels in the resulting stream. Setting it to 1 will create a single channel (mono) audio stream. 2 By default	1
audioRate	string or int	no	The sampling rate of the resulting audio stream. 44100 by default	22050
timeLimit	string or int	no	The maximum recording time, in seconds. The default value is 180, the maximum value is 43200 (12 hours).	60
forceRestart	boolean	no	Whether to restart audio capture process forcefully when startRecordingAudio is called (true) or ignore the call until the current audio recording is completed (false, the default value).	true

mobile: stopAudioRecording

Stops 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.

Returned Result

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

mobile: startPcap

Start mobile device network traffic capture. This extension only works if py-ios-device utility is installed on the server machine and only supports real iOS devices.

Arguments

Name	Type	Required	Description	Example
timeLimitSec	string or int	no	The maximum recording time, in seconds. The default value is 180, the maximum value is 43200 (12 hours).	60
forceRestart	boolean	no	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).	true

mobile: stopPcap

Stops network traffic capture. 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.

Returned Result

Base64-encoded content of the traffic capture file (.pcap) or an empty string if no traffic capture has been started before. Netowrk capture files could be opened in Wireshark application.

mobile: runXCTest

Run a native XCTest script. Launches a subprocess that runs the XC Test and blocks until it is completed. Parses the stdout of the process and returns its result as an array. Facebook's IDB tool is required to run such tests.

Arguments

Name	Type	Required	Description	Example
testRunnerBundleId	string	yes	Test app bundle	io.appium.XCTesterAppUITests.xctrunner
appUnderTestBundleId	string	yes	App-under-test bundle	com.mycompany.myapp
xcTestBundleID	string	yes	xctest bundle id	io.appium.XCTesterAppUITests
testType	string	no	Test type. Either ui (the default one), app or logic	app
env	map	no	Environment variables mapping to be passed to the test	{'myvar': 'myvalue'}
args	array	no	Launch arguments to start the test with (see https://developer.apple.com/documentation/xctest/xcuiapplication/1500477-launcharguments for reference)	['-arg1', '--arg2']
timeout	string or int	no	Timeout if session doesn't complete after given time (in milliseconds). 360000ms by default	120000

Returned Result

The API calls returns a map with the following entries:

• results: The array of test results. Each item in this array conists of the following entries:
• testName: Name of the test (e.g.: 'XCTesterAppUITests - XCTesterAppUITests.XCTesterAppUITests/testExample')
• passed: Did the tests pass?
• crashed: Did the tests crash?
• status: Test result status (e.g.: 'passed', 'failed', 'crashed')
• duration: How long did the tests take (in seconds)
• failureMessage: Failure message (if applicable)
• location The geolocation of the test (if applicable)
• code: The exit code of the process. 0 value marks a successful execution.
• signal: The signal that terminated the process. Could be null (e.g.: SIGTERM)

mobile: installXCTestBundle

Installs an XCTest bundle to the device under test. Facebook's IDB tool is required to for this API to work.

Arguments

Name	Type	Required	Description	Example
xctestBundle	string	yes	Path to your xctest .app bundle. Could be an URL	/path/to/my/bundle.app

mobile: listXCTestBundles

List XCTest bundles that are installed on device. Facebook's IDB tool is required to for this API to work.

Returned Result

Array of XCTest bundles (e.g.: ["XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance"])

mobile: listXCTestsInTestBundle

List XCTests in a test bundle. Facebook's IDB tool is required to for this API to work.

Arguments

Name	Type	Required	Description	Example
bundle	string	yes	Bundle ID of the XCTest	'com.bundle.myapp'

Returned Result

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

mobile: viewportRect

Retrieves the viwport dimensions. The viewport is the device's screen size with status bar size subtracted if the latter is present/visible.

Returned Result

The response looks like {"value":{"left":0,"top":96,"width":828,"height":1696}}.

left and top are distance from the left of the screen and the top of the screen. iOS Drawing Concepts could help about the relationship of coordinate.

width and height are the screen's width and height.

mobile: deviceScreenInfo

Get information about screen.

Returned Result

The response looks like {"value":{"statusBarSize":{"width":414,"height":48},"scale":2}}

statusBarSize contains status bar dimensions. It is the result of status bar. scale is screen scale.

mobile: swipe

This gesture performs a simple "swipe" gesture on the particular screen element or on the application element, which is usually the whole screen. This method does not accept coordinates and simply emulates single swipe with one finger. It might be useful for such cases like album pagination, switching views, etc. More advanced cases may require to call mobile: dragFromToForDuration, where one can supply coordinates and duration.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no	The internal element identifier (as hexadecimal hash string) to swipe on. Application element will be used instead if this argument is not provided	fe50b60b-916d-420b-8728-ee2072ec53eb
direction	Either 'up', 'down', 'left' or 'right'	yes	The direction in which to swipe	up
velocity	number	no	This argument is optional and is only supported since Appium server version 1.19 and Xcode SDK version 11.4+. The value is measured in pixels per second and same values could behave differently on different devices depending on their display density. Higher values make swipe gesture faster (which usually scrolls larger areas if we apply it to a list) and lower values slow it down. Only values greater than zero have effect.	250

Examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
Map<String, Object> params = new HashMap<>();
params.put("direction", "down");
params.put("velocity", 2500);
params.put("element", ((RemoteWebElement) element).getId());
js.executeScript("mobile: swipe", params);

References

• swipeDown
• swipeDownWithVelocity:
• swipeUp
• swipeUpWithVelocity:
• swipeLeft
• swipeLeftWithVelocity:
• swipeRight
• swipeRightWithVelocity:

mobile: scroll

Scrolls the element or the whole screen. Different scrolling strategies are supported. Arguments define the choosen strategy: either 'name', 'direction', 'predicateString' or 'toVisible' in that order. All strategies are exclusive and only one strategy can be applied at a single moment of time. Use "mobile: scroll" to emulate precise scrolling in tables or collection views, where it is already known to which element the scrolling should be performed. Although, there is one known limitation there: in case it is necessary to perform too many scroll gestures on parent container to reach the necessary child element (tens of them) then the method call may fail. Important: The implemntation of this extension relies on several undocumented XCTest features, which might not always be reliable. Thus it might not always work as expected.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no	The internal element identifier (as hexadecimal hash string) to scroll on (e.g. the container). Application element will be used if this argument is not set	fe50b60b-916d-420b-8728-ee2072ec53eb
name	string	no	The accessibility id of the child element, to which scrolling is performed. The same result can be achieved by setting predicateString argument to 'name == accessibilityId'. Has no effect if elementId is not a container	cell12
direction	Either 'up', 'down', 'left' or 'right'	yes	The main difference from swipe call with the same argument is that scroll will try to move the current viewport exactly to the next/previous page (the term "page" means the content, which fits into a single device screen)	down
predicateString	string	no	The NSPredicate locator of the child element, to which the scrolling should be performed. Has no effect if elementId is not a container	label == "foo"
toVisible	boolean	no	If set to true then asks to scroll to the first visible elementId in the parent container. Has no effect if elementId is not set	true

Examples

# Python
driver.execute_script('mobile: scroll', {'direction': 'down'});

mobile: pinch

Performs pinch gesture on the given element or on the application element.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no	The internal element identifier (as hexadecimal hash string) to pinch on. Application element will be used instead if this parameter is not provided	fe50b60b-916d-420b-8728-ee2072ec53eb
scale	number	yes	Pinch scale of type float. Use a scale between 0 and 1 to "pinch close" or zoom out and a scale greater than 1 to "pinch open" or zoom in.	0.5
velocity	number	yes	The velocity of the pinch in scale factor per second (float value)	2.2

Examples

# Ruby
execute_script 'mobile: pinch', scale: 0.5, velocity: 1.1, element: element.ref

Reference

pinchWithScale:velocity:

mobile: doubleTap

Performs double tap gesture on the given element or on the screen.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no if x and y are set	The internal element identifier (as hexadecimal hash string) to double tap on	fe50b60b-916d-420b-8728-ee2072ec53eb
x	number	no if elementId is set	Screen x tap coordinate of type float.	100
y	number	no if elementId is set	Screen y tap coordinate of type float.	100

Examples

// javascript
driver.execute('mobile: doubleTap', {element: element.value.ELEMENT});

mobile: touchAndHold

Performs long press gesture on the given element or on the screen.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no if x and y are set	The internal element identifier (as hexadecimal hash string) to long tap on	fe50b60b-916d-420b-8728-ee2072ec53eb
duration	number	yes	The float duration of press action in seconds	1.5
x	number	no if elementId is set	Screen x tap coordinate of type float.	100
y	number	no if elementId is set	Screen y tap coordinate of type float.	100

Examples

// c#
Dictionary<string, object> tfLongTap = new Dictionary<string, object>();
tfLongTap.Add("element", element.Id);
tfLongTap.Add("duration", 2.0);
((IJavaScriptExecutor)driver).ExecuteScript("mobile: touchAndHold", tfLongTap);

Reference

pressForDuration:

mobile: twoFingerTap

Performs two finger tap gesture on the given element or on the application element.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no	The internal element identifier (as hexadecimal hash string) to tap on. Application element will be used instead if this parameter is not provided	fe50b60b-916d-420b-8728-ee2072ec53eb

Examples

// c#
Dictionary<string, object> tfTap = new Dictionary<string, object>();
tfTap.Add("element", element.Id);
((IJavaScriptExecutor)driver).ExecuteScript("mobile: twoFingerTap", tfTap);

Reference

twoFingerTap

mobile: tap

Performs tap gesture by coordinates on the given element or on the screen.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no	The internal element identifier (as hexadecimal hash string) to tap on. x and y tap coordinates will be calulated relatively to the current element position on the screen if this argument is provided. Otherwise they should be calculated relatively to the active application element.	fe50b60b-916d-420b-8728-ee2072ec53eb
x	number	yes	Screen x tap coordinate of type float.	100
y	number	yes	Screen y tap coordinate of type float.	100

mobile: dragFromToForDuration

Performs drag and drop gesture by coordinates. This can be done either on an element or on the screen

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	no	The internal element identifier (as hexadecimal hash string) to perform drag on. All the coordinates will be calculated relatively this this element position on the screen. Absolute screen coordinates are expected if this argument is not set	fe50b60b-916d-420b-8728-ee2072ec53eb
duration	number	yes	Float number of seconds in range [0.5, 60]. How long the tap gesture at starting drag point should be before to start dragging	5.3
fromX	number	yes	The x coordinate of starting drag point	100
fromY	number	yes	The y coordinate of starting drag point	100
toX	number	yes	The x coordinate of ending drag point	200
toY	number	yes	The y coordinate of ending drag point	200

Examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
Map<String, Object> params = new HashMap<>();
params.put("duration", 1.0);
params.put("fromX", 100);
params.put("fromY", 100);
params.put("toX", 200);
params.put("toY", 200);
params.put("element", ((RemoteWebElement) element).getId());
js.executeScript("mobile: dragFromToForDuration", params);

Reference

clickForDuration:thenDragToElement:

mobile: dragFromToWithVelocity

Initiates a press-and-hold gesture, drags to another coordinate or an element with a velocity you specify, and holds for a duration you specify.

Arguments

Name	Type	Required	Description	Example
fromElementId	string	no	The internal element identifier (as hexadecimal hash string) to start the drag gesture from. Absolute screen coordinates are expected if this argument is not set	fe50b60b-916d-420b-8728-ee2072ec53eb
toElementId	string	no	The internal element identifier (as hexadecimal hash string) to end the drag gesture on. This parameter is mandatory if fromElementId is provided	fe50b60b-916d-420b-8728-ee2072ec53eb
pressDuration	number	yes	Float number of seconds in range [0, 60]. How long the tap gesture at starting drag point should be before to start dragging	0.5
holdDuration	number	yes	Float number of seconds in range [0, 60]. The duration for which to hold over the other coordinate or the given element after dragging	0.1
velocity	number	yes	The speed at which to move from the initial press position to the other element or coordinate, expressed in pixels per second	400
fromX	number	no	The x coordinate of starting drag point. Must be provided if fromElementId is not defined	100
fromY	number	no	The y coordinate of starting drag point. Must be provided if fromElementId is not defined	100
toX	number	no	The x coordinate of ending drag point. Must be provided if fromElementId is not defined	200
toY	number	no	The y coordinate of ending drag point. Must be provided if fromElementId is not defined	200

References

pressForDuration:thenDragToElement:withVelocity:thenHoldForDuration: pressForDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration:

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 value selection does not work because of XCTest bug.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	yes	PickerWheel's internal element id (as hexadecimal hash string) to perform value selection on. The element must be of type XCUIElementTypePickerWheel	fe50b60b-916d-420b-8728-ee2072ec53eb
order	string	yes	Either next to select the value next to the current one from the target picker wheel or previous to select the previous one	next
offset	number	no	The value in range [0.01, 0.5]. It defines how far from picker wheel's center the click should happen. The actual distance is calculated by multiplying this value to the actual picker wheel height. Too small offset value may not change the picker wheel value and too high value may cause the wheel to switch two or more values at once. Usually the optimal value is located in range [0.15, 0.3]. 0.2 by default	0.3

Examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
Map<String, Object> params = new HashMap<>();
params.put("order", "next");
params.put("offset", 0.15);
params.put("element", ((RemoteWebElement) element).getId());
js.executeScript("mobile: selectPickerWheelValue", params);

mobile: rotateElement

Performs rotate gesture on the given element.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	yes	Internal element id (as hexadecimal hash string) to perform rotation on	fe50b60b-916d-420b-8728-ee2072ec53eb
rotation	number	yes	The rotation of the gesture in radians	Math.PI
velocity	number	yes	The velocity of the rotation gesture in radians per second	Math.PI / 4

Examples

// Java
JavascriptExecutor js = (JavascriptExecutor) driver;
js.executeScript("mobile: rotateElement", ImmutableMap.of(
    // rotate clockwise, 90 degrees
    "rotation", -Math.PI / 2,
    // in approximately two seconds
    "velocity", Math.PI / 4,
    "element", ((RemoteWebElement) element).getId()
));

Reference

rotate:withVelocity:

mobile: tapWithNumberOfTaps

Sends one or more taps with one or more touch points since Appium 1.17.1.

Arguments

Name	Type	Required	Description	Example
elementId ("element" prior to Appium v 1.22)	string	yes	The internal element identifier (as hexadecimal hash string) to perform one or more taps.	fe50b60b-916d-420b-8728-ee2072ec53eb
numberOfTaps	number	yes	The number of taps	2
numberOfTouches	number	yes	The number of touch points	2

Examples

# Ruby
e = @driver.find_element :id, 'target element'
# Taps the element with a single touch point twice
@driver.execute_script 'mobile: tapWithNumberOfTaps', {element: e.ref, numberOfTaps: 2, numberOfTouches: 1}

Reference

tapWithNumberOfTaps:numberOfTouches:

mobile: forcePress

Emulates force press on the given element/coordinates. An error is thrown if the target device does not support force press gesture.

Arguments

Name	Type	Required	Description	Example
elementId	string	no	The internal element identifier (as hexadecimal hash string) to perform one or more taps. It is expected that both x and y are provided if this argument is ommitted. If the element identifier is provided without coordinates then the actual element's touch point will be calculated automatically by WebDriverAgent.	fe50b60b-916d-420b-8728-ee2072ec53eb
x	number	no	x coordinate of the gesture. It is calculated relatively to the given element (if provided). Otherwise the gesture destination point is calculated relatively to the active application.	100
y	number	no	y coordinate of the gesture. It is calculated relatively to the given element (if provided). Otherwise the gesture destination point is calculated relatively to the active application	100
duration	number	no	The float number of seconds the force press action would take. If duration is provided then it is also expected that a custom pressure value is provided as well. 0.5 by default.	2.5
pressure	number	no	The float number defining how much pressure to apply. If pressure is provided then it is also expected that a custom duration value is provided as well. 1.0 by default	1.5

mobile: scrollToElement

Scrolls the current viewport to the given element. It is expected the destination element is inside a scrollable container and is hittable. The scroll direction is detected automatically. This API uses native XCTest calls, so it performs scrolling pretty fast. The same native call is implicitly performed by a vanilla click API if the destination element is out of the current viewport. An exception is thrown if the scrolling action cannot be performed. This extension is available since the driver version 4.7.0.

Arguments

Name	Type	Required	Description	Example
elementId	string	yes	The internal element identifier (as hexadecimal hash string) to scroll to. The destination element must be located in a scrollable container and must be hittable. If the element is already present in the current viewport then no action is performed.	fe50b60b-916d-420b-8728-ee2072ec53eb

mobile: resetLocationService

Reset the location service on real device since Appium 1.22.0. It could delay a few seconds to reflect the location by the system. It raises an error if the device is simulator or an error occurred during the reset.

mobile: enableConditionInducer

Important: Device conditions are available for real devices running iOS 13.0 and later.

This API is going to throw an error if it is called while another condition inducer has been already enabled and is not explicitly disabled.

mobile: enableConditionInducer
mobile: disableConditionInducer
mobile: listConditionInducers

The above three extensions are available since the driver version 4.9.0.

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.

Reference: Test under adverse device conditions (iOS)

Name	Type	Required	Description	Example
conditionID	string	yes	Get the conditionID parameter through the command mobile: availableConditionInducer	SlowNetworkCondition
profileID	string	yes	Get the profileID parameter through the command mobile: availableConditionInducer	SlowNetwork100PctLoss

Returned Result

Either true or false, where true means enabling of the condition inducer has been successful

mobile: listConditionInducers

Get all condition inducer configuration profiles

Returned Result

The response looks like

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

mobile: disableConditionInducer

Disable device condition inducer.

Usually a persistent connection is maintained after enable the condition inducer, and this method is only valid for this connection.

If the connection is disconnected, condition inducer will be automatically disabled

Returned Result

Either true or false, where true means disabling of the condition inducer has been successful

mobile: updateSafariPreferences

Updates preferences of Mobile Safari on Simulator

Arguments

Name	Type	Required	Description	Example
preferences	map	yes	An object containing Mobile Safari preferences to be updated. The list of available setting names and their values could be retrieved by changing the corresponding Safari settings under Preferences->Safari 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 actual .plist content to the Terminal.	{ ShowTabBar: 0, WarnAboutFraudulentWebsites: 0 }

mobile: deepLink

Opens the given URL with the default or the given application. This functionality is only available since xcuitest driver version 4.17. Xcode must be at version 14.3+ and iOS must be at version 16.4+.

Arguments

Name	Type	Required	Description	Example
url	string	yes	The URL to be opened. This parameter is manadatory.	https://apple.com, myscheme:yolo
bundleId	string	no	The bundle identifier of an application to open the given url with. If not provided then the default application for the given url scheme is going to be used.	com.myapp.yolo

mobile: getSimulatedLocation

Retrieves simulated geolocation value. This functionality is only available since xcuitest driver version 4.18. Xcode must be at version 14.3+ and iOS must be at version 16.4+.

Returned Result

This API returns a map with the following entries:

Name	Type	Description	Example
latitude	number	Measurement of distance north or south of the Equator. null if mobile: setSimulatedLocation has not been called before or the simulated geolocation has been reset by mobile: resetSimulatedLocation.	50.08546
longitude	number	Measurement of distance east or west of the prime meridian. null if mobile: setSimulatedLocation has not been called before or the simulated geolocation has been reset by mobile: resetSimulatedLocation.	-20.12345

mobile: setSimulatedLocation

Sets simulated geolocation value. This functionality is only available since xcuitest driver version 4.18. Xcode must be at version 14.3+ and iOS must be at version 16.4+.

Arguments

Name	Type	Required	Description	Example
latitude	number	yes	Measurement of distance north or south of the Equator.	50.08546
longitude	number	yes	Measurement of distance east or west of the prime meridian.	-20.12345

mobile: resetSimulatedLocation

Resets the previously set simulated geolocation value. This functionality is only available since xcuitest driver version 4.18. Xcode must be at version 14.3+ and iOS must be at version 16.4+.

Warning 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.