@appium/mcp-documentation 1.0.2 → 1.0.4

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/parallel-tests.md

@@ -0,0 +1,39 @@
+---
+hide:
+  - toc
+
+title: Running Tests in Parallel
+---
+
+It is possible to execute tests in parallel using XCUITest driver. Appium allows to do this on a
+per-process (multiple server processes running on different ports managing single session) or a
+per-request basis (single server process managing multiple sessions, more preferable, uses less
+resources and ensures better control over running sessions).
+
+!!! note
+
+    If you are _not_ going to run your tests in parallel, consider enabling the `--session-override`
+    Appium server argument. It forces the server to close all pending sessions before a new one
+    could be opened, which allows you to avoid possible issues with such sessions silently
+    running/expiring in the background.
+
+### Important Real Device Capabilities
+
+- `udid` must be a unique device UDID for each parallel session.
+- `wdaLocalPort` must be a unique port number for each parallel session. The default value is `8100`.
+- `derivedDataPath` set the unique derived data path root for each driver instance. This will help
+  to avoid possible conflicts and to speed up the parallel execution.
+- `mjpegServerPort` must be a unique port number for each parallel session if you are going to
+  record a video stream from it. The default value is `9100`.
+
+### Important Simulator Capabilities
+
+- Either `udid`, which is the unique simulator UDID for each parallel session (it could be retrieved
+  from `xcrun simctl list` command output), or a unique combination of `deviceName` and
+  `platformVersion` capabilities to identify the appropriate simulator with the given name and
+  version number for each parallel session.
+- `wdaLocalPort` must be a unique port number for each parallel session. The default value is `8100`.
+- `derivedDataPath` set the unique derived data path root for each driver instance. This will help
+  to avoid possible conflicts and to speed up the parallel execution.
+- `mjpegServerPort` must be a unique port number for each parallel session if you are going to
+  record a video stream from it. The default value is `9100`.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/remotexpc-tunnels-real-devices.md

