Settings
The XCUITest driver exposes various settings through Appium's Settings API.
acceptAlertButtonSelector¶
| Type | Default |
|---|---|
string |
Not specified |
Custom selector for an alert button. This can be used to handle accept buttons with arbitrary text when using the Accept Alert API.
The selector should be a valid class chain
expression, where the search root is the alert element itself, for example, **/XCUIElementTypeButton[`label CONTAINS[c] 'accept'`].
If the provided selector is wrong or does not match any element, the default button location
algorithm is used.
accessibilityDeadline¶
| Type | Default |
|---|---|
float |
0 |
The maximum time in seconds to wait for the frontmost application to confirm its main run loop is responsive before an accessibility snapshot request (element attribute lookups, active app detection, etc). XCTest has no bounded timeout of its own for this, so an application whose main thread stops responding (e.g. it deadlocks, or is kept constantly busy by video/animation playback) could otherwise block WebDriverAgent forever.
Setting this value to 0 (the default) or a negative number disables the check, restoring the
unbounded behavior. Once the deadline is exceeded, the pending request is aborted with an error
instead of hanging indefinitely.
This is not a silver bullet: if the application under test genuinely has long-running animations or transitions, a low deadline would make requests fail (or retry, and thus become much slower) rather than simply waiting them out. Since this is a per-session setting, it is best applied surgically, e.g. only around the specific steps of your test where an unresponsive app is a real risk, rather than left enabled for the whole session. See the WebDriverAgent Slowness guide for more details.
activeAppDetectionPoint¶
| Type | Default |
|---|---|
string |
MIN(w, h) * 0.2, MIN(w, h) * 0.2 |
The coordinates of a point on the device screen, used by WebDriverAgent to detect the currently
active application, if multiple active applications are identified. The format of this value is
a comma-separated list of the exact x and y coordinates (as integers or floats). By default,
it is set to 20% of the screen width and height.
Setting this value to a point outside of the physical device screen may cause undefined behavior.
animationCoolOffTimeout¶
| Type | Default |
|---|---|
float |
2 |
The amount of time in seconds to wait until the application under test does not have any active
animations. This check is usually applied after each automation action that is supposed to change
the state of the application under test (e.g. click), and blocks XCTest until the transition of
the tested application to a new state completes, or the cool off timeout occurs.
Setting this value to 0 disables animation checks completely.
autoClickAlertSelector¶
| Type | Default |
|---|---|
string |
Not specified |
Custom selector for an alert button. This can be used to automatically locate an element inside an alert hierarchy, and tap it as soon as a new alert is detected.
The selector should be a valid class chain
expression, where the search root is the alert element itself, for example, **/XCUIElementTypeButton[`label CONTAINS[c] 'click'`].
If two or more elements match the provided selector, then the very first matched element is tapped
on. If the provided selector does not match any element, no action is performed. An error is thrown
if the provided selector is invalid.
This setting takes priority over the appium:autoAcceptAlerts and
appium:autoDismissAlerts capabilities, i.e. if both are enabled, the destination element to tap on
would be selected based on the autoClickAlertSelector selector value.
boundElementsByIndex¶
| Type | Default |
|---|---|
boolean |
false |
Whether to look up elements using allElementsBoundByIndex,
as opposed to the default approach using allElementsBoundByAccessibilityElement.
This Stack Overflow topic
explains the difference.
currentDisplayId¶
| Type | Default |
|---|---|
int or null |
null (the main display) |
Identifier of the display that should be used for driver actions such as retrieving screenshots,
W3C actions, MJPEG streams, and new XCTest recordings. Available values can be retrieved using the
mobile: listDisplays execute method.
If set to null, the display is reset to the default one.
This setting does not affect the page source and element lookup - the accessibility hierarchy belongs to the application rather than to a display.
If using MJPEG streaming, the stream follows display changes and pauses if the display becomes
unavailable. After changing this setting, the MJPEG screenshot cache is bypassed for the rest of
the session, including after resetting the setting to null. MJPEG frames do not identify their
source display, so buffered frames cannot safely be reused after a display change.
If using XCTest recordings, they retain their initial display; restart the recording to change it.
On foldable devices such as the iPhone Duo, changing the hinge angle does not affect this setting. See the iPhone Duo Automation guide for more details.
defaultActiveApplication¶
| Type | Default |
|---|---|
string |
auto |
The suggested active application. This is used by WebDriverAgent to automatically select the currently active application if multiple such applications are found. The setting is particularly useful for automating split-screen apps, but also applies when dealing with native system alerts or overlays (see Element Lookup Troubleshooting).
For system permission dialogs, use com.apple.springboard on iOS or com.apple.PineBoard
on tvOS. Set the value back to auto after handling the dialog. See
System Dialog Troubleshooting
for examples and alternatives.
dismissAlertButtonSelector¶
| Type | Default |
|---|---|
string |
Not specified |
Custom selector for an alert button. This can be used to handle dismiss buttons with arbitrary text when using the Dismiss Alert API.
The selector should be a valid class chain
expression, where the search root is the alert element itself, for example, **/XCUIElementTypeButton[`label CONTAINS[c] 'dismiss'`].
If the provided selector is wrong or does not match any element, the default button location
algorithm is used.
elementResponseAttributes¶
| Type | Default |
|---|---|
| string | type,label |
Element attribute names to be included into the findElement response, as a comma-separated
list. The following values are supported: type, name, label, text, rect, enabled,
displayed, selected, attribute/<attribute_name>.
This setting only has an effect if the shouldUseCompactResponses
setting is set to false.
enforceCustomSnapshots¶
| Type | Default |
|---|---|
boolean |
false |
Whether to instruct WebDriverAgent to always use use a customized snapshotting mechanism using
private XCTest APIs, as opposed to the
standard snapshotWithError
approach.
By default, WebDriverAgent only uses the custom approach for some particular cases where standard snapshots may provide unreliable or distorted results, but this may not cover all cases, for example, with custom keyboards. Setting this value may help with handling such edge cases, though it may also result in snapshots being slower and less memory efficient.
includeCustomActionsInPageSource¶
| Type | Default |
|---|---|
boolean |
false |
Whether the customActions attribute should be included
in the page source XML tree.
includeHittableInPageSource¶
| Type | Default |
|---|---|
boolean |
false |
Whether the hittable attribute should be included in the page
source XML tree.
includeMinMaxValueInPageSource¶
| Type | Default |
|---|---|
boolean |
false |
Whether the minValue and maxValue
attributes should be included in the page source XML tree.
includeNativeAccessibilityElementInPageSource¶
| Type | Default |
|---|---|
boolean |
false |
Whether the nativeAccessibilityElement
attribute should be included in the page source XML tree.
keyboardAutocorrection¶
| Type | Default |
|---|---|
boolean |
false |
Changes the system-wide "Auto-Correction" option (Settings -> General -> Keyboard).
keyboardPrediction¶
| Type | Default |
|---|---|
boolean |
false |
Changes the system-wide "Predictive Text" option (Settings -> General -> Keyboard).
keyboardWaitTimeout¶
| Type | Default |
|---|---|
float |
0 |
The number of seconds to wait for a hittable key before typing on iOS. 0 (the default) disables
the wait, and null sets the value back to 0. The text is typed immediately.
A positive value waits up to that many seconds for a key that is on screen and hittable, then types the whole string once. The string is still typed once if no such key appears before the timeout.
A boolean, a negative number, or a non-finite number is rejected. The wait applies when typing into an element and when sending keys.
limitXPathContextScope¶
| Type | Default |
|---|---|
boolean |
true |
Whether to limit the page source to the parent element when using scoped element searches.
This ensures that a chained query like findElement(By.xpath, "//XCUIElementTypeAlert").findElement(By.xpath, "//XCUIElementTypeButton")
correctly applies the parent scoped context, however, a query like findElement(By.xpath, "//XCUIElementTypeButton").findElement(By.xpath, "./..")
will fail, because the first half of it will only return descendants of the target element.
Disabling this setting would cause the latter query to no longer fail, but it will also cause the
former query to ignore the parent scoped context. You can use the . notation to adjust the scope
of the former query like so: findElement(By.xpath, "//XCUIElementTypeAlert").findElement(By.xpath, ".//XCUIElementTypeButton")
maxTypingFrequency¶
| Type | Default |
|---|---|
int |
60 |
Maximum frequency of keystrokes per minute, used for for typing and clearing text fields. Setting a smaller value may help if your tests are failing due to typing errors.
mjpegFixOrientation¶
| Type | Default |
|---|---|
boolean |
true |
Whether to automatically normalize the orientation of MJPEG frames so that they match the current device orientation. Affects only the MJPEG screenshots broadcaster and does not change regular screenshot responses. See the MJPEG guide for more details.
When using appium:mjpegScreenshotUrl, explicitly setting mjpegFixOrientation to true
also applies JPEG EXIF orientation before the driver converts cached frames to PNG screenshots.
If the setting is omitted or explicitly false, conversion preserves its previous behavior.
mjpegServerFramerate¶
| Type | Default |
|---|---|
int |
10 |
The maximum number of screenshots per second taken by the MJPEG screenshots broadcaster. Must be in
the range 1..60. See the MJPEG guide for more details.
mjpegServerScreenshotQuality¶
| Type | Default |
|---|---|
int |
25 |
The JPEG compression factor applied to the screenshots generated by the MJPEG screenshots
broadcaster, as a percentage. Must be in range 1..100. See the MJPEG guide
for more details.
mjpegScalingFactor¶
| Type | Default |
|---|---|
float |
100 |
The scaling factor of screenshots generated by the MJPEG screenshots broadcaster, as a percentage.
Must be in the range 1..100. See the MJPEG guide for more details.
nativeWebTap¶
| Type | Default |
|---|---|
boolean |
false |
Whether to use native, non-JavaScript-based tap functionality in webview context. Coordinate
translation is calibrated automatically and transparently: the driver fits an empirical
offset/pixel-ratio transform against the current page (see
mobile: calibrateWebToRealCoordinatesTranslation
for details) and refits it whenever the orientation, viewport size, or scroll position changes.
This setting has no effect once a
mobile: startAutomationSession is active -
clicks are then dispatched as real WebKit touch interactions against the element's own on-page
position, bypassing the native-tap/coordinate-calibration path entirely.
This property can also be set using the appium:nativeWebTap capability.
nativeWebTapStrict¶
| Type | Default |
|---|---|
boolean |
false |
Whether to skip the additional logic that tries to match webview elements to native ones before falling back to coordinate-based tapping. Depending on the actual webview content, this element-matching step might sometimes fail, which slows down the click since the driver then falls back to the coordinate transformation flow anyway.
It is advised to use this setting with the mobile: calibrateWebToRealCoordinatesTranslation
execute method.
This setting only has an effect if the nativeWebTap setting is set to true,
which itself has no effect once a
mobile: startAutomationSession is active.
This property can also be set using the appium:nativeWebTapStrict capability.
pageSourceExcludedAttributes¶
| Type | Default |
|---|---|
string |
"" |
One or more comma-separated attribute names to be excluded from the
application source. Excluding certain expensive attributes (e.g. visible) may speed up page
source retrieval.
If used in combination with useJSONSource, only frame, nativeFrame,
enabled, visible, accessible, nativeAccessibilityElement, focused, traits,
placeholderValue, minValue, maxValue and customActions (WebDriverAgent 16.17.6+)
attributes can be excluded.
reduceMotion¶
| Type | Default |
|---|---|
boolean |
false |
Changes the system-wide "Reduce Motion" option (Settings -> Accessibility -> Motion).
respectSystemAlerts¶
| Type | Default |
|---|---|
boolean |
false |
Whether to automatically switch the active application to the system application (SpringBoard on iOS or PineBoard on tvOS) if a native alert element is detected. Decreases the performance of the active app detection.
Currently the driver sets the app under test as active if XCTest identifies it as running in foreground. The presence of a native alert element does not change the value returned by XCTest, which results in the driver being blocked from interacting with the app. Changing this setting can avoid such issues.
screenshotOrientation¶
| Type | Default |
|---|---|
string |
auto |
Overriden value for the screenshot orientation. Appium tries to return a screenshot and adjust its orientation properly using internal heuristics, but sometimes it does not work, especially in landscape mode. The actual screenshot orientation depends on various factors such as OS versions, model versions and whether this is a real or simulator device.
The supported values are auto, portrait, portraitUpsideDown, landscapeRight, and
landscapeLeft.
screenshotQuality¶
| Type | Default |
|---|---|
int |
3 |
The quality of display screenshots. This value affects the screenshoting speed and the actual quality of resulting screenshots.
The supported values are:
0- lossless PNG1- high-quality JPEG2- low-quality JPEG3- lossless HEIC (fallbacks to PNG if hardware HEIC encoding is not supported)
This property can also be set using the appium:screenshotQuality capability.
shouldUseCompactResponses¶
| Type | Default |
|---|---|
boolean |
true |
Setting this to false will cause the findElement response to include the attributes specified
by the elementResponseAttributes setting.
skipDocumentsContainerCheck¶
| Type | Default |
|---|---|
boolean |
false |
Whether to treat documents container type during file management operations (pushing/pulling
to/from real devices) the same as other container types. For certain applications, having this
setting enabled helps to workaround documents upload issues if the UIFileSharingEnabled flag is
not active in the application manifest.
snapshotMaxChildren¶
| Type | Default |
|---|---|
int |
INT_MAX (effectively unlimited) |
The maximum retrieved number of children for each element of the application source tree. Lower values can help speed up source retrieval and prevent out of memory or timeout errors.
snapshotMaxDepth¶
| Type | Default |
|---|---|
int |
50 |
The maximum retrieved depth of the application source tree. Lower values can help speed up source
retrieval and prevent out of memory or timeout errors. Must be in range 1..62 (higher values are not
supported by XCTest).
Consider reducing this value in case of errors like Timed out snapshotting com.apple.testmanagerd... or Cannot get 'xml' source of the current application in your Appium log.
useClearTextShortcut¶
| Type | Default |
|---|---|
boolean |
true |
Whether to use the IOHIDEvent operation for clearing text fields. Disabling this setting may be useful for simulators in headless mode, as the simulator keyboard may otherwise no longer appear (see this issue for more details).
useFirstMatch¶
| Type | Default |
|---|---|
boolean |
false |
Enabling this setting can speed up lookup of single element, though nested element lookups may be subject to a known issue.
useJSONSource¶
| Type | Default |
|---|---|
boolean |
false |
Whether to retrieve the application source from WebDriverAgent in JSON format, and transform it to XML on the Appium server side, as opposed to retrieving the source from WebDriverAgent directly in XML format.
This property can also be set using the appium:useJSONSource capability.
waitForIdleTimeout¶
| Type | Default |
|---|---|
float |
10 |
The amount of time in seconds to wait until the application under test is idling. XCTest requires the app's main thread to be idling in order to execute any action on it, so WebDriverAgent might not even start/freeze if the app under test is constantly hogging the main thread.
Setting this value to 0 disables idling checks completely (not recommended).
This property can also be set using the appium:waitForIdleTimeout capability.
webInspectorSettings¶
| Type | Default |
|---|---|
object |
{} |
Overrides Web Inspector page settings, CSS preferences, and the User-Agent for Safari and inspectable webviews. One policy applies to the session's tracked pages, newly attached targets, and subsequent debugger connections; switching webviews does not require setting it again.
Updates are allowed in NATIVE_APP: before attachment they are validated and saved without
connecting; otherwise they are forwarded to the existing debugger. Native UI settings are unaffected.
getSettings() returns the saved policy, not each webview's effective values or application status.
The optional groups and keys below are case-sensitive. Invalid input returns an invalid argument
error. Each update replaces the entire object: omitted entries restore browser/system defaults,
and {} clears the policy.
| Group | Key | Values and effect |
|---|---|---|
pageSettings |
AuthorAndUserStylesEnabled |
Boolean; enables/disables author and user CSS, leaving browser default styles when disabled. |
pageSettings |
ImagesEnabled |
Boolean; enables/disables image loading. |
pageSettings |
ScriptEnabled |
Boolean; enables/disables page JavaScript. Disabling it can affect JavaScript-based Appium commands. |
pageSettings |
WebSecurityEnabled |
Boolean; false relaxes web security checks, allowing cross-origin iframe automation. |
pageSettings |
MediaCaptureRequiresSecureConnection |
Boolean; requires/relaxes a secure connection for media capture, without granting capture permissions. |
pageSettings |
ICECandidateFilteringEnabled |
Boolean; enables/disables WebRTC ICE candidate filtering. Disabling it may expose additional network addresses. |
userPreferences |
PrefersReducedMotion |
Reduce or NoPreference for the prefers-reduced-motion media query. |
userPreferences |
PrefersContrast |
More or NoPreference for the prefers-contrast media query. |
userPreferences |
PrefersColorScheme |
Light or Dark for the prefers-color-scheme media query. |
userAgent |
— | String overriding the page's User-Agent; does not emulate another browser engine. |
Reload or navigate after document/resource-dependent changes; CSS preferences update immediately. Updates do not reload pages automatically. Device support varies, and a saved policy does not guarantee that every target accepted it.
See the remote debugger's Web Inspector settings guide for input rules, reset and reload semantics, User-Agent interactions, device support, and error recovery.
webScreenshotMode¶
| Type | Default |
|---|---|
string |
native |
The screenshoting logic in web context. The following values are supported:
native- screenshots are taken using WDA and capture the full device screen (including status bars)page- screenshots try to include the entire active web pageviewport- screenshots only include the visible viewport