@appium/mcp-documentation 1.0.2 → 1.0.4

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/settings.md

@@ -0,0 +1,467 @@
+---
+title: Settings
+---
+
+The XCUITest driver exposes various settings through Appium's [Settings API](https://appium.io/docs/en/latest/guides/settings/).
+
+## 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](https://www.w3.org/TR/webdriver2/#accept-alert) API.
+
+The selector should be a valid [class chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules)
+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](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules)
+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`](./capabilities.md) 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`](https://developer.apple.com/documentation/xcuiautomation/xcuielementquery/allelementsboundbyindex),
+as opposed to the default approach using [`allElementsBoundByAccessibilityElement`](https://developer.apple.com/documentation/xcuiautomation/xcuielementquery/allelementsboundbyaccessibilityelement).
+[This Stack Overflow topic](https://stackoverflow.com/questions/49307513/meaning-of-allelementsboundbyaccessibilityelement)
+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](../troubleshooting/element-lookup.md#select-the-correct-active-application)).
+
+## 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](https://www.w3.org/TR/webdriver2/#dismiss-alert) API.
+
+The selector should be a valid [class chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules)
+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`](#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`](https://developer.apple.com/documentation/xcuiautomation/xcuielementsnapshotproviding/snapshot())
+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](https://github.com/appium/WebDriverAgent/issues/1085). 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`](./element-attributes.md#customactions) attribute should be included
+in the page source XML tree.
+
+## includeHittableInPageSource
+
+| Type | Default |
+| -- | -- |
+| `boolean` | `false` |
+
+Whether the [`hittable`](./element-attributes.md#hittable) attribute should be included in the page
+source XML tree.
+
+## includeMinMaxValueInPageSource
+
+| Type | Default |
+| -- | -- |
+| `boolean` | `false` |
+
+Whether the [`minValue`](./element-attributes.md#minvalue) and [`maxValue`](./element-attributes.md#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](../guides/mjpeg.md) 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](../guides/mjpeg.md) 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](../guides/mjpeg.md)
+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](../guides/mjpeg.md) 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`](./capabilities.md) 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`](#nativewebtap) and [`nativeWebTapStrict`](#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-methods.md)
+execute method.
+
+This setting only has an effect if the [`nativeWebTap`](#nativewebtap) setting is set to `true`.
+
+This property can also be set using the [`appium:nativeWebTapStrict`](./capabilities.md) 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`](#nativewebtap) and [`nativeWebTapStrict`](#nativewebtapstrict)
+settings are both set to `true`.
+
+## pageSourceExcludedAttributes
+
+| Type | Default |
+| -- | -- |
+| `string` | `""` |
+
+One or more comma-separated [attribute names](./element-attributes.md) 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`](#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`](#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`](./capabilities.md) capability.
+
+## shouldUseCompactResponses
+
+| Type | Default |
+| -- | -- |
+| `boolean` | `true` |
+
+Setting this to `false` will cause the `findElement` response to include the attributes specified
+by the [`elementResponseAttributes`](#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](https://github.com/appium/appium/issues/20727) 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](https://github.com/appium/appium/issues/10101).
+
+## 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`](./capabilities.md) 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`](./capabilities.md) 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

package/src/resources/submodules/appium-xcuitest-driver/docs/reference/xpath-extensions.md

@@ -0,0 +1,167 @@
+---
+title: XPath Extension Functions
+---
+
+Starting with [WebDriverAgent 13.2.0](https://github.com/appium/WebDriverAgent/releases/tag/v13.2.0)
+([appium/WebDriverAgent#1144](https://github.com/appium/WebDriverAgent/pull/1144)), the XCUITest
+driver's XPath locator strategy supports XPath 2–style **string extension functions** on top of the
+existing XPath 1.0 evaluator. They are evaluated inside WebDriverAgent (libxml2) and work in both
+standalone expressions and predicates inside element queries.
+
+!!! info "XPath 1.0 baseline"
+
+    The underlying engine is still XPath 1.0. Only the functions listed below are added; full XPath
+    2.0 syntax is not supported. See [Locator Strategies](./locator-strategies.md#xpath) for general
+    XPath usage notes and performance guidance.
+
+!!! warning "WebDriverAgent version"
+
+    These functions require WebDriverAgent **13.2.0 or newer**. The driver bundles WDA via the
+    [`appium-webdriveragent`](https://www.npmjs.com/package/appium-webdriveragent) dependency. If you
+    manage WDA yourself (prebuilt, preinstalled, or `appium:webDriverAgentUrl`), ensure the running
+    WDA build includes this release.
+
+## Quick examples
+
+=== "Java"
+
+    ```java
+    // Case-insensitive label match
+    driver.findElement(AppiumBy.xpath(
+        "//XCUIElementTypeButton[matches(@label, '^alerts$', 'i')]"));
+
+    // Case-normalized equality
+    driver.findElement(AppiumBy.xpath(
+        "//XCUIElementTypeButton[lower-case(@label) = 'alerts']"));
+    ```
+
+=== "JavaScript (WebdriverIO)"
+
+    ```javascript
+    await $('//XCUIElementTypeButton[ends-with(@label, "ing")]').click();
+    ```
+
+=== "Python"
+
+    ```python
+    driver.find_element(
+        AppiumBy.XPATH,
+        '//XCUIElementTypeButton[replace(@label, " ", "") = "Deadlockapp"]',
+    )
+    ```
+
+## `matches`
+
+Tests whether a string matches a regular expression.
+
+**Signature:** `matches(input, pattern)` or `matches(input, pattern, flags)`
+
+**Returns:** `boolean`
+
+| Argument | Description |
+| --- | --- |
+| `input` | String to test (often an attribute, e.g. `@label`) |
+| `pattern` | Regular expression ([`NSRegularExpression`](https://developer.apple.com/documentation/foundation/nsregularexpression)) |
+| `flags` | Optional. Supported: `i` (case-insensitive), `m`, `s`, `x` |
+
+```xpath
+//XCUIElementTypeButton[matches(@label, '^Alerts$')]
+//XCUIElementTypeButton[matches(@label, '^alerts$', 'i')]
+```
+
+## `ends-with`
+
+Tests whether a string ends with a given suffix (literal suffix, not a regex).
+
+**Signature:** `ends-with(input, suffix)`
+
+**Returns:** `boolean`
+
+```xpath
+//XCUIElementTypeButton[ends-with(@label, 'ing')]
+```
+
+## `lower-case` / `upper-case`
+
+Convert a string to lowercase or uppercase using the system locale rules.
+
+**Signature:** `lower-case(input)` / `upper-case(input)`
+
+**Returns:** `string`
+
+```xpath
+//XCUIElementTypeButton[lower-case(@label) = 'alerts']
+//XCUIElementTypeButton[upper-case(@label) = 'TOUCH']
+```
+
+## `replace`
+
+Replaces substrings that match a regular expression with a replacement template.
+
+**Signature:** `replace(input, pattern, replacement)` or `replace(input, pattern, replacement, flags)`
+
+**Returns:** `string`
+
+| Argument | Description |
+| --- | --- |
+| `input` | Source string |
+| `pattern` | Regular expression |
+| `replacement` | Replacement template (same semantics as `NSRegularExpression` replacement) |
+| `flags` | Optional. Supported: `i`, `m`, `s`, `x`, `q` |
+
+```xpath
+//XCUIElementTypeButton[replace(@label, ' ', '') = 'Deadlockapp']
+replace(//XCUIElementTypeOther/@value, '-', '_')
+```
+
+## `tokenize` and `string-join`
+
+Split a string into parts and join them with a separator. These are intended to be used together:
+`tokenize` produces an internal token sequence that `string-join` consumes (this avoids temporary
+XML node-sets in the XPath 1.0 engine).
+
+**`tokenize` signature:** `tokenize(input)` or `tokenize(input, pattern)`
+
+**`string-join` signature:** `string-join(sequence, separator)`
+
+**Returns:** `string` (from `string-join`)
+
+| `tokenize` form | Behavior |
+| --- | --- |
+| `tokenize(input)` | Split on whitespace (non-empty tokens) |
+| `tokenize(input, '')` | Split into Unicode extended grapheme clusters |
+| `tokenize(input, pattern)` | Split using the regex `pattern` as delimiter |
+
+```xpath
+string-join(tokenize(//XCUIElementTypeOther/@value, '-'), '|')
+//XCUIElementTypeButton[string-join(tokenize(@label, ' '), '-') = 'Deadlock-app']
+```
+
+## Regular expression flags
+
+| Flag | `matches` | `replace` | Meaning |
+| --- | --- | --- | --- |
+| `i` | yes | yes | Case-insensitive |
+| `m` | yes | yes | Multiline (`^` / `$` match line boundaries) |
+| `s` | yes | yes | Dot matches newlines |
+| `x` | yes | yes | Ignore whitespace in the pattern |
+| `q` | no | yes | Quote metacharacters (literal pattern) |
+
+Invalid flag combinations cause the XPath expression to fail evaluation.
+
+## Error handling
+
+- **Invalid arity** (wrong number of arguments) fails the XPath evaluation.
+- **Invalid regular expressions** or **invalid flags** fail the XPath evaluation.
+- When used for element lookup, failures surface as an invalid XPath error from WebDriverAgent
+  (`FBInvalidXPathException`).
+
+Prefer [predicate string](./ios-predicate.md) or [class chain](./locator-strategies.md#class-chain)
+locators when they can express the same condition; XPath remains the slowest strategy, even with
+these helpers.
+
+## More information
+
+- [WebDriverAgent PR #1144](https://github.com/appium/WebDriverAgent/pull/1144) — implementation and tests
+- [Locator Strategies](./locator-strategies.md) — strategy overview and performance notes
+- [Element Attributes](./element-attributes.md) — attribute names available in XPath (`@label`, `@name`, etc.)