Skip to content

Execute Methods

In addition to standard W3C APIs, the driver provides many custom command extensions for executing platform-specific scenarios. Use the following examples in order to invoke them from your client code:

var result = driver.executeScript("mobile: <methodName>", Map.ofEntries(
    Map.entry("arg1", "value1"),
    Map.entry("arg2", "value2")
    // you may add more pairs if needed or skip providing the map completely
    // if all arguments are defined as optional
));
const result = await driver.executeScript('mobile: <methodName>', [{
    arg1: "value1",
    arg2: "value2",
}]);
result = driver.execute_script('mobile: <methodName>', {
    'arg1': 'value1',
    'arg2': 'value2',
})
result = @driver.execute_script 'mobile: <methodName>', {
    arg1: 'value1',
    arg2: 'value2',
}
object result = driver.ExecuteScript("mobile: <methodName>", new Dictionary<string, object>() {
    {"arg1", "value1"},
    {"arg2", "value2"}
}));

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
value string no If provided WDA will try to automatically scroll in the given direction until the actual picker value reaches the expected one or the amount of scrolling attempts is exceeded. myvalue
maxAttempts number no The maximum number of scrolling attempts to reach value before an error will be thrown. Only makes sense in combination with value. 25 by default 50

mobile: sendMemoryWarning

Simulates sending of Low Memory warning to the target application. It might be useful to verify the didReceiveMemoryWarning API in the application under test. This feature only works on real devices running iOS 17+ with Xcode 15+ SDK. The target application must be running while this API is called.

Arguments

Name Type Required Description Example
bundleId string yes Bundle identifier of the app to simulate the warning for com.great.app

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. Offloaded applications are handled as not installed.

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. Offloaded application can also be removed.

For real devices, please also check how to explicitly clear the application local data.

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. Offload applications will not be in the result.

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 the File Transfer guide for more details.

mobile: clearApp

Deletes data files from the data container of an installed app, so it could start from the clean state next time it is launched. The destination app will be terminated if it is running when this API is invoked. Sometimes it might also be necessary to invoke the following APIs to fully reset the state of an installed app (make sure the app is not running while calling them): - mobile: clearKeychains - mobile: resetPermission

This API might not be 100% reliable for some apps. The only reliable method to fully reset an existing app that Apple supports is to uninstall it and then perform a fresh install of the same app.

This API only works on simulators. An exception is thrown if executed with real devices.

Arguments

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

Returned Result

true if at least one item has been successfully deleted from the app data container.

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: removeCertificate

Removes installed certificate for real devices only if py-ios-device tool is available on the server machine since driver version 4.19.2.

Arguments

Name Type Required Description Example
name string yes Name of the profile com.orgname.profile.mdmprofile

Returned Result

Returns status acknowledgment {'Status': 'Acknowledged'} if successfully removed certificate or None if unable to remove certificate.

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 HH🇲🇲ss

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

location and location-always services are by xcrun simctl privacy command since XCUITest driver version 5.11.0. The command will kill the bundleId application process if it is running.

Other services such as contacts are processed by WIX applesimutils, which will not kill the bundleId application process. WIX applesimutils needs 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. See the File Transfer guide for accepted formats. 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 corresponding apps must be restarted in order to observe their interface using the newly set locale/language. Also this method might leave some system UI alerts untranslated. 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 viewport 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: viewportScreenshot

Takes a screenshot of the device viewport (see mobile: viewportRect)

Unreliable

This method is unreliable. We recommend using getScreenshot instead

Returned Result

Base64-encoded string, which represents the viewport screenshot.

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

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: 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: calibrateWebToRealCoordinatesTranslation

Calibrates web to real coordinates translation. This API can only be called from Safari web context. It must load a custom page to the browser, and then restore the original one, so don't call it if you can potentially lose the current web app state. The outcome of this API is then used if nativeWebTap capability/setting is enabled. The returned value could also be used to manually transform web coordinates to real device ones in client scripts.

It is adviced to call this API at least once before changing the device orientation or device screen layout as the recetly received value is cached for the session lifetime and may become obsolete.

It is advised to enable nativeWebTapStrict capability/setting to speed up dynamic coordinates transformation if you use this extension.

Returned Result

An object with three properties used to properly shift Safari web element coordinates into native context: - offsetX: Webview X offset in real coordinates - offsetY: Webview Y offset in real coordinates - pixelRatioX: Webview X pixel ratio - pixelRatioY: Webview Y pixel ratio

The following formulas are used for coordinates translation: RealX = offsetX + webviewX * pixelRatioX RealY = offsetY + webviewY * pixelRatioY

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 }

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

It is recommended for iOS 17+ real devices to simulate the device location.

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 explicitly then the simulated one will remain until the next device restart.

mobile: getAppStrings

Retrieves string resources for the given app language. An error is thrown if strings cannot be fetched or no strings exist for the given language abbreviation

Arguments

Name Type Required Description Example
language string no The language abbreviation to fetch app strings mapping for. If no language is provided then strings for the 'en language would be returned fr
stringFile string no Relative path to the corresponding .strings file starting from the corresponding .lproj folder base/main.strings

Returned Result

App strings map, where keys are resource identifiers.

mobile: hideKeyboard

