appium-mcp 0.0.1 → 1.1.4

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

@@ -0,0 +1,135 @@
+---
+title: Run Prebuilt WebDriverAgentRunner
+---
+
+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.
+
+[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. 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-sim` command helps to download the proper version of WDA for your XCUITest driver version
+for simulator use.
+
+```bash
+appium driver run xcuitest download-wda-sim --outdir=/path/to/target/directory
+```
+
+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,178 @@
+---
+title: Run Preinstalled WebDriverAgentRunner
+---
+
+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+ specific:
+
+    This method currently works over `devicectl` for iOS 17+ with Xcode 15+ environment since XCUITest driver v7.5.0.
+    This may not work for tvOS 17+.
+    iOS/tvOS 16 and lower ones work over [appium-ios-device](https://github.com/appium/appium-ios-device) directly.
+
+## Capabilities
+
+- Required
+    - [`appium:usePreinstalledWDA`](../reference/capabilities.md#webdriveragent)
+- Optional
+    - [`appium:updatedWDABundleId`](../reference/capabilities.md#webdriveragent)
+    - [`appium:updatedWDABundleIdSuffix`](../reference/capabilities.md#webdriveragent)
+        - Since XCUITest driver v7.6.0
+    - [`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
+    - You can run `appium driver run xcuitest open-wda` if using XCUITest driver 4.13 or newer
+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](../preparation/prov-profile-full-manual.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), [ios-app-signer](https://github.com/DanTheMan827/ios-app-signer)
+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](../preparation/prov-profile-generic-manual.md).
+The app can then be installed without `xcodebuild` using the 3rd party tools.
+
+### Additional requirement for iOS 17+/tvOS17+
+
+To launch the WebDriverAgentRunner package with `xcrun devicectl device process launch` for real devices it should not have `Frameworks/XC**` files.
+
+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>.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/touch-id.md

