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.

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.

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

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.

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

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.

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. Warning: sometimes the preciseness of native taps could be broken, because there is no reliable way to map web element coordinates to native ones.

This property can also be set using the appium:nativeWebTap capability.

nativeWebTapSmartAppBannerVisibility

Type	Default
string	detect

The visibility state of the smart app banner. Setting this value may speed up tap actions in webview context. Supported values are detect, visible, and invisible.

This setting only has an effect if the nativeWebTap and nativeWebTapStrict settings are both set to true.

nativeWebTapStrict

Type	Default
boolean	false

Whether to skip additional logic that tries to match webview elements to native ones by using their textual descriptions. Depending on the actual webview content, this algorithm might sometimes be not very reliable, and may slow down each click, since a failure would cause the driver to fallback to the default coordinates transformation flow.

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.

This property can also be set using the appium:nativeWebTapStrict capability.

nativeWebTapTabBarVisibility

Type	Default
string	detect

The visibility state of the browser tab bar. Setting this value may speed up tap actions in webview context. Supported values are detect, visible, and invisible.

This setting only has an effect if the nativeWebTap and nativeWebTapStrict settings are both set to true.

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, enabled, visible, accessible and focused attributes are supported.

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

safariTabBarPosition

Type	Default
string	bottom for iPhones on iOS 15+, otherwise top

The tab bar position in Safari. Supported values are bottom and top.

This setting only has an effect if the nativeWebTap setting is set to true.

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 PNG
• 1 - high-quality JPEG
• 2 - low-quality JPEG
• 3 - 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.

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 page
• viewport - screenshots only include the visible viewport