@appium/mcp-documentation 1.0.3 → 1.0.4

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

@@ -0,0 +1,202 @@
+---
+title: Element Lookup Issues
+---
+
+This article helps to resolve possible _functional_ issues that may arise during element lookup,
+where the desired element is either not found or has unexpected property values. Such issues can
+manifest with several symptoms.
+
+For _non-functional_ issues, such as slow performance during element lookup, please refer to the
+[WebDriverAgent Slowness](./wda-slowness.md) guide.
+
+## No Element in Page Source
+
+The desired element is shown as part of a parent element container, and is not individually
+distinguishable in the page source tree. Sometimes the entire application view is shown as one
+single element container.
+
+### Ensure application accessibility
+
+The XCUITest driver is based on Apple's XCTest framework, which uses the information provided by
+the system accessibility framework to distinguish and interact with on-screen elements.
+The same approach is used by various screen readers, VoiceOver, etc. This means that if the
+application is missing accessibility indicators for certain elements, then they may not be visible.
+
+You may start your journey into what Accessibility is and how to deal with it in your applications
+from the official [Apple's accessibility guideline](https://developer.apple.com/design/human-interface-guidelines/accessibility).
+Bear in mind that this tutorial only describes apps based on official Apple frameworks like UIKit
+or SwiftUI. If you use a different framework to build the application's user interface, for example
+[React Native](https://reactnative.dev/), then consider looking for framework-specific
+accessibility guidelines.
+
+It is also possible that the source tree displayed in the Xcode accessibility inspector differs from
+the tree generated by XCTest. The best possible way to verify the page source generated by the
+latter is to check the output of the [`debugDescription`](https://developer.apple.com/documentation/xctest/xcuielement/1500909-debugdescription)
+attribute of the corresponding `XCUIApplication` element. The XCUITest driver exposes this
+functionality using the [`mobile: source`](../reference/execute-methods.md#mobile-source) execute
+method with `format` set to `description`.
+
+### Check if this is a hybrid application
+
+Hybrid applications are applications that use [web views](https://developer.apple.com/design/human-interface-guidelines/web-views)
+in order to represent their whole user interface or portions of it. The iOS web view engine only
+allows for limited accessibility interactions via [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA)
+attributes, which may result in certain elements being absent.
+
+One approach to handle this is to switch the driver context in order to get full native access to
+the page DOM. Read [Automating Hybrid Apps](../guides/hybrid.md) for more details.
+
+For app developers, setting [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
+and [`role`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles)
+attributes allow exposing web elements to the accessibility tree, as [accessibilityLabel](https://developer.apple.com/documentation/objectivec/nsobject/1615181-accessibilitylabel)
+in `WKWebView`. The primary purpose of these attributes is to make web elements accessible for
+tools such as VoiceOver, but they also expose these elements to the XCUITest driver's `NATIVE_APP`
+context. Consider adding these attributes to elements that you want to expose to the driver.
+
+### Adjust the tree depth
+
+Apple's XCTest represents the page source as hierarchical structure (a tree), where each UI element
+has ancestor, descendant or sibling relationships to other elements. Complex applications with
+deeply nested views may therefore result in tree structures of large depth. For performance reasons,
+the XCUITest driver sets the maximum nesting level to `50`, which means that elements of depth `51`
+or greater will not be visible at all.
+
+The driver allows to increase this limit using the [`snapshotMaxDepth`](../reference/settings.md#snapshotmaxdepth)
+setting, but only to a maximum value of `62`. This is due to an Apple limitation, where XCTest
+cannot return any elements located at depth `63` or greater. This limitation is linked to the
+operation of `NSDictionary` and cannot be worked around.
+
+The suggested approach for handling the depth limit of `62` is to refactor the code of the
+actual application under test. For example, applications built using [React Native](https://reactnative.dev/)
+are known to create deeply nested view hierarchies. There are several approaches that can help
+mitigate this:
+
+- Try to remove unnecessary nesting levels
+- Use the Fabric renderer with [View Flattening](https://reactnative.dev/architecture/view-flattening)
+- Use native stack navigator instead of stack navigator
+- Reduce the amount of view tags/test IDs
+
+Check [the corresponding issue](https://github.com/appium/appium/issues/14825) for more details.
+
+Deeply nested hierarchies might also be the reason for the element lookup slowness. Read the
+[Diagnosing WebDriverAgent Slowness](./wda-slowness.md) article to troubleshoot such cases.
+
+### Select the correct active application
+
+Certain UI elements may appear as though they belong to the application under test, but are actually
+part of a completely different application (oftentimes the iOS system itself - the springboard).
+Application ownership of certain elements may even change in different iOS versions. Frequent
+candidates for such behavior are:
+
+- System alerts, such as camera or geolocation permission requests
+- Quick access toolbars, such as Control Center
+- Various RPC sheets, such as the Share To sheet
+
+WebDriverAgent is designed in such a way that it only interacts with a single app hierarchy at a
+time. This is considered the `active` application. The driver provides two approaches to change
+the active app:
+
+- The [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp) execute method
+  allows to explicitly change the currently active application
+- The [`defaultActiveApplication`](../reference/settings.md#defaultactiveapplication) setting allows
+  to set the preferred active application. This means that if WebDriverAgent detects multiple
+  applications, it will attempt to automatically set the preferred application as active.
+
+Check the main [Troubleshooting guide](./index.md) and/or
+[Switching Between iOS Apps During a Test](https://appiumpro.com/editions/13-switching-between-ios-apps-during-a-test)
+article for more details on how to make such elements available.
+
+
+## Test Cannot Find a Known Element
+
+The desired element is shown in the page tree, but cannot be found using an automated test.
+
+### Check for race conditions
+
+Sometimes automation might run too quickly or too slowly depending on the application's UI state.
+This means lookup may fail before the element has appeared, or after it has already disappeared.
+
+- If lookup is too fast: consider using timers, e.g. repeat the `findElement` action multiple times
+  until either the element is found or the timeout occurs. All clients have convenience wrappers
+  for such timers in form of expected conditions.
+- If lookup is too slow: try to optimize your script for the maximum performance, e.g. use
+  optimal/fast element locators, adjust the application and driver settings to perform optimally,
+  etc.
+
+You may also encounter situations where the automation framework is already optimized, but the
+target element disappears quickly by design, for example, a notification popup that only appears
+for a second and then is immediately hidden. For such "special" elements, consider using approaches
+different from `findElement`:
+
+- Post-test video recording analysis (video FPS should usually be enough to catch all short-living
+  elements)
+- Work with application developers to introduce a debug setting to change the behavior for such
+  elements and make them stay visible for longer time
+- Use non-UI-related assertions, like log analysis or direct API calls
+
+### Check for environment mismatches
+
+There are known cases where the application interface/behavior might differ in simulators and real
+devices. It might even differ if the screen size or device model/OS version/system setting differs.
+That is why always make sure that your test development environment, such as one where Appium
+Inspector is used, is as close as possible to the environment where automated tests are run.
+
+
+## Incorrect Element Property Value
+
+The desired element is shown in the page tree, but the value of a certain element property is not
+as expected. For example, the element's `visible` property may be set to `true`, even though the
+element is not actually shown in the application interface, or vice versa.
+
+### The driver has minimum influence to attribute values
+
+This is a simple and at the same time complicated topic.
+
+Since the XCUITest driver is based on Apple's XCTest, where possible, attribute values are
+retrieved from the latter. The standard attributes provided by XCTest can be found in [XCUIElementAttributes](https://developer.apple.com/documentation/xctest/xcuielementattributes?language=objc)
+protocol reference, while the full list of attributes supported by XCUITest driver's WebElement can
+be found in the [Element Attributes](../reference/element-attributes.md) document.
+
+Most of the supported driver attributes are simple compilations of standard XCTest attributes. For
+example, `elementType` is translated to `type` by matching the corresponding [enum](https://developer.apple.com/documentation/xctest/xcuielementtype?language=objc)
+value to a string representation, while `name` is compiled from the original element's identifier
+and label, depending on what is present first. The full list of mapping rules between standard and
+XCUITest attribute values can be found in [WebDriverAgent sources](https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentLib/Categories/XCUIElement%2BFBWebDriverAttributes.m).
+
+Still, some supported driver attributes, like `visible` or `accessible`, have no direct mapping in
+XCTest and are retrieved directly from the accessibility framework ~~using dark magic~~.
+This means that the actual value of these attributes depends on accessibility internals, and is
+available mostly due to ~~legacy~~ convenience purposes, since XCTest does not even expose them.
+We'd love to deprecate and remove this legacy burden and only rely on officially supported
+attributes, but historically many people rely on these attributes, even though their values might
+be not reliable, and there is no good way to debug this behavior or somehow influence it.
+
+The final recommendation here would be:
+
+- If the problematic attribute is based on a public XCUIElement attribute, try to run a vanilla
+  XCTest test with the same app, and compare the attribute value to the one you see in the XCUITest
+  driver. If XCTest returns a correct value, then feel free to raise an [issue](https://github.com/appium/WebDriverAgent/issues)
+  to the Appium team. However, if the XCTest value is still incorrect, then the only place to
+  complain would be the Apple support forum or an XCTest bug tracker.
+- If the problematic attribute is a "custom" driver attribute, like `visible` or `accessible`,
+  then we, most likely, won't be able to help you. You may try to contribute to the corresponding
+  WebDriverAgent sources, but keep in mind that many automation tests rely on the current way
+  these attributes are calculated, and we probably don't want to break them.
+
+
+## Long Element Property Value is Truncated
+
+The desired element is shown in the page tree, but the value of a certain long element property is
+truncated and not fully shown.
+
+### Use value retrieval methods
+
+The XCTest framework limits element property values to 512 bytes in snapshots for performance reasons.
+Such behavior can primarily be observed when retrieving the full page source using the driver, or via
+[debugDescription](https://developer.apple.com/documentation/xctest/xcuielement/1500909-debugdescription)
+in XCTest directly.
+
+The solution here is to retrieve the property value using the corresponding API (such as
+[Get Element Attribute](https://www.w3.org/TR/webdriver1/#get-element-attribute) / [Get Element Text](https://www.w3.org/TR/webdriver1/#dfn-get-element-text)).
+Please see [this issue](https://github.com/appium/appium-xcuitest-driver/issues/2552) and
+[this PR](https://github.com/appium/WebDriverAgent/pull/1007) for more details.

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

@@ -0,0 +1,204 @@
+---
+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#respectsystemalerts) 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#defaultactiveapplication).
+    - 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`](../reference/settings.md#acceptalertbuttonselector)
+      or [`dismissAlertButtonSelector`](../reference/settings.md#dismissalertbuttonselector) settings
+- Activate `com.apple.springboard` with [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp) before interacting with dialogs
+
+[`mobile: activeAppInfo`](../reference/execute-methods.md#mobile-activeappinfo) 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#defaultactiveapplication).
+    - 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.
+
+## Unable to Detect Webview
+
+The driver can only detect webviews that are exposed for debugging. This can be configured by the
+application developer as follows:
+
+- On iOS/iPadOS >= 16.4: the destination `WKWebView` and/or `JSContext` component must have the
+  [`isInspectable`](https://developer.apple.com/documentation/webkit/wkwebview/4111163-isinspectable)
+  property set to `true`. Please read [the WebKit documentation page](https://webkit.org/blog/13936/enabling-the-inspection-of-web-content-in-apps/)
+  for more details on this property.
+- On iOS/iPadOS < 16.4: the [`get-task-allow` entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_cs_debugger)
+  must be set to `true` in the application manifest.

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

@@ -0,0 +1,206 @@
+---
+title: WebDriverAgent Slowness
+---
+
+The XCUITest driver is based on Apple's [XCTest](https://developer.apple.com/documentation/xctest)
+test automation framework and thus inherits most (if not all) properties and features this framework
+provides. The purpose of this article is to help with optimization of automation scenarios that
+don't perform well and/or to explain possible causes of such behavior.
+
+!!! note
+
+    This article only covers specific patterns that the author knows of or dealt with. If your pattern
+    is not present here, try to look for possible occurrences in existing [issues](https://github.com/appium/appium/issues),
+    [Appium forum](https://discuss.appium.io) or just search the internet.
+
+## Context
+
+### How Automation Runs
+
+First, it is important to figure out what exactly is slow. The Appium ecosystem is complicated and
+consists of multiple layers, where each layer could influence the overall duration. For example,
+when an API call is invoked from a client script, it must go through the following stages:
+
+1. Your automation script (Java, Python, C#, etc; runs on your machine)
+2. Appium Client Lib (Java, Python, C#, etc; runs on your machine)
+3. Appium Server (Node.js HTTP server; runs on your machine or a remote one)
+4. XCUITest Driver (Node.js HTTP handler; runs on your machine or a remote one)
+5. WebDriverAgent Server (ObjectiveC HTTP Server; runs on the remote mobile device)
+
+The example above is the simplest flow. If you run your scripts using cloud providers
+infrastructure then the amount of intermediate components in this chain may be much greater. As
+mentioned above, it is very important to know in which stage(s) (or between them) the bottleneck
+is observed.
+
+This article focuses only on the last stage: the WebDriverAgent (WDA) server.
+
+### How WDA Works
+
+The WDA source code is located in [the WebDriverAgent repository](https://github.com/appium/WebDriverAgent/tree/master).
+It is published as the [`appium-webdriveragent`](https://www.npmjs.com/package/appium-webdriveragent)
+NPM package, and contains several helper Node.js modules, along with the WDA source code itself.
+This source code is compiled into an `.xctrunner` bundle, which is a special application type that
+contains tests, and has some higher privileges in comparison to standard apps. The project itself
+consists of three main parts:
+
+- Vendor Libraries (e.g. RoutingHTTPServer)
+    - Ensure support for low-level HTTP- and TCP-server APIs
+- WebDriverAgentLib
+    - Defines handlers for [W3C WebDriver](https://www.w3.org/TR/webdriver/) endpoints and implements
+    all the heavy-lifting procedures related to Apple's XCTest communication, plus some custom
+    handling specific for the XCUITest driver
+- WebDriverAgentRunner
+    - An XCTest test that runs the HTTP server implemented by the WebDriverAgentLib
+
+Important conclusions from the above information:
+
+- WDA is an HTTP server, which executes API commands by invoking HTTP response handlers
+- WDA uses Apple's XCTest APIs with various custom additions
+
+### Check If WDA Is the Bottleneck
+
+Examine the Appium server logs and look for lines similar to the following:
+```bash
+[3716542a][XCUITestDriver@73bc] Proxying [X] to [Y]
+```
+
+This line indicates an HTTP request being proxied to WDA, and its duration can identify how long it
+takes for the XCUITest driver to receive a response from WDA.
+
+For easier debugging, consider enabling server timestamps by providing the `--log-timestamp` Appium
+server parameter.
+
+If you observe timestamps between the above log line and the next one differ too much, and the
+difference is an anomaly (e.g. the same step is (much) faster for other apps/environments/parameter
+combinations), then it might serve as a confirmation of a suspicious slowness.
+
+
+## Slow Application Startup
+
+You observe timeouts or unusual slowness (in comparison to manual execution performance)
+of the application startup on session initialization (if it also includes app startup)
+or mid-session app startup.
+
+### Causes
+
+When XCTest starts an app, it checks that the app's accessibility layer is ready for interactions.
+This is done by verifying that the application is idling (e.g. does not perform any actions on the
+main thread), as well as whether all animations have been finished.
+
+If this check times out, an exception is thrown, or WDA may try to continue without any guarantees
+the app could be interacted with (a.k.a. best effort strategy).
+
+### Solutions
+
+You may try to tune the following capabilities and settings to influence the above timeout:
+
+- [`appium:waitForIdleTimeout`](../reference/capabilities.md) capability
+- [`waitForIdleTimeout`](../reference/settings.md#waitforidletimeout) setting
+- [`animationCoolOffTimeout`](../reference/settings.md#animationcoolofftimeout) setting
+
+Still, there are known cases where the application under test is constantly running something on
+the main thread in an endless loop. Most likely, such apps are not automatable at all, or hardly
+automatable without fixing the app source code itself.
+
+
+## Slow Page Source Retrieval
+
+You observe timeouts or unusual slowness while retrieving the page source of the app.
+
+### Causes
+
+In order to retrieve the page source, WDA needs to take a snapshot of the whole accessibility
+hierarchy with all element attributes resolved, which is a time-expensive operation. The causes for
+the slowness are commonly the following:
+
+- The current app hierarchy is too large (e.g. has hundreds of elements). This is a known
+  XCTest limitation.
+- The app is not idling/has active animations
+- It takes too long to determine each element's `visible` or `accessible` attributes, which are
+  custom and are not present in the original XCTest implementation
+
+### Solutions
+
+- Reduce the size of the app hierarchy using the [`snapshotMaxDepth`](../reference/settings.md#snapshotmaxdepth)
+  and/or [`snapshotMaxChildren`](../reference/settings.md#snapshotmaxchildren) settings. The former setting limits how
+  deep into the hierarchy WDA will traverse; if the destination element is nested deeper than this
+  value, it will not be present in the snapshot. The latter setting limits how many child elements
+  are captured for each node; if there are more siblings than this limit, some of them (and any
+  elements under them) will be omitted from the snapshot.
+- Retrieve the page source without "expensive" attributes using the [`mobile: source`](../reference/execute-methods.md#mobile-source)
+  method with the appropriate `excludedAttributes` argument value, or the [`pageSourceExcludedAttributes` setting](../reference/settings.md#pagesourceexcludedattributes)
+- Retrieve the native XCTest page source using the [`mobile: source`](../reference/execute-methods.md#mobile-source)
+  method with the `format=description` argument value. The returned page source will be
+  poorly-formatted text, but its retrieval should be fast (at least not slower than XCTest).
+- Reduce various timeouts, same as for the [Slow Application Startup pattern](#solutions)
+- Adjust the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Adjust the source code of the application under test to avoid running long operations or
+  animations on the main thread
+
+
+## Slow Element Search Using XPath
+
+You observe timeouts or unusual slowness of XPath locators (in comparison to other location
+strategies).
+
+### Causes
+
+The [XPath](../reference/locator-strategies.md) location strategy is not natively supported by
+XCTest, and is a custom addition only available in WDA. Even though such locators have more
+features than others, the price for it is the observed slowness, as the driver cannot rely on native
+XCTest location APIs while looking for elements using XPath.
+
+In order to perform XPath lookup, WDA needs to take a snapshot of the whole accessibility
+hierarchy with all element attributes resolved, which is a time-expensive operation.
+The causes for the slowness of this operation are mentioned for the [Slow Page Source Retrieval pattern](#causes_1).
+
+### Solutions
+
+In general, the common advice would be to avoid XPath locators where possible, and use locators
+that are natively supported by XCTest (such as `id` or `predicate`), which are also more performant.
+If using XPath locators is the only option, then the following suggestions may help:
+
+- Reduce the size of the app hierarchy using the [`snapshotMaxDepth`](../reference/settings.md#snapshotmaxdepth)
+  and/or [`snapshotMaxChildren`](../reference/settings.md#snapshotmaxchildren) settings
+- Retrieve the page source without the `visible` and/or `accessible` attributes, using the [`mobile: source`](../reference/execute-methods.md#mobile-source)
+  method with the appropriate `excludedAttributes` argument value, or the [`pageSourceExcludedAttributes` setting](../reference/settings.md#pagesourceexcludedattributes)
+- Reduce various timeouts, same as for the [Slow Application Startup pattern](#solutions)
+- Adjust the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Adjust the source code of the application under test to avoid running long operations or
+  animations on the main thread
+
+
+## Slow Element Search Using Non-XPath
+
+You observe timeouts or unusual slowness with various non-XPath locators.
+
+### Causes
+
+All causes mentioned for the [Slow Page Source Retrieval pattern](#causes_1) also apply here.
+
+### Solutions
+
+All suggestions mentioned for the [Slow Element Search Using XPath pattern](#solutions_2) also apply
+here.
+
+
+## Slow Element Interactions
+
+You observe timeouts or unusual slowness while clicking elements or performing other
+actions on them.
+
+### Causes
+
+- The current app hierarchy is too large (e.g. has hundreds of elements). This is a known
+  XCTest limitation.
+- The app is not idling/has active animations
+
+### Solutions
+
+- Reduce various timeouts, same as for the [Slow Application Startup pattern](#solutions)
+- Adjust the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Adjust the source code of the application under test to avoid running long operations or
+  animations on the main thread