@@ -0,0 +1,33 @@
+---
+hide:
+  - toc
+
+title: Touch ID
+---
+
+The XCUITest driver has the capability to simulate [Touch ID](https://support.apple.com/en-ca/HT201371).
+
+!!! note
+
+    This functionality is only supported on simulators.
+
+## Configuration
+
+To use Touch ID, the application that Appium launches from (Terminal, iTerm, etc.) must be added to
+the accessibility preferences on your Mac. Navigate to _System Preferences -> Privacy & Security ->
+Accessibility_ and under _Allow the apps below to control your computer_ add the application.
+
+Why this is needed: The only way Appium can enable enrollment and toggling of Touch ID is to use
+system-level accessibility APIs to simulate mouse clicks on the simulator menus via AppleScript.
+
+## Usage
+
+* Set the capability `appium:allowTouchIdEnroll` to `true`.
+* When the Simulator starts, Touch ID enrollment will be enabled by default
+* You can toggle Touch ID enrollment by calling the
+  [`mobile: enrollBiometric`](../reference/execute-methods.md#mobile-enrollbiometric) extension
+
+!!! note
+
+    Remember that not all iOS devices have Touch ID, so your tests should handle cases where
+    Touch ID is not supported.

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

@@ -0,0 +1,191 @@
+---
+title: Troubleshooting
+---
+
+## Known Problems
+
+* Real devices with iOS/iPadOS 15+ show an overlay with the text `Automation Running Hold both
+  volume buttons to stop` while WebDriverAgent is running. This is a known limitation of the XCTest
+  framework. Note that screenshotting functionality is not affected (i.e. the overlay is not visible
+  on taken screenshots).
+* Real devices with iOS/iPadOS 15+ [require passcode or Touch ID](https://github.com/appium/appium/issues/15898#issuecomment-927340411)
+  when starting a new session. A workaround for this is to disable passcode/Touch ID on the device.
+* After many failures on a real device, it could transition to a state where connections are no
+  longer being accepted. Rebooting the device can help remedy this problem. Please read
+  [this issue](https://github.com/facebook/WebDriverAgent/issues/507) for more details.
+* `shake` is implemented via AppleScript and works only on Simulator due to lack of support from Apple
+
+## Interact with dialogs managed by `com.apple.springboard`
+
+System dialogs, such as permission dialogs, might not be interactable directly when the active application is not `com.apple.springboard`.
+Despite a similar look, dialogs belonging to the active session application (e.g. initially passed as `appium:app` or `appium:bundleId` capability value)
+do not require such adjustment.
+
+XCUITest driver offers a couple of approaches to handle them:
+
+- Set the [respectSystemAlerts setting](../reference/settings.md) to `true`. It enforces the active application
+  detection algorithm to check a presence of system alerts and to return the Springboard app if this check succeeds.
+  Such approach emulates the driver behavior prior to version 6 of XCUITest driver, although it might slightly
+  slow down your scripts because each attempt to detect an active app would require to also query for alerts
+  presence.
+- Start a session without `appium:app` nor `appium:bundleId`. Then XCUITest driver attempts to get the current active application. This requires you to start an application after a new session request with [`mobile: installApp`](../reference/execute-methods.md#mobile-installapp) to install an app if needed and [`mobile: launchApp`](../reference/execute-methods.md#mobile-launchapp)/[`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp), but it could automatically change the active application with `com.apple.springboard` or activate an application at the foreground. (Note that the automatic app detection might be lengthy, thus each action could take more time.)
+    - When a permission alert exists at the foreground, it could select the `com.apple.springboard`
+    - When another application is at the foreground by accepting/denying the system alert, or [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp), the application would be selected as an active application.
+- [`mobile: alert`](../reference/execute-methods.md#mobile-alert)
+- `defaultActiveApplication` setting in [Settings](../reference/settings.md).
+    - e.g. With the [Appium Ruby client](https://github.com/appium/ruby_lib_core)
+        ```ruby
+        # Interacting with the test target
+        driver.settings.update({defaultActiveApplication: "com.apple.springboard"})
+        # to accept the alert
+        driver.find_element("accessibility_id", "Allow Once").click
+        driver.settings.update({defaultActiveApplication: "auto"})
+        # keep interacting with the test target
+        ```
+- Enable `appium:autoAcceptAlerts`/`appium:autoDismissAlerts`, or interact with alerts via [User Prompts](https://www.w3.org/TR/webdriver1/#user-prompts) in WebDriver endpoints
+    - e.g. `driver.switch_to.alert.accept` with the [Appium Ruby client](https://github.com/appium/ruby_lib_core)
+    - It might be necessary to coordinate element selection via `acceptAlertButtonSelector`/`dismissAlertButtonSelector` settings in [Settings](../reference/settings.md)
+- Activate `com.apple.springboard` with [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp) before interacting with dialogs
+
+[`mobile: activeAppInfo`](../reference/execute-methods.md#mobile-activateappinfo) helps to understand what application (bundleId) is considered as active for the XCUITest driver.
+
+## Interact with dialogs managed by `com.apple.ContactsUI.LimitedAccessPromptView`
+
+iOS 18 introduced a new process named `com.apple.ContactsUI.LimitedAccessPromptView`. See [this issue](https://github.com/appium/appium/issues/20591) for more details.
+As of XCUITest driver v7.26.4, the only workaround to interact with views available through the process is the below method:
+
+- `defaultActiveApplication` setting in [Settings](../reference/settings.md).
+    - e.g. With the [Appium Ruby client](https://github.com/appium/ruby_lib_core)
+        ```ruby
+        # Interacting with the test target
+        driver.settings.update({defaultActiveApplication: "com.apple.ContactsUI.LimitedAccessPromptView"})
+        # to accept the alert
+        driver.find_element("accessibility_id", "Select Contacts").click
+        driver.settings.update({defaultActiveApplication: "auto"})
+        # keep interacting with the test target
+        ```
+
+The `com.apple.ContactsUI.LimitedAccessPromptView` process can get elements available through `com.apple.springboard`, such as several system permission dialogs.
+iOS 18+ devices may be possible to use `com.apple.ContactsUI.LimitedAccessPromptView` to interact with elements managed either by `com.apple.ContactsUI.LimitedAccessPromptView` or `com.apple.springboard`.
+
+## Leftover Application Data on Real Devices
+
+There might be a situation where application data is present on the real device, even if the
+application itself is not installed. This could happen if:
+
+- The app is in an [offloaded state](https://discussions.apple.com/thread/254887240)
+- The application state is cached
+- There was an unexpected failure while installing the app. An example of such failure is the
+  `ApplicationVerificationFailed` which happens while installing an app signed with an invalid provisioning profile.
+
+In the above cases, the application identifier will not be listed in the output of
+[`mobile: listApps`](../reference/execute-methods.md#mobile-listapps), and it will not be detected
+by [`mobile: isAppInstalled`](../reference/execute-methods.md#mobile-isappinstalled). Setting
+`appium:fullReset` or `appium:enforceAppInstall` capabilities to `true` also will not help clear this data.
+
+The only way to completely get rid of the cached application data is to call the
+[`mobile: removeApp`](../reference/execute-methods.md#mobile-removeapp) command with the appropriate
+bundle identifier.
+
+The driver does automatically try to resolve application installs that failed because of the
+`MismatchedApplicationIdentifierEntitlement` error. However, in cases when the previously installed
+application's provisioning profile is different from what currently the driver is trying to
+install, and if you explicitly set the driver to _not_ perform application uninstall, then consider
+calling [`mobile: removeApp`](../reference/execute-methods.md#mobile-removeapp) before the
+`MismatchedApplicationIdentifierEntitlement` error occurs. Example steps can be as follows:
+
+1. Start a session without `appium:app` and `appium:bundleId` capabilities
+2. Call [`mobile: removeApp`](../reference/execute-methods.md#mobile-removeapp) for the target
+   application's bundle id
+3. Install the test target with [`mobile: installApp`](../reference/execute-methods.md#mobile-installapp)
+4. Launch the application with [`mobile: launchApp`](../reference/execute-methods.md#mobile-launchapp)
+   or [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp)
+
+
+!!! note
+
+    We observed that iOS 18+ environments can retain the permission preference even after reinstallation.
+    Please refer to [this issue](https://github.com/appium/appium-xcuitest-driver/issues/2572) for more information about this behavior.
+    
+
+## Weird State
+
+### Real Device Stops Responding
+
+Running tests on a real device is particularly flakey. If things stop responding, the only recourse
+is, most often, to restart the device. Logs in the form of the following _may_ start to occur:
+
+```shell
+info JSONWP Proxy Proxying [POST /session] to [POST http://10.35.4.122:8100/session] with body: {"desiredCapabilities":{"ap..."
+dbug WebDriverAgent Device: Jul 26 13:20:42 iamPhone XCTRunner[240] <Warning>: Listening on USB
+dbug WebDriverAgent Device: Jul 26 13:21:42 iamPhone XCTRunner[240] <Warning>: Enqueue Failure: UI Testing Failure - Unable to update application state promptly. <unknown> 0 1
+dbug WebDriverAgent Device: Jul 26 13:21:57 iamPhone XCTRunner[240] <Warning>: Enqueue Failure: UI Testing Failure - Failed to get screenshot within 15s <unknown> 0 1
+dbug WebDriverAgent Device: Jul 26 13:22:57 iamPhone XCTRunner[240] <Warning>: Enqueue Failure: UI Testing Failure - App state of (null) is still unknown <unknown> 0 1
+```
+
+### Command Takes 60+ Seconds
+
+Sometimes it is possible to encounter slowdowns for an additional 60 seconds for a command that
+usually should not take long. This may be caused by a crash in the `testmanagerd` process on the
+device under test. In such a case, the OS tries to restore the process, then wait for the resurrected
+daemon to connect to the target process, which causes the aforementioned delay.
+
+This can be fixed by terminating the target application process. For example, if this behavior
+occurs while calling `mobile: queryAppState`, you can terminate the application once, or restart the
+device entirely. Please check [this pull request](https://github.com/appium/WebDriverAgent/pull/774)
+for more details.
+
+## Real Device Security Settings
+
+On some systems, especially CI ones, where tests are executed by command line agents, macOS
+Accessibility restrictions result in the WebDriverAgent process being unable to retrieve the
+development keys from the system keychain. This usually manifests by `xcodebuild` returning error
+code `65`. One workaround for this is to use a private key that is not stored on the system
+keychain. See [this issue](https://github.com/appium/appium/issues/6955) and
+[this Stack Exchange post](http://stackoverflow.com/questions/16550594/jenkins-xcode-build-works-codesign-fails).
+
+To export the key, use
+
+```
+security create-keychain -p [keychain_password] MyKeychain.keychain
+security import MyPrivateKey.p12 -t agg -k MyKeychain.keychain -P [p12_Password] -A
+```
+
+where `MyPrivateKey.p12` is the private development key exported from the system keychain.
+
+You can then use the [`appium:keychainPath`](../reference/capabilities.md#webdriveragent) and
+[`appium:keychainPassword`](../reference/capabilities.md#webdriveragent) capabilities to pass this
+keychain to WebDriverAgent.
+
+## Simulator Resetting
+
+When testing on simulators, the driver tries to leave the simulator state as it found it:
+
+* If no `udid` is provided, the driver will create a new iOS simulator, run tests on it, and then
+  delete the simulator
+* If a specific `udid` is provided for a simulator that _is not_ running, the driver will boot the
+  specified simulator, run tests on it, and then shut the simulator down
+* If a specific `udid` is provided for a simulator that _is_ running, the driver will connect to the
+  existing simulator, run tests, and then leave the simulator running
+
+You can use the `appium:noReset` capability to adjust this behavior: setting it to `true` will
+leave the simulator running at the end of a test session.
+
+## Caching Issues During Build
+
+Testing on iOS generates files that can sometimes get large. These include logs, temporary files,
+and derived data from Xcode runs, all of which are safe to delete if any issues arise. The files are
+usually found in the following locations, should they need to be deleted:
+
+```
+$HOME/Library/Logs/CoreSimulator/*
+$HOME/Library/Developer/Xcode/DerivedData/*
+```
+
+## Frequent `Disconnecting from remote debugger` error in iOS 17
+
+Please try out iOS 17.6 or a newer version which includes [a possible fix by Apple](https://developer.apple.com/documentation/safari-release-notes/safari-17_6-release-notes#Web-Inspector).
+
+Frequent Web Inspector debugger disconnection started since iOS 17.2 (or iOS 17.0), that eventually caused `Disconnecting from remote debugger` error.
+It could be improved since iOS 17.6.
+Please check [the corresponding pull request](https://github.com/appium/appium-xcuitest-driver/pull/2334) for more details.

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

@@ -0,0 +1,114 @@
+---
+title: tvOS Support
+---
+
+The XCUITest driver supports automation of the tvOS platform.
+
+<img src="https://user-images.githubusercontent.com/5511591/55161297-876e0200-51a8-11e9-8313-8d9f15a0db9d.gif" width=50%>
+
+!!! warning
+
+    Apple TV 4K is not supported. This is because [`appium-ios-device`](https://github.com/appium/appium-ios-device),
+    which is used to support low-level communication with devices, only supports devices connected via USB.
+
+## Setup
+
+You can run tests for tvOS by setting the `platformName` capability to `tvOS`:
+
+```json
+{
+    "platformName": "tvOS", // here
+    "appium:automationName": "XCUITest",
+    "appium:platformVersion": "12.2",
+    "appium:deviceName": "Apple TV",
+    ...
+}
+```
+
+!!! note
+
+    If using a simulator, make sure the tvOS simulator exists in your simulator list. You can run
+    `xcrun simctl list | grep "com.apple.CoreSimulator.SimRuntime.tvOS"` to verify this.
+
+## Basic Actions
+
+tvOS provides [remote controller](https://developer.apple.com/design/human-interface-guidelines/tvos/remote-and-controllers/remote/)
+based actions. The XCUITest driver implements these actions using the
+[`mobile: pressButton`](../reference/execute-methods.md#mobile-pressbutton) extension, with the
+following button values: `menu`, `up/down/left/right`, `home`, `playpause` and `select`.
+
+All actions are performed on the _focused_ element (which has the `focus` attribute set). The
+focused element is automatically changed after using `mobile: pressButton`.
+
+It is also possible to use the standard `findElement` and `click` methods. The XCUITest driver will
+automatically calculate the necessary sequence of `up/down/left/right` and `select` button presses,
+so you should not care about which keys should be pressed to reach an arbitrary element every time.
+
+=== "Java"
+
+    ```java
+    WebElement element = driver.findElementByAccessibilityId("element on the app");
+    element.getAttribute("focused"); // => 'true'
+    // Appium moves the focus to the element by pressing the corresponding keys and clicking the element
+    element.click();
+    driver.queryAppState("test.package.name"); // => :running_in_foreground
+    driver.executeScript("mobile: pressButton", ImmutableMap.of("name", "Home"));
+    driver.executeScript("mobile: pressButton", ImmutableMap.of("name", "Up"));
+    element = driver.switchTo().activeElement();
+    element.getAttribute("label");
+    ```
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    const element = $('~SomeAccessibilityId');
+    element.getAttribute('focused');
+    element.click();
+    driver.execute('mobile: pressButton', {name: 'Home'});
+    driver.execute('mobile: pressButton', {name: 'Up'});
+    const activeElement = driver.getActiveElement();
+    activeElement.getAttribute('label');
+    ```
+
+=== "Python"
+
+    ```Python
+    element = driver.find_element_by_accessibility_id('element on the app')
+    element.get_attribute('focused')
+    element.click()
+    driver.query_app_state('test.package.name')
+    driver.execute_script('mobile: pressButton', { 'name': 'Home' })
+    driver.execute_script('mobile: pressButton', { 'name': 'Up' })
+    element = driver.switch_to.active_element
+    element.get_attribute('label')
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    element = @driver.find_element :accessibility_id, 'element on the app'
+    element.focused
+    element.click
+    @driver.app_state('test.package.name')
+    @driver.execute_script 'mobile: pressButton', { name: 'Home' }
+    @driver.execute_script 'mobile: pressButton', { name: 'Up' }
+    element = @driver.switch_to.active_element
+    element.label
+    ```
+
+## More Actions
+
+* Consider using `wait` methods, since tvOS also has animation
+* The `menu` button works as _back_ for iOS context in tvOS
+
+## Known Limitations
+
+* Gesture commands do not work for tvOS. Some commands such as pasteboard do not work as well.
+
+## Related Tickets
+
+* <https://github.com/appium/appium/pull/12401>
+* <https://github.com/appium/appium-xcuitest-driver/pull/911>
+* <https://github.com/appium/appium-xcuitest-driver/pull/931>
+* <https://github.com/appium/appium-xcuitest-driver/pull/939>
+* <https://github.com/appium/WebDriverAgent/pull/163>