Tries to hide the on-screen keyboard. Throws an exception if the keyboard cannot be hidden. On non-tablet devices the keyboard might not have an explicit button to hide it. In such case this API won't work and the only way to close the keyboard would be to simulate the same action an app user would do to close it. For example, swipe from top to bottom or tap the screen somewhere at the area not covered by the keyboard.

Arguments

Name Type Required Description Example
keys string[] no One or more keyboard key names used to close/hide it. On tablet's such button is usually called 'done'.

mobile: isKeyboardShown

Checks if the system on-screen keyboard is visible.

Returned Result

true if the keyboard is visible

mobile: keys

Send keys to the given element or to the application under test. This API is only supported since Xcode 15/iOS 17. It is not supported on tvOS. The API only works on iPad. On iOS calling it has no effect.

Arguments

Name Type Required Description Example
elementId string no Unique identifier of the element to send the keys to. If unset then keys are sent to the current application under test. 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
keys array yes Array of keys to type. Each item could either be a string, that represents a key itself (see the official documentation on XCUIElement's typeKey:modifierFlags: method and on XCUIKeyboardKey constants) or a dictionary with key and modifierFlags entries, if the key should also be entered with modifiers. ['h', 'i'] or [{key: 'h', modifierFlags: 1 << 1}, {key: 'i', modifierFlags: 1 << 2}] or ['XCUIKeyboardKeyEscape']

Note

The modifierFlags argument is of unsigned long type and defines the bitmask with depressed modifier keys for the given key. XCTest defines the following possible bitmasks for modifier keys:

typedef NS_OPTIONS(NSUInteger, XCUIKeyModifierFlags) {
   XCUIKeyModifierNone       = 0,
   XCUIKeyModifierCapsLock   = (1UL << 0),
   XCUIKeyModifierShift      = (1UL << 1),
   XCUIKeyModifierControl    = (1UL << 2),
   XCUIKeyModifierOption     = (1UL << 3),
   XCUIKeyModifierCommand    = (1UL << 4),
   XCUIKeyModifierFunction   = (1UL << 5),
   // These values align with UIKeyModifierFlags and CGEventFlags.
   XCUIKeyModifierAlphaShift = XCUIKeyModifierCapsLock,
   XCUIKeyModifierAlternate  = XCUIKeyModifierOption,
};

So, for example, if you want Ctrl and Shift to be depressed while entering your key then modifierFlags should be set to (1 << 1) | (1 << 2), where the first constant defines XCUIKeyModifierShift and the seconds one - XCUIKeyModifierControl. We apply the bitwise or (|) operator between them to raise both bitflags in the resulting value. The left bitshift (<<) operator defines the binary bitmask for the given modifier key. You may combine more keys using the same approach.

mobile: lock

Lock the device (and optionally unlock it after a certain amount of time). Only simple (e.g. without a password) locks are supported.

Arguments

Name Type Required Description Example
seconds number string no The number of seconds after which to unlock the device. Set to 0 or leave it empty to require manual unlock (e.g. do not block and automatically unlock afterwards).

mobile: unlock

Unlocks the previously locked device. Only simple (e.g. without a password) locks are supported.

mobile: isLocked

Determine whether the device is locked.

Returned Result

Either true or false

mobile: shake

Shakes the device. This functionality is only supported on simulators.

mobile: backgroundApp

Puts the app to the background and waits the given number of seconds. Then restores the app if necessary. The call is blocking.

Arguments

Name Type Required Description Example
seconds number no The amount of seconds to wait between putting the app to background and restoring it. Any negative value means to not restore the app after putting it to background (the default behavior). 5

mobile: performAccessibilityAudit

Performs accessbility audit of the current application according to the given type or multiple types. Wraps the XCTest's performAccessibilityAuditWithAuditTypes API. Only available since Xcode 15/iOS 17.

Arguments

Name Type Required Description Example
auditTypes string[] no One or more type names to perform the audit for. The full list of available names could be found in the official XCTest API documentation. If no type if provided explicitly then XCUIAccessibilityAuditTypeAll is assumed. ['XCUIAccessibilityAuditTypeContrast', 'XCUIAccessibilityAuditTypeElementDetection']

Returned Result

List of found issues or an empty list. Each list item is a map consisting of the following items:

Name Type Description Example
detailedDescription string The detailed description of the found accessbility issue. Some longer issue description
compactDescription string The compact description of the found accessbility issue. Some compact issue description
auditType string or number The name of the audit type this issue belongs to. Could be a number if the type name is unknown. 'XCUIAccessibilityAuditTypeContrast'
element string The description of the element this issue was found for. 'Yes' button
elementDescription string The debug description of the element this issue was found for. Availble since driver version A long string describing the element itself and its position in the page tree hierarchy
elementAttributes dict JSON object containing various attributes of the element. See the example below
"elementAttributes":{
    "isEnabled":"1",
    "isVisible":"1",
    "isAccessible":"0",
    "frame":"{{129, 65}, {135, 18}}",
    "isFocused":"0",
    "rect":{
        "y":65,
        "x":129,
        "width":135,
        "height":18
    },
    "value":"Some Button",
    "label":"Some Button",
    "type":"StaticText",
    "name":"Some Button",
    "rawIdentifier":null
}