@appium/mcp-documentation 1.0.3 → 1.0.5

package/src/resources/submodules/appium-xcuitest-driver/docs/getting-started/provisioning-profile/generic-device-config.md

@@ -0,0 +1,75 @@
+---
+hide:
+  - toc
+
+title: Manual Configuration for a Generic Device
+---
+
+It is possible to build `WebDriverAgentRunner` for a generic iOS/iPadOS/tvOS device, and install the
+generated `.app` package to a real device.
+
+```bash
+# iOS/iPadOS
+$ xcodebuild clean build-for-testing -project WebDriverAgent.xcodeproj -derivedDataPath appium_wda_ios -scheme WebDriverAgentRunner -destination generic/platform=iOS CODE_SIGNING_ALLOWED=YES
+
+# tvOS
+$ xcodebuild clean build-for-testing -project WebDriverAgent.xcodeproj -derivedDataPath appium_wda_tvos -scheme WebDriverAgentRunner_tvOS -destination generic/platform=tvOS CODE_SIGNING_ALLOWED=YES
+```
+
+On successful completion the resulting package `WebDriverAgentRunner-Runner.app` should be located
+in the `Build/Products/Debug-iphoneos/` subfolder under WebDriverAgent sources root, or in the path
+provided as `derivedDataPath` argument.
+
+!!! note
+
+    If the build fails, please make sure `WebDriverAgent.xcodeproj` has codesigning properties
+    configured properly. For example, you may need to change the bundle id for the provisioning profile.
+
+The `WebDriverAgentRunner-Runner.app` can now be installed to any real device as allowed by the
+provisioning profile.
+
+You can install the package with 3rd party tools and manage it separately as explained in
+[How To Set Up And Customize WebDriverAgent Server](../../guides/wda-custom-server.md). Note that if
+the codesigning was not correct, the installation will fail.
+
+As a more advanced method, you can generate the package with `CODE_SIGNING_ALLOWED=NO` and do
+[`codesign`](https://developer.apple.com/documentation/xcode/using-the-latest-code-signature-format)
+by yourself. This would make the device management more flexible, but you would need to know about
+advanced codesign usage scenarios.
+
+The Appium team distributes generic builds with `CODE_SIGNING_ALLOWED=NO` at
+[WebDriverAgent package releases](https://github.com/appium/WebDriverAgent/releases).
+It is recommended to sign packages with a wildcard (`*`) provisioning profile,
+although such profiles require a paid Apple Developer account.
+For example, if you're preparing such a provisioning profile for `io.appium.WebDriverAgentRunner.xctrunner`, it will be for `io.appium.*`, `io.appium.WebDriverAgentRunner.*` or `*`.
+
+In case of a free account or paid account without `*` provisioning profile,
+you may need to update the bundle id before building so `xcodebuild` can produce
+a properly signed WebDriverAgent package. Another option is to re-sign an existing
+package and remap its bundle ids with 3rd party tools such as [resigner](https://github.com/appium/resigner).
+The tool can remap the bundle ids to values allowed by the free provisioning profile and
+then sign the package with that profile.
+
+Please check the tool's readme for details, but in short, you can use the following command to
+re-sign the package with bundle id remapping:
+
+```
+P12_PASSWORD="<password of p12>" resigner \
+  --p12-file "<path to p12 file>" \
+  --profile "<path to provisioning profiles>" \
+  --force \
+  --bundle-id-remap "com.facebook.WebDriverAgentRunner=<valid bundle id for the profile>" \
+  --bundle-id-remap "com.facebook.WebDriverAgentRunner.xctrunner=<valid bundle id for the profile>" \
+  --bundle-id-remap "com.facebook.WebDriverAgentLib=<valid bundle id for the profile>" \
+  /path/to/WebDriverAgentRunner-Runner.app
+```
+
+Or
+
+```
+P12_PASSWORD="<password of p12>" appium driver run xcuitest sign-wda -- \
+  --wda-path=<path> \
+  --p12-file=<path> \
+  --profile-dir=<path to provisioning profiles> \
+  --bundle-id=<valid bundle id for the profile>
+```

package/src/resources/submodules/appium-xcuitest-driver/docs/getting-started/provisioning-profile/index.md

@@ -0,0 +1,117 @@
+---
+title: Provisioning Profile
+---
+
+The XCUITest driver communicates with the device under test through the
+`WebDriverAgentRunner-Runner` (WDA) helper application, which the driver can automatically build and
+install on the device. For real devices, Apple requires all apps to have a valid provisioning
+profile before they can be installed, which means that the WDA app must first be signed and linked
+to a development team. This guide describes how to accomplish this.
+
+## Apple Account
+
+A key prerequisite for signing WDA is ^^an Apple Account^^. Free and paid accounts are both
+supported. Note that there are two cases where you may not need an account:
+
+* Your device already [already has WDA installed](../../guides/run-preinstalled-wda.md)
+* You already have [a prebuilt WDA](../../guides/run-prebuilt-wda.md) on your local system
+
+Once you have an Apple Account, there are several approaches you can take.
+
+## Automatic Configuration
+
+The automatic configuration approach allows creating a provisioning profile without the need to
+configure WDA itself. However, ^^it is only supported for paid Apple Developer accounts^^.
+
+> Read the full guide: [Automatic Provisioning Profile Configuration](./auto-config.md)
+
+## Manual Configuration
+
+Free Apple Accounts are still able to sign WDA and link it to their default personal team. There
+are several ways of doing this, but all of them involve working with the WDA application, or more
+specifically, its Xcode project, which is installed alongside the XCUITest driver.
+
+The driver includes a convenience script to automatically open the WDA project in Xcode:
+```
+appium driver run xcuitest open-wda
+```
+
+The script will also print the full path to the project file, which you may want to use in later
+steps. The project file is located in the XCUITest driver install directory:
+```
+<path/to/xcuitest/driver>/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj
+```
+
+Once Xcode is open, make sure to add your Apple Account in the settings:
+ > _Xcode_ -> _Settings_ -> _Apple Accounts_ -> _Add Apple Account..._
+
+Now you can configure the WDA project using one of the manual configuration approaches:
+
+* Basic configuration: create a new project, then use its provisioning profile and bundle ID
+
+    > Read the full guide: [Basic Manual Provisioning Profile Configuration](./basic-manual-config.md)
+
+* Full configuration: associate the provisioning profile directly with the WDA project
+
+    > Read the full guide: [Full Manual Provisioning Profile Configuration](./full-manual-config.md)
+
+* Generic device configuration: manually run `xcodebuild` to build WDA, then manually install it
+
+    > Read the full guide: [Manual Provisioning Profile Configuration for a Generic Device](./generic-device-config.md)
+
+## Common Issues
+
+At this point you should have either tried to start a session with provisioning profile-related
+capabilities (for automatic config), or tried to build and install WDA through Xcode (for manual
+config). If this did not succeed, you likely have one of the following problems. For issues not
+listed here, please refer to the [Troubleshooting](../../troubleshooting/index.md) page.
+
+### xcodebuild exited with code 65
+
+  This can happen during automatic configuration, or when a manually configured provisioning profile
+  is revoked (for example, due to expiration). It means that code signing is not set up correctly and
+  must be reconfigured. Follow the steps in any of the manual configuration approaches to fix this.
+
+  The [appium:allowProvisioningDeviceRegistration](../../reference/capabilities.md) capability
+  enables automatic device registration with the specified account and works for both paid and free accounts.
+
+### xcodebuild exited with code 70
+
+  Similarly to the error for code 65, this error can be caused by invalid code signing, but may
+  also be returned in case of invalid `xcodebuild` configuration (for example, wrong platform
+  version). To fix this, check if code signing is set up properly, and verify that any custom build
+  parameters have valid values.
+
+### Developer App Certificate is not trusted
+
+  This error can appear in Xcode when building WDA during manual configuration with a free Apple
+  Account. A similar error will also appear if you manually try to open the WDA app on the device:
+
+  ![Untrusted developer](./assets/images/untrusted-dev.png)
+
+  You can fix this by allowing your device to accept apps from your personal development team.
+  Note that this requires the device to have an internet connection.
+  
+  1. On the device, open _Settings_ -> _General_ -> _VPN & Device Management_
+  2. You should see a new _Developer App_ section, listing the Apple Account email used to build WDA. Select it.
+  3. Tap _Trust {email}_ -> _Allow_
+
+  You can find additional information in the related [Apple documentation guide](https://support.apple.com/en-us/118254).
+
+## Offline Provisioning Profile
+
+Since iOS 16, Apple requires a device to have a live internet connection for validating the code
+signing. It is possible to set up an offline enabled provisioning profile, which allows you to avoid
+the limitation, although such profiles are only valid for up to 7 days. Please read
+[this issue](https://github.com/appium/appium/issues/18378#issuecomment-1482678074) regarding
+detailed configuration steps.
+
+## Improve WebDriverAgent Startup Performance
+
+Building WDA upon every session startup may add up to a significant amount of time. The driver
+offers a few methods to speed this up, with or without using `xcodebuild`. Some approaches may
+require a deeper understanding of the iOS development environment.
+
+- [Run Preinstalled WebDriverAgentRunner](../../guides/run-preinstalled-wda.md)
+- [Run Prebuilt WebDriverAgentRunner](../../guides/run-prebuilt-wda.md)
+- [Attach to a Running WebDriverAgent](../../guides/attach-to-running-wda.md)

package/src/resources/submodules/appium-xcuitest-driver/docs/getting-started/system-requirements.md

@@ -0,0 +1,131 @@
+---
+title: System Requirements
+---
+
+There are three primary requirements to use the XCUITest driver:
+
+* macOS host machine
+* Xcode
+* Appium
+
+For most use cases, the latest versions of the above will work just fine.
+
+However, if you want to automate devices with an older iOS/iPadOS/tvOS version, ^^you may also be
+required to use older versions of all three of the above^^. Use the following compatibility tables
+to help identify your target Xcode, macOS, driver and Appium server versions.
+
+!!! note
+
+    This document only lists compatibility information starting from iOS/tvOS 9.3 and Xcode 11, as
+    these were the minimum supported versions in XCUITest driver 4.0.0, which was the first
+    version supporting Appium 2. For iOS/tvOS/Xcode support in driver versions older than 4.0.0
+    (Appium 1), please refer to [the Appium 1 changelog](https://github.com/appium/appium/blob/1.x/CHANGELOG.md).
+
+!!! note
+
+    If you already have the driver installed, you can also verify its requirements with the
+    built-in Appium Doctor support:
+
+    ```
+    appium driver doctor xcuitest
+    ```
+
+## Xcode and macOS
+
+Apple provides a list of Xcode versions and their minimum supported iOS/iPadOS/tvOS and macOS
+versions in the [Xcode Release Notes](https://developer.apple.com/documentation/xcode-release-notes/).
+However, _maximum_ supported versions are also enforced, but are not explicitly listed.
+
+The aforementioned release notes do allow identifying the upper version limits for iOS/iPadOS/tvOS,
+but for macOS, it can generally be assumed that if a major Xcode version requires at least macOS
+version `X`, then it will no longer run on macOS version `X+2`. [^xcode-macos]
+
+The following table shows a simplified mapping between iOS/iPadOS/tvOS, Xcode, and macOS versions,
+narrowed for XCUITest driver compatibility:
+
+| iOS/iPadOS/tvOS version | Supported Xcode versions (driver-adjusted) | Supported macOS versions |
+| --- | --- | -- |
+| 26 | Xcode >= 26 | macOS >= 15.6 |
+| 18 | Xcode >= 16 | macOS >= 14.3 |
+| 17 | Xcode >= 15 | macOS >= 13.3 |
+| 16 | Xcode >= 14 | macOS >= 12.5 |
+| 15 | Xcode >= 13 | macOS >= 11.3 |
+| 14 | Xcode 12 - 15 (except 13.3 - 13.4.1) | macOS 10.15.4 - 14 |
+| 13 | Xcode 11 - 15 (except 13.3 - 13.4.1) | macOS 10.14.4 - 14 |
+| 12 | Xcode 11 - 15 (except 13.3 - 13.4.1) | macOS 10.14.4 - 14 |
+| 11 | Xcode 11 - 14 (except 13.3 - 13.4.1) | macOS 10.14.4 - 13 |
+| 10 | Xcode 11 - 13.2.1 | macOS 10.14.4 - 12 |
+| 9.3 | Xcode 11 - 13.2.1 | macOS 10.14.4 - 12 |
+
+## Driver Version
+
+The XCUITest driver aims to _fully support_ the latest _two_ (2) major Xcode/iOS/iPadOS/tvOS
+versions, but _may_ still fully or partially work with certain older versions.
+
+??? info "Why not support all OS and Xcode versions?"
+
+    The XCUITest driver depends on the [WebDriverAgent (WDA)](https://github.com/appium/WebDriverAgent)
+    framework, which in turn [relies on Apple's XCTest framework](../overview.md). Changes in the
+    XCTest API are published in new Xcode and Apple device OS versions. These API changes may not
+    only add new features that the driver must implement in order to support the latest devices, but
+    also modify or even remove support for existing features that the driver relies on.
+
+The following tables map Xcode/OS versions to their supported driver versions. Versions with the
+'not tested' label are still likely to work fine with the latest driver, but any fixes for them will
+have lesser priority than for newer Xcode/OS versions, and any major workarounds are unlikely.
+
+If you are downgrading an existing driver installation to adjust its Xcode/OS support range, ensure that
+the version of the [WebDriverAgent (WDA)](https://github.com/appium/WebDriverAgent) server
+application (which the driver installs on the device under test) is also downgraded accordingly.
+
+| iOS/iPadOS/tvOS version | Fully supported driver/WDA versions | Last likely working driver/WDA version |
+| --- | --- | --- |
+| >= 26.4 | >= [10.23.2](https://github.com/appium/appium-xcuitest-driver/pull/2733) (WDA >= 11.1.5) | Latest |
+| 26.0 - 26.3 | >= 9.5.0 (WDA >= [9.14.1](https://github.com/appium/WebDriverAgent/pull/1032)) | Latest |
+| 18.0 - 18.7 | >= 7.24.15 (WDA >= [8.9.1](https://github.com/appium/WebDriverAgent/pull/935)) | Latest |
+| 17.0 - 17.7 | [4.32.23](https://github.com/appium/appium-xcuitest-driver/pull/1822) - 10.1.0 (WDA 5.6.0 - 10.1.0) | Latest (not tested) |
+| 16.4 - 16.7 | 4.21.7 - 7.26.3 (WDA [4.13.1](https://github.com/appium/WebDriverAgent/pull/681) - 8.9.1) | Latest (not tested) |
+| 16.0 - 16.3 | 4.7.4 - 7.26.3 (WDA [4.8.1](https://github.com/appium/WebDriverAgent/pull/597) - 8.9.1) | Latest (not tested) |
+| 15.0 - 15.8 | 4.0.0 - 5.2.0 (WDA 4.0.0 - 5.8.5) | Latest (not tested) |
+| 14.0 - 14.8 | 4.0.0 - 4.11.1 (WDA 4.0.0 - 4.8.5) | 4.27.2 (WDA [4.15.1](https://github.com/appium/WebDriverAgent/pull/696)) |
+| 9.3 - 13.7 | < 4.0.0 | 4.27.2 (WDA [4.15.1](https://github.com/appium/WebDriverAgent/pull/696)) |
+
+| Xcode version | Fully supported driver/WDA versions | Last likely working driver/WDA version |
+| --- | --- | --- |
+| Xcode >= 26.0 | >= 9.5.0 (WDA >= [9.14.1](https://github.com/appium/WebDriverAgent/pull/1032)) | Latest |
+| Xcode 16.0 - 16.4 | >= 7.24.15 (WDA >= [8.9.1](https://github.com/appium/WebDriverAgent/pull/935)) | Latest |
+| Xcode 15.0 - 15.4 | [4.32.23](https://github.com/appium/appium-xcuitest-driver/pull/1822) - 10.1.0 (WDA 5.6.0 - 10.1.0) | Latest (not tested) |
+| Xcode 14.3 | 4.21.7 - 7.26.3 (WDA [4.13.1](https://github.com/appium/WebDriverAgent/pull/681) - 8.9.1) | Latest (not tested) |
+| Xcode 14.0 - 14.2 | 4.7.4 - 7.26.3 (WDA [4.8.1](https://github.com/appium/WebDriverAgent/pull/597) - 8.9.1) | Latest (not tested) |
+| Xcode 13.3 - 13.4 | 4.3.3 - 5.2.0 (WDA [4.1.6](https://github.com/appium/WebDriverAgent/pull/573) - 5.8.5) | [10.6.0](https://github.com/appium/appium-xcuitest-driver/pull/2658) (WDA 10.2.2) |
+| Xcode 13.0 - 13.2 | 4.0.0 - 5.2.0 (WDA 4.0.0 - 5.8.5) | [10.6.0](https://github.com/appium/appium-xcuitest-driver/pull/2658) (WDA 10.2.2) |
+| Xcode 12.0 - 12.5 | 4.0.0 - 4.11.1 (WDA 4.0.0 - 4.8.5) | 4.27.2 (WDA [4.15.1](https://github.com/appium/WebDriverAgent/pull/696)) |
+| Xcode 11.0 - 11.7 | < 4.0.0 | 4.2.0 (WDA [4.0.0](https://github.com/appium/WebDriverAgent/pull/557)) |
+
+## Appium Server
+
+Make sure to install a version of Appium that supports your target driver version. The requirements
+and prerequisites of Appium itself can be found in [the Appium documentation](https://appium.io/docs/en/latest/quickstart/install/).
+
+| XCUITest driver version | Supported Appium server version |
+| --- | --- |
+| >= 10.0.0 | Appium 3 |
+| 4.0.0 - 9.10.5 | Appium 2 |
+
+## Other Requirements
+
+- If automating real devices, additional manual configuration is required - please refer to the
+  [Real Device Setup](./device-setup.md#real-devices) guide.
+- If testing web or hybrid apps, their webviews must be debuggable. If it is not possible to connect to your
+  webview(s) using [Safari remote debugger](https://appletoolbox.com/use-web-inspector-debug-mobile-safari/),
+  then the driver will not be able to identify them.
+
+### Optional Requirements
+
+- [`ffmpeg`](https://ffmpeg.org/) is used for test video recording. It can be installed using
+  [`brew`](https://brew.sh/): `brew install ffmpeg`
+- [`go-ios`](https://github.com/danielpaulus/go-ios) can be used to improve device interactions
+- [WIX AppleSimulatorUtils](https://github.com/wix/AppleSimulatorUtils) can be used to improve some
+  Simulator interactions
+
+[^xcode-macos]: Refer to this [StackOverflow post](https://stackoverflow.com/questions/78996419/xcode-15-is-not-running-in-macos-sequoia)

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/attach-to-running-wda.md

@@ -0,0 +1,43 @@
+---
+hide:
+  - toc
+
+title: Attach to a Running WDA
+---
+
+The XCUITest driver provides the __`appium:webDriverAgentUrl`__ capability to attach to a running
+WebDriverAgent (WDA) application. This works for real devices and simulators, but the primary usage
+is for real devices.
+
+## Usage
+
+1. Start a WebDriverAgent application on a device
+2. Start an XCUITest driver session with `appium:webDriverAgentUrl` capability
+
+Please read [Manage WebDriverAgent by Yourself](./wda-custom-server.md) and
+[Real Device Setup](../getting-started/device-setup.md#real-devices) about how to prepare WDA for a
+real device.
+
+The `appium:webDriverAgentUrl` value should be the WDA URL: `http://<reachable ip address for the device>:8100`.
+If the environment has port-forward to the connected device, it can be `http://localhost:8100`.
+
+```json
+{
+  "platformName": "ios",
+  "appium:automationName": "xcuitest",
+  "appium:platformVersion": "15.5",
+  "appium:udid": "<device udid>",
+  "appium:deviceName": "iPhone",
+  "appium:webDriverAgentUrl": "http://<reachable ip address for the device>:8100"
+}
+```
+
+This method allows you to manage the WDA process by yourself. The XCUITest driver then simply
+attaches to the WDA process, which may improve the application performance.
+
+Some XCUITest driver APIs (for example,
+[mobile: calibrateWebToRealCoordinatesTranslation](../reference/execute-methods.md#mobile-calibratewebtorealcoordinatestranslation))
+might still require the port number of the remote device if it is a real device. Providing the
+`appium:webDriverAgentUrl` capability might not be sufficient to recognize the remote port number,
+in case it is different from the local one. Consider settings the `appium:wdaRemotePort` capability
+in such cases, to supply the driver with the appropriate data.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/audio-capture.md

@@ -0,0 +1,78 @@
+---
+title: Audio Capture
+---
+
+
+Appium XCUITest driver provides a possibility to record iOS audio stream and save it to a file,
+which could be then retrieved on the client side. Apple does not provide any API to directly
+retrieve the audio stream from a Simulator or a real device, but it is possible to redirect that
+stream to the host machine, where it could be captured.
+
+* [`mobile: startAudioRecording`](../reference/execute-methods.md#mobile-startaudiorecording)
+* [`mobile: stopAudioRecording`](../reference//execute-methods.md#mobile-stopaudiorecording)
+
+## Server Requirements
+
+- The host machine must have [`ffmpeg`](https://www.ffmpeg.org/download.html) installed and added to PATH.
+  It can be installed via [`brew`](https://brew.sh/): `brew install ffmpeg`.
+- For macOS 10.15+, applications recording Microphone audio need to be explicitly granted this permission.
+  This can be done in the following settings menu:
+
+    - macOS < 13: _System Preferences -> Security & Privacy -> Privacy -> Microphone_
+    - macOS 13+: _System Settings -> Privacy & Security -> Microphone_
+
+    Ensure that either `ffmpeg` itself or the parent Appium process (e.g. Terminal) is present in that list.
+
+- As this is a potentially insecure feature, it must be explicitly allowed on the server side. See
+  [the Appium documentation on Security](https://appium.io/docs/en/latest/guides/security/) for more details.
+  The feature name is `audio_record`.
+
+## Simulator Setup
+
+The following steps are necessary to setup iOS Simulator audio capture:
+
+* Install [Soundflower](https://github.com/mattingalls/Soundflower/releases)
+* Redirect Simulator audio output to Soundflower: from the main Simulator menu, select
+  _I/O -> Audio Output -> Soundflower (2ch)_
+* In terminal, run `ffmpeg -f avfoundation -list_devices true -i ""` to get the identifier of the
+  `Soundflower (2ch)` device. This identifier prefixed with `:` will be then used as `audioInput`
+  argument to `mobile: startAudioRecording` call
+* Test that your setup works as expected. Run any audio playback in Simulator and execute the
+  following command in Terminal, replacing the `-i` argument value with the one you got from the
+  previous step:
+  ```
+  ffmpeg -t 5 -f avfoundation -i ":1" -c:a aac -b:a 128k -ac 2 -ar 44100 -y ~/Desktop/out.mp4
+  ```
+  After 5 seconds, a file named `out.mp4` should be created on your desktop, containing the recorded
+  audio stream.
+
+## Real Device Setup
+
+The following steps are necessary to setup iOS Real Device audio capture:
+
+* Connect your device to the Mac host with a cable
+* Open the _Audio MIDI Setup_ application
+    * Via Finder: _Applications -> Utilities -> Audio MIDI Setup_
+    * Via terminal: `open -a /System/Applications/Utilities/Audio\ MIDI\ Setup.app`
+* Find your phone in the list of devices there and click `Enable` next to it
+* In terminal, run `ffmpeg -f avfoundation -list_devices true -i ""` to get the identifier of your
+  device in the `AVFoundation audio devices` list. This identifier prefixed with `:` will be then
+  used as `audioInput` argument to `mobile: startAudioRecording` call
+* Test that your setup works as expected. Run any audio playback on the device and execute the
+  following command in Terminal, replacing the `-i` argument value with the value you got from the
+  previous step:
+  ```
+  ffmpeg -t 5 -f avfoundation -i ":1" -c:a aac -b:a 128k -ac 2 -ar 44100 -y ~/Desktop/out.mp4
+  ```
+  After 5 seconds, a file named `out.mp4` should be created on your desktop, containing the recorded
+  audio stream.
+
+!!! note
+
+    Apple does not allow phone calls to be redirected this way. You can only record application or system sounds.
+
+## Further Reading
+
+* <https://github.com/appium/appium-xcuitest-driver/pull/1207>
+* <https://www.macobserver.com/tips/quick-tip/iphone-audio-input-mac/>
+* <http://www.lorisware.com/blog/2012/04/28/recording-iphone-emulator-video-with-sound/>

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/biometric-auth.md

@@ -0,0 +1,29 @@
+---
+hide:
+  - toc
+
+title: Biometric Authentication
+---
+
+The XCUITest driver has the capability to simulate biometric authentication, such as
+[Touch ID](https://support.apple.com/en-us/102528) and [Face ID](https://support.apple.com/en-us/108411).
+
+!!! note
+
+    This functionality is only supported on simulators that support either Touch ID or Face ID.
+
+The driver provides the following execute methods for managing biometric authentication:
+
+* [`mobile: enrollBiometric`](../reference/execute-methods.md#mobile-enrollbiometric)
+* [`mobile: sendBiometricMatch`](../reference/execute-methods.md#mobile-sendbiometricmatch)
+* [`mobile: isBiometricEnrolled`](../reference/execute-methods.md#mobile-isbiometricenrolled)
+
+Basic use case:
+
+1. Call `mobile: enrollBiometric`
+    * By default, this enrolls the device
+    * Set `isEnabled` to `false` to unenroll
+2. Call `mobile: sendBiometricMatch`
+    * By default, this simulates a Touch ID match
+    * Set `type` to either `touchId` or `faceId`, depending on your device
+    * Set `match` to `true` or `false` to trigger a match or non-match, respectively

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/capability-sets.md

@@ -0,0 +1,169 @@
+---
+title: Capability Set Examples
+---
+
+This article describes necessary capabilities that must be provided in order
+to implement some common automation testing scenarios.
+It only describes very minimum sets of capabilities required to
+be included. For refined setups more of them might need to be provided. Check the
+[Capabilities](../reference/capabilities.md) article for more details
+on each option available for the fine-tuning of XCUITest driver sessions.
+
+### Application File (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+  "appium:app": "/path/to/local/package.ipa"
+}
+```
+
+`appium:app` could also be a remote app or an archive:
+
+```
+  "appium:app": "https://example.com/package.ipa"
+  "appium:app": "https://example.com/package.zip"
+```
+
+`appium:udid` could also be set to `auto` in order to select the first matched device
+connected to the host (or a single one if only one is connected):
+
+```
+  "appium:udid": "auto"
+```
+
+### Application File (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:app": "/path/to/local/package.app"
+}
+```
+
+`appium:app` could also be an archive:
+
+```
+  "appium:app": "https://example.com/package.zip"
+  "appium:app": "/path/to/local/package.zip"
+```
+
+### Safari (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "browserName": "Safari",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>"
+}
+```
+
+You may also provide `appium:safariInitialUrl` capability value to navigate
+to the desired page during the session startup:
+
+```
+  "appium:safariInitialUrl": "https://server.com/page"
+```
+
+### Safari (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "browserName": "Safari",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>"
+}
+```
+
+### Pre-Installed App (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+  "appium:bundleId": "<Bundle_ID_Of_Preinstalled_App>",
+  "appium:noReset": true
+}
+```
+
+The `appium:noReset` capability is set to `true` in order to tell the driver
+the app identified by `appium:bundleId` is already preinstalled and must not be reset.
+
+### Pre-Installed App (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:bundleId": "<Bundle_ID_Of_Preinstalled_App>",
+  "appium:noReset": true
+}
+```
+
+### Deeplink (Real Device running iOS 17+)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+  "appium:initialDeeplinkUrl": "<Deeplink_Url>"
+}
+```
+
+### Deeplink (Simulator running iOS 17+)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:initialDeeplinkUrl": "<Deeplink_Url>"
+}
+```
+
+### Custom Launch (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+}
+```
+
+This will start your test at the Home screen.
+Afterwards you may use any of the application management
+methods, like [mobile: installApp](../reference//execute-methods.md#mobile-installapp)
+or [mobile: activateApp](../reference//execute-methods.md#mobile-activateapp)
+to manage the life cycle of your app or switch between contexts to
+manage web pages. Check the full list of
+[mobile: execute methods](../reference/execute-methods.md) for more details.
+
+### Custom Launch (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>"
+}
+```