@@ -0,0 +1,148 @@
+---
+title: Remote XPC Tunnels
+---
+
+Certain features of the XCUITest driver rely on Remote XPC services and IPv6 tunneling. This
+functionality is provided by the optional [`appium-ios-remotexpc`](https://github.com/appium/appium-ios-remotexpc/)
+library.
+
+!!! info
+
+    The driver only uses remote XPC tunnels for ^^real devices running iOS/tvOS 18 or later^^.
+    Real devices running iOS/tvOS < 18 do not support this tunneling mechanism, whereas
+    simulators do not need to use it.
+
+## Why Use Remote XPC
+
+On iOS/tvOS 18+, Apple routes many system services (including XCTest-related ones) over IPv6-only
+interfaces and Remote XPC endpoints. The XCUITest driver utilizes them for the following features
+(non-exhaustive list):
+
+- General communication with wireless Apple TV devices
+- Retrieval of various logs
+- Network monitoring
+- Certificate management
+- Execution of native XCTest test suites
+
+## Prerequisites
+
+- macOS or Linux host
+- Real device running iOS/tvOS 18 or later, paired and trusted on its host
+    - The driver supports devices connected via `usbmuxd` (wired and wireless), as well as
+      wireless tvOS devices (must be paired first, [see tvOS guide](./tvos.md#wireless-tvos-18-or-later))
+- `appium-ios-remotexpc` installed
+    - The driver declares this package as an **optional dependency**, so in a normal
+      installation npm will install it automatically. You only need to install it manually if
+      the optional dependency step failed or you are wiring a custom environment.
+
+To verify that the optional dependency and tunnel infrastructure are available, you can run:
+
+```bash
+appium driver doctor xcuitest
+```
+
+Look for the optional checks related to `appium-ios-remotexpc` and “tunnel availability”.
+
+## Creating Tunnels
+
+The XCUITest driver exposes a high‑level convenience script that wraps the lower‑level
+`appium-ios-remotexpc` tunnel workflow.
+
+!!! warning
+
+    This script must be run as **sudo/root** to create TUN/TAP interfaces for the tunnel.
+
+```bash
+sudo appium driver run xcuitest tunnel-creation
+```
+
+Refer to [the script reference page](../reference/scripts.md#tunnel-creation) for a list of
+additional options.
+
+The script executes the following actions:
+
+- Enumerates all connected and trusted iOS/tvOS devices
+    - The list of available devices can also be retrieved using the [`list-real-devices`](../reference/scripts.md#list-real-devices)
+      script
+- For each device:
+    - Starts a Lockdown session
+    - Starts `com.apple.internal.devicecompute.CoreDeviceProxy` via Remote XPC
+    - Creates an IPv6 tunnel using `TunnelManager.getTunnel(...)`
+    - Starts a packet stream server on a local TCP port (default base: `50000`)
+- Builds an in‑memory tunnel registry containing:
+    - Device UDID and device ID
+    - Tunnel IPv6 address (`Address`) and `RsdPort`
+    - Packet stream port and basic metadata
+- Starts an HTTP tunnel registry API server and prints its address
+- Persists the chosen registry port in a per‑driver strongbox entry so that the driver can find it
+
+### Inspecting the Tunnel Registry
+
+After a successful script execution, you should see log lines similar to:
+
+```text
+📁 Tunnel registry API:
+   The tunnel registry is now available through the API at:
+   http://localhost:<port>/remotexpc/tunnels
+```
+
+You can now use the registry endpoints to retrieve tunnel information:
+
+- List all tunnels:
+
+    ```bash
+    curl http://localhost:<port>/remotexpc/tunnels
+    ```
+
+- Get tunnel for a specific UDID:
+
+    ```bash
+    curl http://localhost:<port>/remotexpc/tunnels/<udid>
+    ```
+
+The response contains the IPv6 `address`, `rsdPort`, and other metadata required to establish
+Remote XPC connections.
+
+## Running Tests
+
+Make sure to create all required tunnel(s) _before_ launching your tests. The tunnel process(es)
+should remaing running in the background, _in addition to_ the Appium server process.
+
+No extra capabilities are required to "enable" tunnels; they are automatically used when:
+
+- `appium-ios-remotexpc` is installed
+- the tunnel registry server is reachable
+- the platform is a real device running iOS/tvOS 18 or later
+
+### Multiple Sessions
+
+The tunnel creation script is multi‑device aware: it creates and registers an independent tunnel
+for each connected device. It can also be limited to specific devices by passing `--udid`/`--appletv-device-id`
+multiple times. The driver can then run multiple sessions concurrently on a single Appium server
+as long as:
+
+- Each session uses a different real device (`appium:udid` is unique per session)
+- The tunnels for all those devices are present in the tunnel registry
+
+If you frequently add/remove devices, consider occasionally re‑running the tunnel script to refresh
+the registry, or use the `--disconnect-retry-max-attempts`/`--disconnect-retry-interval-ms` options
+to configure automatic reconnection.
+
+### Multiple Appium Servers
+
+Since the tunnel registry server is running in a separate process, it is not linked to a specific
+Appium server instance, and can be used by multiple Appium servers simultaneously. To ensure that
+all Appium server instances discover the same tunnel registry, you can set a specific port:
+
+```bash
+sudo appium driver run xcuitest tunnel-creation --tunnel-registry-port 43000
+```
+
+Similarly to running multiple sessions on a single server, make sure that each session uses
+a different device UDID.
+
+In more advanced setups (e.g., Docker, multiple hosts, CI agents), you may want to run one
+tunnel‑creation process per container/VM. In such cases, use distinct `--tunnel-registry-port`
+values for each isolation boundary. This keeps tunnel state scoped to each environment, but within
+that boundary you should still avoid running multiple competing tunnel‑creation scripts
+simultaneously, as they may fight over TUN/TAP configuration and `usbmuxd` connections.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/run-prebuilt-wda.md

@@ -0,0 +1,147 @@
+---
+title: Run Prebuilt WDA
+---
+
+The XCUITest driver runs `xcodebuild` to build and install the WebDriverAgentRunner (WDA) app on the
+target device. Running the command every time could slow down new session creation.
+You can manually run a modified version of this command in order to prebuild the WDA.
+
+## Understanding How `xcodebuild` Works
+
+By default, `xcodebuild` is run with two commands: `build-for-testing` and `test-without-building`.
+`build-for-testing` builds a test bundle package, whereas `test-without-building` actually runs it.
+
+For instance, XCUITest driver issues an `xcodebuild` command like so:
+
+```bash
+xcodebuild build-for-testing test-without-building \
+  -project WebDriverAgent.xcodeproj \
+  -derivedDataPath wda_build \
+  -scheme WebDriverAgentRunner \
+  -destination "platform=iOS Simulator,name=iPhone 14 Pro" \
+  CODE_SIGNING_ALLOWED=NO
+```
+
+This translates to `xcodebuild` building `WebDriverAgent.xcodeproj` and running the resulting
+package on the specified device. The built package will be located in the `wda_build` path.
+
+The command can be split into `build-for-testing` and `test-without-building` parts as follows:
+
+```bash
+xcodebuild build-for-testing \
+  -project WebDriverAgent.xcodeproj \
+  -derivedDataPath wda_build \
+  -scheme WebDriverAgentRunner \
+  -destination "platform=iOS Simulator,name=iPhone 14 Pro" \
+  CODE_SIGNING_ALLOWED=NO
+```
+
+```bash
+xcodebuild test-without-building \
+  -xctestrun wda_build/Build/Products/WebDriverAgentRunner_iphonesimulator16.2-arm64.xctestrun \
+  -destination "platform=iOS Simulator,name=iPhone 14 Pro"
+```
+
+* The `build-for-testing` command generates two files: an `.app` package and an `.xctestrun` file, e.g.:
+
+    ```
+    wda_build/Build/Products/Debug-iphonesimulator/WebDriverAgentRunner-Runner.app
+    wda_build/Build/Products/WebDriverAgentRunner_iphonesimulator16.2-arm64.xctestrun
+    ```
+
+    The `.xctestrun` file name depends on the `-destination` preference. The file contains metadata
+    about the package (the `DependentProductPaths` key).
+
+* The `test-without-building` command starts the WDA application for testing by referencing the
+  provided `.xctestrun` file. Once this is done, `http://localhost:8100` will be able to receive
+  commands for the target device.
+
+## Preparation performance improvement ideas
+
+### Download Prebuilt WDA and run them with `appium:prebuiltWDAPath` and `appium:usePreinstalledWDA`
+
+This approach allows the XCUITest driver to start WDA without running `xcodebuild` by using prebuilt WDA packages.
+We recommend this method if you don't need to modify the WDA source code.
+
+!!! warning "iOS/tvOS 17+ required for `usePreinstalledWDA`"
+
+    With WebDriverAgent v13+, `appium:usePreinstalledWDA` and `appium:prebuiltWDAPath` require **iOS/tvOS 17.0 or newer**.
+    They are **not supported on iOS 16 and below**. See [Run Preinstalled WebDriverAgentRunner](./run-preinstalled-wda.md)
+    for details and alternatives (`xcodebuild` or `appium:webDriverAgentUrl`).
+
+[The Appium WebDriverAgent GitHub page](https://github.com/appium/WebDriverAgent/releases) provides
+downloads for WebDriverAgent packages for real devices and simulators.
+WebDriverAgent packages for real devices do not have embedded XCTest frameworks so that
+they can run on iOS 17+ devices. Please read [Run Preinstalled WebDriverAgentRunner](./run-preinstalled-wda.md)
+for more details about running on real devices and simulators. Understanding app signing is also important when working with real devices.
+Simulators need everything, so WDA package sizes for simulators are greater than for real devices.
+The [Release](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml) and
+[Building WebDriverAgent](https://github.com/appium/WebDriverAgent/actions/workflows/wda-package.yml)
+workflows may help with validating the build script.
+
+[Run Preinstalled WebDriverAgentRunner](./run-preinstalled-wda.md) provides `appium:prebuiltWDAPath`
+and `appium:usePreinstalledWDA` capabilities.
+These capabilities allow the XCUITest driver to install prebuilt WDA specified with
+`appium:prebuiltWDAPath` and start it **without** running `xcodebuild`.
+
+The `download-wda` command helps to download the proper version of WDA for your XCUITest driver version
+for simulator use.
+
+```bash
+appium driver run xcuitest download-wda -- --outdir=/path/to/target/directory --kind=sim --platform=ios
+```
+
+To see all available options for the script, including flags and defaults, run:
+
+```bash
+appium driver run xcuitest download-wda -- --help
+```
+
+Then, starting a new session with capabilities below:
+
+```json
+{
+  "appium:usePreinstalledWDA": true,
+  "appium:prebuiltWDAPath": "/path/to/target/directory/WebDriverAgentRunner-Runner.app"
+}
+```
+
+The new session starts without an `xcodebuild` run.
+
+### Capabilities for Prebuilt WDA with `appium:useXctestrunFile`, `appium:usePrebuiltWDA` or `appium:prebuildWDA`
+
+The XCUITest driver provides two capabilities that allow skipping the `build-for-testing` command,
+and executing only the `test-without-building` command: __`appium:useXctestrunFile`__ and
+__`appium:bootstrapPath`__ (see [Capabilities](../reference/capabilities.md#webdriveragent)).
+
+!!! note
+
+    These capabilities expect that the WDA files are already prebuild, so make sure to first run
+    `xcodebuild` to create the files.
+
+This method can be used on both real devices and simulators, but real devices requires proper
+signing as described in [Run Preinstalled WebDriverAgentRunner](./run-preinstalled-wda.md).
+
+The capabilities can be used as follows:
+
+```json
+{
+  "platformName": "ios",
+  "appium:automationName": "xcuitest",
+  "appium:platformVersion": "18.4",
+  "appium:deviceName": "iPhone 16",
+  "appium:useXctestrunFile": true,
+  "appium:bootstrapPath": "/path/to/wda_build/Build/Products"
+}
+```
+
+Not all combinations have been tested, but the target device can probably be anything.
+
+The same thing can be achieved with the __`appium:derivedDataPath`__ and __`appium:usePrebuiltWDA`__
+capabilities, but this may fail if `xcodebuild` cannot find or handle the `.xctestrun` file
+properly. The stability depends on Xcode.
+
+__`appium:prebuildWDA`__ lets the XCUITest driver build the WDA before running it, then the session
+will be handled with `appium:usePrebuiltWDA`.
+It might have additional building steps than with `appium:derivedDataPath` and `appium:usePrebuiltWDA`
+combination, but it could help `appium:usePrebuiltWDA` to not manage the WDA project.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/run-preinstalled-wda.md

@@ -0,0 +1,177 @@
+---
+title: Run Preinstalled WDA
+---
+
+The XCUITest driver can be configured to launch an already-installed `WebDriverAgentRunner-Runner`
+application (WDA) on a real device and a simulator. This allows you to start a session without the `xcodebuild`
+command execution, improving the session startup performance.
+
+!!! warning "iOS/tvOS 17+ required (WebDriverAgent v13+)"
+
+    Bundled WebDriverAgent v13+ (see [appium/WebDriverAgent#1137](https://github.com/appium/WebDriverAgent/pull/1137))
+    launches preinstalled WDA with `devicectl` only. The legacy launch path through `appium-ios-device` /
+    Instruments is no longer available.
+
+    As a result, `appium:usePreinstalledWDA` and `appium:prebuiltWDAPath` work on **iOS/tvOS 17.0 and newer only**.
+    They are **not supported on iOS 16 and below**. For older OS versions, use the default `xcodebuild` flow or
+    provide `appium:webDriverAgentUrl` if you already have a running WDA server.
+
+## Capabilities
+
+- Required
+    - [`appium:usePreinstalledWDA`](../reference/capabilities.md#webdriveragent)
+- Optional
+    - [`appium:updatedWDABundleId`](../reference/capabilities.md#webdriveragent)
+    - [`appium:updatedWDABundleIdSuffix`](../reference/capabilities.md#webdriveragent)
+    - [`appium:prebuiltWDAPath`](../reference/capabilities.md#webdriveragent)
+
+## Install WebDriverAgent
+
+### Using Xcode
+
+Running a test for the WDA package in Xcode is the easiest way to prepare the device environment:
+
+1. Open WebDriverAgent project in Xcode via `appium driver run xcuitest open-wda`
+2. Select the _WebDriverAgentRunner_ scheme
+3. Select the scheme as _Product -> Scheme -> WebDriverAgentRunner_ (or _WebDriverAgentRunner\_tvOS_ for tvOS)
+4. Select your device in _Product -> Destination_
+5. Select _Product -> Test_ to build and install the WDA app
+
+If using a real device, you may need to change your bundle ID. Please check the
+[Full Manual Provisioning Profile setup](../getting-started/provisioning-profile/full-manual-config.md) for details.
+
+### Using 3rd Party Tools
+
+Some 3rd party tools such as [pymobiledevice3](https://github.com/doronz88/pymobiledevice3),
+[ios-deploy](https://github.com/ios-control/ios-deploy), [go-ios](https://github.com/danielpaulus/go-ios) and
+[tidevice](https://github.com/alibaba/taobao-iphone-device) can install the WebDriverAgent package.
+
+Some tools let you set an arbitrary bundle identifier (`CFBundleIdentifier` for the `Info.plist`) and sign it with the bundle identifier.
+It may not have `.xctrunner` as the bundle identifier.
+XCUITest driver automatically adds the `.xctrunner` suffix to the provided bundle identifier unless a different suffix is specified by the `appium:updatedWDABundleIdSuffix` capability.
+If the value is an empty string, then no suffix will be added to the provided bundle identifier.
+
+The WDA app package (`WebDriverAgentRunner-Runner.app`) can be generated in the _derivedDataPath_
+directory, as explained in [Manual Configuration for a Generic Device](../getting-started/provisioning-profile/generic-device-config.md).
+The app can then be installed without `xcodebuild` using the 3rd party tools.
+
+### Additional requirement for real devices on iOS/tvOS 17+
+
+Preinstalled WDA on real devices is started with `xcrun devicectl device process launch`. The runner app should not
+include embedded `Frameworks/XC**` copies (use the device's local XCTest frameworks instead).
+
+For example, after building the WebDriverAgent with Xcode with proper sign, it generates `/Users/<user>/Library/Developer/Xcode/DerivedData/WebDriverAgent-ezumztihszjoxgacuhatrhxoklbh/Build/Products/Debug-appletvos/WebDriverAgentRunner-Runner.app`.
+Then you can remove `Frameworks/XC**` in `WebDriverAgentRunner-Runner.app` like `rm Frameworks/WebDriverAgentRunner-Runner.app/XC**`.
+
+Configuring `appium:prebuiltWDAPath` to the `/Users/<user>/Library/Developer/Xcode/DerivedData/WebDriverAgent-ezumztihszjoxgacuhatrhxoklbh/Build/Products/Debug-appletvos/WebDriverAgentRunner-Runner.app` would install the `WebDriverAgentRunner-Runner.app`, which has no `Frameworks/XC**` to the target device and launch it with `devicectl` command as part of `appium:usePreinstalledWDA` functionality.
+
+!!! note
+
+    You can also remove `Frameworks/Testing.framework` and `Frameworks/libXCTestSwiftSupport.dylib` to reduce the package size
+    because WebDriverAgent doesn't need both. Then, the total size of the WebDriverAgent runner app can be 3MB or less.
+    `Testing.framework` is almost 6MB and `libXCTestSwiftSupport.dylib` is 2.6MB with Xcode 16 build.
+
+## Launch the Session
+
+After installing the `WebDriverAgentRunner-Runner` application, you can start the Appium server
+and launch an XCUITest driver session with the specified capabilities:
+
+```
+appium
+```
+
+```ruby
+# Ruby
+capabilities: {
+  "platformName": "ios",
+  "appium:automationName": "xcuitest",
+  "appium:udid": "<udid>",
+  "appium:usePreinstalledWDA": true,
+  "appium:updatedWDABundleId": "com.appium.WebDriverAgentRunner"
+}
+@core = Appium::Core.for capabilities: capabilities
+driver = @core.start_driver
+# do something
+driver.quit
+```
+
+If the `<udid>` device has a WebDriverAgent package with `com.appium.WebDriverAgentRunner.xctrunner`
+bundle ID, the session will launch the WebDriverAgent process without `xcodebuild`.
+
+!!! note
+
+    Please ensure that the WDA application is launchable before starting an XCUITest driver session.
+    For example, check whether the provisioning profile is trusted.
+
+
+!!! note
+
+    Please make sure the device under test has the developer disk image mounted.
+    This is necessary to start an XCTest session and load the required XCTest libraries from the device.
+    For example, starting Xcode after connecting the device to the host machine will mount the developer disk image automatically.
+    Using third-party tools can also help to mount the developer disk image service.
+    Please check the documentation for each tool to understand how to mount the developer disk image.
+
+
+```ruby
+# Ruby
+capabilities: {
+  "platformName": "ios",
+  "appium:automationName": "xcuitest",
+  "appium:udid": "<udid>",
+  "appium:usePreinstalledWDA": true,
+  "appium:updatedWDABundleId": "io.appium.wda"
+  "appium:updatedWDABundleIdSuffix": ""
+}
+@core = Appium::Core.for capabilities: capabilities
+driver = @core.start_driver
+# do something
+driver.quit
+```
+
+If the `<udid>` device has a WebDriverAgent package with `io.appium.wda` bundle ID (it does not have `.xctrunner`),
+the session will launch the WebDriverAgent process without `xcodebuild`.
+
+## Set `appium:prebuiltWDAPath`
+
+If the `appium:prebuiltWDAPath` capability is provided with a `WebDriverAgentRunner-Runner.app` test bundle,
+the XCUITest driver will install the application and launch it every test session.
+Test bundles cannot be versioned using `CFBundleVersion` as vanilla applications do usually,
+which is why it is necessary to (re)install them for every test session.
+The test bundle should be signed properly for real devices.
+
+Usually you can find the WDA application bundle at the below location if you use Xcode to build it.
+
+```
+~/Library/Developer/Xcode/DerivedData/WebDriverAgent-<random string>/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app
+```
+
+You can then set your Appium capabilities as follows:
+
+```ruby
+# Ruby
+capabilities: {
+  "platformName": "ios",
+  "appium:automationName": "xcuitest",
+  "appium:udid": "<udid>",
+  "appium:usePreinstalledWDA": true,
+  "appium:prebuiltWDAPath": "/path/to/Library/Developer/Xcode/DerivedData/WebDriverAgent-<random string>/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app"
+}
+@core = Appium::Core.for capabilities: capabilities
+driver = @core.start_driver
+# do something
+driver.quit
+```
+
+!!! note
+
+    As of iOS 17, the testmanagerd service name has changed from `com.apple.testmanagerd` to
+    `com.apple.dt.testmanagerd.runner`. It causes an unexpected WDA process crash with embedded
+    XCTest frameworks while running a single WebDriverAgent package on various OS environments
+    without `xcodebuild`.
+
+    Since WDA v5.10.0, the module can refer to the device's local XCTest frameworks. It lets the
+    Appium/WebDriverAgent package use proper dependencies for the device with a single prebuilt
+    WebDriverAgent package. To set this up, you should remove the package internal frameworks from
+    `WebDriverAgentRunner-Runner.app` with `rm -rf WebDriverAgentRunner-Runner.app/Frameworks/XC*.framework`.
+    The WDA package itself is available from <https://github.com/appium/WebDriverAgent>.