appium-mcp 0.0.1 → 1.1.5

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

@@ -0,0 +1,158 @@
+---
+title: Elements Lookup Troubleshooting
+---
+
+This article helps to resolve possible issues that may pop up while looking up for elements with XCUITest driver,
+where the desired element is either not found or not visible in the page source at all.
+
+Since there might be multiple reasons to why an element cannot be found the topic is divided into sections where
+each section contains visible symptoms with the list of their possible resolutions.
+
+
+## Symptom #1
+
+The desired element is shown as part of a bigger container and is not distinguishable in the page source tree.
+Sometimes the whole application view with all elements in it is visible as one single container.
+
+## Resolutions To Symptom #1
+
+### Make sure the application under test is accessible
+
+The XCUITest driver is based on Apple's XCTest framework. And the latter uses the information provided by the system
+accessibility framework to interact with on-screen elements, and to distinguish them. The same approach is used by
+various screen readers, VoiceOver, etc. 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 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. XCUITest driver allows to perform a direct forwarding for this API by
+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.
+Web views is the technology that allows to seamlessly integrate web pages browsing experience
+into native mobile applications. Applications might contain native views mixed with web views, or the whole
+application UI might be just a single web view. And while the built-in web view engine allows limited accessibility
+interactions via [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes, consider
+switching a driver context instead in order to get full native access to the page DOM.
+Read [Automating Hybrid Apps](./hybrid.md) for more details there.
+
+### Make sure the application accessibility tree is not too deep
+
+Apple's XCTest represents the page source as hierarchical structure (a tree), where each UI element has ancestor and
+descendant relationships to other elements. There are applications having complex UI structure with deeply nested
+views. Such deep structures are known to create problems for XCTest as the latter is unable to work with tree elements
+whose nesting level is deeper than `62`. This limitation has to do with how `NSDictionary` works and cannot be worked
+around. The default maximum nesting level for the XCUITest driver is set to `50` and could be customized by the
+[snapshotMaxDepth](../reference/settings.md) setting.
+[React Native](https://reactnative.dev/) is known to create
+such deep hierarchies and the only viable solution for now is to fix the application
+under test by flattening nested views. 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 the latter.
+
+### Make sure a valid active application is selected in WebDriverAgent
+
+Sometimes, even if visually it looks like UI elements belong to the same application, they are referenced by
+absolutely different apps. Moreover, the operating system
+may change elements ownership in different versions. In the UI inspector it looks like visually the element
+is visible, but no "real" accessibility control relies on it. Most frequent candidates for such behavior are:
+- System alerts, for example camera or geolocation permission requests
+- Quick access toolbars, for example the one where Wi-Fi or Bluetooth state could be changed
+- Various RPC sheets, for example the Share To collection
+
+WebDriverAgent is designed the way it only interacts with a single app hierarchy at the particular
+moment of time. Such application is called `active`.
+It is possible to switch between applications in runtime using
+[mobile: activateApp](../reference/execute-methods.md#mobile-activateapp) API or
+to provide a hint for WebDriverAgent on which application to prefer if multiple apps are running
+using the [defaultActiveApplication setting](../reference/settings.md).
+Check the [Troubleshooting guide](./troubleshooting.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.
+
+## Symptom #2
+
+The desired element is shown in the page tree, but cannot be found if looked up from an automated test.
+
+## Resolutions To Symptom #2
+
+### Make sure there is no race condition
+
+Sometimes the automation might too fast or too slow depending on in which state the UI is while the lookup is being
+executed. If it is too fast then consider using lookup timers, e.g. repeat the `findElement` more than once until
+either the element is found or the timeout occurs. All clients have convenience wrappers for such timers in form of
+expected conditions.
+If the automation is too slow, e.g. the desired element disappears faster than `findElement` could detect its presence
+then make sure your script is optimized for the maximum performance, e.g. optimal/fast element locators are used,
+the application itself and driver settings are [adjusted](./wda-slowness.md) to perform optimally, etc.
+There might be situations where the automation framework is already optimized, although the desired element is
+a short-living one, for example some notification popup that only appears for a second and then is immediately hidden.
+For such "special" elements consider using approaches different from `findElement`, for example post-test video recording analysis (video FPS should usually be enough to catch all short-living elements), or introducing special
+application debug settings to change the behavior for such elements and make them stay visible for longer time, or
+using non-UI-related assertions, like logs analysis or direct API calls.
+
+### Make sure the debug environment matches to the testing one
+
+There are known cases where 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 your debug
+environment, for example one where Appium Inspector is used,
+is as close as possible to the environment where automated tests are being executed.
+
+
+## Symptom #3
+
+The desired element is shown in the page tree, but its property value is not as expected, for example, it
+is shown as visible while one does not see it in the application interface or vice versa.
+
+## Resolutions To Symptom #3
+
+### XCUITest driver has minimum influence to attribute values
+
+This is a simple and at the same time complicated topic. Since XCUITest driver is based on Apple's XCTest,
+all attribute values are retrieved from the latter. Standard attributes provided by XCTest could be found in
+[XCUIElementAttributes](https://developer.apple.com/documentation/xctest/xcuielementattributes?language=objc)
+protocol reference. The full list of attributes supported by XCUITest driver's WebElement
+could be found in the [Element Attributes](../reference/element-attributes.md) document.
+Most of the above attributes are simple compilations of standard 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, `name` is compiled from original element's identifier and label depending on what is
+present first. The full list of mapping rules between standard and XCUITest attribute values could be found in
+[WebDriverAgent sources](https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentLib/Categories/XCUIElement%2BFBWebDriverAttributes.m).
+Although, some attributes there, like `visible` or `accessible` have no direct mapping in XCTest
+and are retrieved directly from the accessibility framework ~~using dark magic~~.
+This means the actual value of these attributes only depends on accessibility internals and is there
+mostly due to ~~legacy~~ convenience purposes, as the original XCTest does not even expose them.
+We'd love to deprecate and remove this legacy burden and only rely on officially supported attributes,
+although historically many people rely on them, so we keep it, 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 there would be:
+- If the value of an attribute that directly or indirectly relies on a public XCUIElement attribute
+  is different from what you expect then run a vanilla XCTest with the same app and make sure
+  it's not the same as you see in the XCUITest driver. If it is then the only place to complain
+  would be the Apple support forum or a XCTest bug tracker. If you can confirm the issue lies in
+  WebDriverAgent's mapping logic then feel free to raise an
+  [issue](https://github.com/appium/WebDriverAgent/issues) to its maintainers.
+- If the value of an attribute that is a "custom" XCUITest attribute, like `visible` or `accessible`,
+  is different from what you expect then we, most likely, won't be able to help you. You may try
+  to improve the corresponding WebDriverAgent sources, but keep in mind there are many automation
+  tests around that rely on the current way these attributes are calculated, and we probably don't
+  want to break them.
+
+## Symptom #4
+
+The desired element is shown in the page tree, but the content of its `value` property is cut off. For example, the actual size of the element's `value` attribute is above 512 bytes, while the size in the XML page source is always limited to 512 bytes.
+
+## Resolutions To Symptom #4
+
+Retrieve the element's `value` using the corresponding API ([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)) to get the full/uncut content. 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.
+
+XCTest framework cuts off long element values in snapshots to achieve the best performance and to reduce the memory footprint. If an element was inspected via [debugDescription](https://developer.apple.com/documentation/xctest/xcuielement/1500909-debugdescription) in XCTest for UI (not Appium XCUITest driver), it prints the value partially while the [value](https://developer.apple.com/documentation/xctest/xcuielementattributes/value) attribute like `element.value` prints the entire value.

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

@@ -0,0 +1,147 @@
+---
+title: File Transfer
+---
+
+The XCUITest driver provides several [extension commands](../reference/execute-methods.md) for file transfer:
+
+* [`mobile: pullFolder`](../reference/execute-methods.md#mobile-pullfolder)
+* [`mobile: pullFile`](../reference/execute-methods.md#mobile-pullfile)
+* [`mobile: pushFile`](../reference/execute-methods.md#mobile-pushfile)
+* [`mobile: deleteFolder`](../reference/execute-methods.md#mobile-deletefolder)
+* [`mobile: deleteFile`](../reference/execute-methods.md#mobile-deletefile)
+
+This documentation aims to help to understand how they work on iOS.
+
+## Formats
+
+All commands require a parameter with a path to the file/folder on the target device. There are 3
+possible formats this path can take:
+
+### Format 1
+
+```
+@<app-bundle-id>:<container-type>/<path-to-file-or-folder>
+```
+
+* `@<app-bundle-id>` is the application bundle identifier
+* `<container-type>` is the container type
+    * On simulators, common values are `app`, `data`, `groups`, but a custom one can also be provided
+    * On real devices, the only accepted value is `documents`. All others are treated as Format 2
+        * This value can only be specified for apps that have the `UIFileSharingEnabled` flag set to
+          `true`. You can use the [`mobile: listApps`](../reference/execute-methods.md#mobile-listapps)
+          extension to identify such apps.
+        * By assigning the `skipDocumentsContainerCheck` [Settings API](https://appium.io/docs/en/latest/guides/settings/) to `true`, you may skip the above limitation for certain apps.
+
+* `<path-to-file-or-folder>` is the target file or folder
+    * On real devices, if `<container-type>` is set to `documents`, this path will be mapped to
+      `On My iPhone/<app name>` in the _Files_ app
+
+### Format 2
+
+```
+@<app-bundle-id>/<path-to-file-or-folder>
+```
+
+* On simulators, the implicit `<container-type>` is set to `app`.
+* On real device, only apps with the `UIFileSharingEnabled` flag set to `true` in their `info.plist`
+  can be mounted. You can use the [`mobile: listApps`](../reference/execute-methods.md#mobile-listapps)
+  extension to identify such apps.
+
+### Format 3
+
+```
+<path-to-file-or-folder>
+```
+
+This format is only supported on simulators. The implicit `<container-type>` is set to `app`.
+Eventually the whole simulator file system is
+[available](https://stackoverflow.com/questions/6480607/is-there-any-way-to-see-the-file-system-on-the-ios-simulator)
+directly from the macOS Finder, so you may pull any file from there by providing a path to it
+relatively to the simulator's file system root.
+
+## Examples
+
+### `pullFile`
+
+This example pulls a file present in _Files -> On My iPhone -> Keynote_:
+
+|Top | On  My iPhone | Keynote |
+|:----:|:----:|:----:|
+|![](./assets/images/ios-xctest-file-movement/top_files.png)|![](./assets/images/ios-xctest-file-movement/on_my_iphone.png)|![](./assets/images/ios-xctest-file-movement/keynote.png)|
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    let data = driver.pullFile('@com.apple.Keynote:documents/Presentation.key');
+    await fs.writeFile('presentation.key', Buffer.from(data, 'base64'), 'binary');
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    file = @driver.pull_file '@com.apple.Keynote:documents/Presentation.key'
+    File.open('presentation.key', 'wb') { |f| f<< file }
+    ```
+
+If the file is in deeper place like _Keynote/Dir1/Dir2_, then the path changes:
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    let data = driver.pullFile('@com.apple.Keynote:documents/Dir1/Dir2/Presentation.key');
+    await fs.writeFile('presentation.key', Buffer.from(data, 'base64'), 'binary');
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    file = @driver.pull_file '@com.apple.Keynote:documents/Dir1/Dir2/Presentation.key'
+    File.open('presentation.key', 'wb') { |f| f<< file }
+    ```
+
+Example for a simulator using Format 3:
+
+```java
+// Java
+// Get AddressBook.sqlitedb in test app package ('app' container)
+byte[] fileContent = driver.pullFile("Library/AddressBook/AddressBook.sqlitedb");
+Path dstPath = Paths.get(new File("/local/path/AddressBook.sqlitedb"));
+Files.write(dstPath, fileContent);
+```
+
+### `pullFolder`
+
+You can pull folders similarly to files, but the path must end with a forward slash (`/`).
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    let data = driver.pullFolder('@com.apple.Keynote:documents/');
+    await fs.writeFile('documents.zip', Buffer.from(data, 'base64'), 'binary');
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    file = @driver.pull_folder '@com.apple.Keynote:documents/'
+    File.open('documents.zip', 'wb') { |f| f<< file }
+    ```
+
+### `pushFile`
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    driver.pushFile('@com.apple.Keynote:documents/text.txt', new Buffer("Hello World").toString('base64'));
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    @driver.push_file '@com.apple.Keynote:documents/text.txt', (File.read 'path/to/file')
+    ```
+
+## References
+- <https://stackoverflow.com/questions/1108076/where-does-the-iphone-simulator-store-its-data>
+- <https://stackoverflow.com/questions/48884248/how-can-i-add-files-to-the-ios-simulator>
+- <https://apple.stackexchange.com/questions/299413/how-to-allow-the-files-app-to-save-to-on-my-iphone-or-to-on-my-ipad-in-ios/299565#299565>

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

@@ -0,0 +1,52 @@
+---
+title: Gestures
+---
+
+The XCUITest driver provides multiple options for touch gestures automation.
+For simple gestures, like tap by coordinates, long tap, multi-finger tap, double/triple tap,
+swipe, drag, rotate, scroll or pinch use the below gesture shortcuts:
+
+- [mobile: tap](../reference/execute-methods.md#mobile-tap)
+- [mobile: doubleTap](../reference/execute-methods.md#mobile-doubletap)
+- [mobile: touchAndHold](../reference/execute-methods.md#mobile-touchandhold)
+- [mobile: twoFingerTap](../reference/execute-methods.md#mobile-twofingertap)
+- [mobile: dragFromToForDuration](../reference/execute-methods.md#mobile-dragfromtoforduration)
+- [mobile: dragFromToWithVelocity](../reference/execute-methods.md#mobile-dragfromtowithvelocity)
+- [mobile: rotateElement](../reference/execute-methods.md#mobile-rotateelement)
+- [mobile: tapWithNumberOfTaps](../reference/execute-methods.md#mobile-tapwithnumberoftaps)
+- [mobile: forcePress](../reference/execute-methods.md#mobile-forcepress)
+- [mobile: scrollToElement](../reference/execute-methods.md#mobile-scrolltoelement)
+- [mobile: scroll](../reference/execute-methods.md#mobile-scroll)
+- [mobile: pinch](../reference/execute-methods.md#mobile-pinch)
+
+For more sophisticated gestures
+consider using [W3C actions](https://w3c.github.io/webdriver/#actions).
+
+Make sure you don't use deprecated JSONWP TouchActions APIs. They have been
+removed from the XCUITest driver since version 7.
+
+If the action code in the client source looks good and satisfies the above requirements,
+but its execution still does not deliver the expected result then the following debugging
+measures might be applied:
+
+- Make sure the gesture has valid coordinates and respects pauses between pointer state changes.
+  For example, it is always mandatory to provide a valid element or valid `absolute` coordinates
+  to any gesture at the beginning. iOS only registers
+  a long touch/click if the pointer has been depressed for longer than 500ms. For shorter actions
+  a simple click is registered instead.
+- If your tests run on Simulator then it is possible to activate pointer tracing by enabling
+  the [appium:simulatorTracePointer](../reference/capabilities.md#simulator) capability or by enabling
+  `Visual Indicators` items from Simulator settings. After running
+  your automation code with this feature enabled you would be able to see the exact pointer trace path
+  and check the velocity of the gesture. Compare the trace
+  to how the same gesture is usually done manually and apply the necessary updates to your code.
+- Do not mix webview and native elements in actions arguments. It simply won't work. Native
+  actions could only consume native elements. A single possibility to perform a native action
+  on a web element would be to translate its coordinates into the native context and pass these
+  coordinates as native action arguments.
+
+Check the below tutorials for more details on how to build reliable action chains:
+
+- [Automating Complex Gestures with the W3C Actions API](https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api)
+- [Swiping your way through Appium by Wim Selles #AppiumConf2021](https://www.youtube.com/watch?v=oAJ7jwMNFVU)
+- [About iOS Input Events](./input-events.md)

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

@@ -0,0 +1,137 @@
+---
+title: Automating Hybrid Apps
+---
+
+One of the core principles of XCUITest driver is that you shouldn't have to change your
+app to test it. In line with that methodology, it is possible to test hybrid
+apps the same way you can with Selenium for web apps. There is a bit of technical
+complexity required so that XCUITest driver knows whether you want to automate the native
+aspects of the app or the web views. But, thankfully, we can stay within the
+Selenium WebDriver protocol for everything.
+
+Once the test is in a web view context the command set that is available is the
+full [Selenium](http://www.seleniumhq.org/) [WebDriver API](https://www.w3.org/TR/webdriver/).
+
+### Requirements
+
+To interact with a web view XCUITest driver establishes a connection using a custom
+[remote debugger](https://github.com/appium/appium-remote-debugger).
+This debugger can connect directly to any WebKit debugger socket exposed by the system.
+The protocol used for the communication there is a proprietary Apple's JSON RPC similar
+to Chrome's [Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/).
+Not all web views expose debugger web sockets by default thus making them invisible
+for the XCUITest driver and not showing in the available contexts list.
+Make sure the following prerequisites are satisfied if you are unsure about whether
+the particular web view is debuggable or not:
+
+- If you use real devices then make sure the Settings→Safari→Advanced→Web Inspector
+  checkbox is turned on.
+- If your app's web view is based on WKWebView then make sure the
+  [isInspectable](https://developer.apple.com/documentation/webkit/wkwebview/4111163-inspectable?language=objc) property of it set to `true`. Note, that you must have access to the application sources in order
+  to ensure that!
+- Make sure you see the corresponding web view in Safari's
+  [remote debugger](https://help.salesforce.com/s/articleView?id=000391692&type=1) list.
+
+If all the above requirements have been satisfied, but the desired web view is still not present in the
+XCUITest driver's context list then there is probably an issue in the driver itself, which must be reported
+to driver maintainers.
+
+### Entering the web view context
+
+Here are the steps required to talk to a web view in your XCUITest driver test:
+
+1. Navigate to a portion of your app where a web view is active
+2. Retrieve the currently available contexts
+    * This returns a list of contexts we can access, like `'NATIVE_APP'` or `'WEBVIEW_1'`
+3. Set the id of the context you want to access
+    * This puts your XCUITest session into a mode where all commands are
+      interpreted as being intended for automating the web view, rather than the
+      native portion of the app. For example, if you run `findElement`, it
+      will operate on the DOM of the web view, rather than return native elements.
+      Of course, certain WebDriver methods only make sense in one context or
+      another, so in the wrong context you will receive an error message.
+4. To stop automating in the web view context and go back to automating the
+   native portion of the app, simply set the context
+   again with the native context id (generally `'NATIVE_APP'`) to leave the web
+   context and once again access the native commands.
+
+### Automatically entering the web view context on session start
+
+If your application begins in a web view, and you do not want to automate the
+native application before entering it, you can have XCUITest driver automatically enter
+the web view context on session initialization by setting the `autoWebview`
+[capability](../reference/capabilities.md) to `true`.
+
+
+### Examples
+
+=== "Java"
+    ```java
+    // java
+    // assuming we have a set of capabilities
+    driver = new AppiumDriver(new URL("http://127.0.0.1:4723/"), options);
+
+    Set<String> contextNames = driver.getContextHandles();
+    for (String contextName : contextNames) {
+        System.out.println(contextName); //prints out something like NATIVE_APP \n WEBVIEW_1
+    }
+    driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1
+
+    //do some web testing
+    String myText = driver.findElement(By.cssSelector(".green_button")).click();
+
+    driver.context("NATIVE_APP");
+
+    // do more native testing if we want
+
+    driver.quit();
+    ```
+    
+=== "Ruby"
+    ```ruby
+    # ruby_lib_core
+    # assuming we have a set of capabilities
+    @driver = Appium::Core.for(url: SERVER_URL, desired_capabilities: capabilities).start_driver
+    # ruby_lib
+    # opts = { caps: capabilities, appium_lib: { custom_url: SERVER_URL }}
+    # @driver = Appium::Driver.new(opts, true).start_driver
+
+    # I switch to the last context because its always the webview in our case, in other cases you may need to specify a context
+    # View the appium logs while running @driver.contexts to figure out which context is the one you want and find the associated ID
+    # Then switch to it using @driver.switch_to.context("WEBVIEW_6")
+
+    Given(/^I switch to webview$/) do
+        webview = @driver.available_contexts.last
+        @driver.switch_to.context(webview)
+    end
+
+    Given(/^I switch out of webview$/) do
+        @driver.switch_to.context(@driver.contexts.first)
+    end
+
+    # Now you can use CSS to select an element inside your webview
+
+    And(/^I click a webview button $/) do
+        @driver.find_element(:css, ".green_button").click
+    end
+    ```
+
+=== "Python"
+    ```python
+    # python
+    # assuming we have an initialized `driver` object for an app
+
+    # switch to webview
+    webview = driver.contexts.last
+    driver.switch_to.context(webview)
+
+    # do some webby stuff
+    driver.find_element(By.CSS, ".green_button").click
+
+    # switch back to native view
+    driver.switch_to.context(driver.contexts.first)
+
+    # do more native testing if we want
+
+    driver.quit()
+    ```

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

@@ -0,0 +1,67 @@
+---
+title: About iOS Input Events
+---
+
+## What Are Input Events
+
+iOS uses the Events concept to handle signals received from different input devices. An Event is an
+object generated in response to a signal from an input device. These objects are then delivered to
+the corresponding kernel subsystem, which processes them and notifies all listening processes about
+taps, key presses, swipes, etc. This means that in order to emulate a signal generated by an external
+device, such as a touch screen, it is necessary to just send Event objects with the same properties
+and in the same sequence as they would be generated by a real device.
+
+## Simulating a Single Tap
+
+The Events API itself is a part of Apple private API, and it is neither open sourced nor documented.
+The XCTest framework also does not expose any _public_ APIs for input events generation, although
+there is a possibility to perform events generation via XCTest _private_ undocumented APIs.
+
+In particular, we are interested in the
+[`XCPointerEventPath`](https://github.com/appium/WebDriverAgent/blob/master/PrivateHeaders/XCTest/XCPointerEventPath.h)
+and [`XCSynthesizedEventRecord`](https://github.com/appium/WebDriverAgent/blob/master/PrivateHeaders/XCTest/XCSynthesizedEventRecord.h)
+interfaces. These APIs allow to create chains of input events and supply them to the system kernel
+for execution.
+
+In order to synthesize a single tap, it is necessary to:
+
+- Create a new `XCPointerEventPath` instance and initialize it for touch at the starting point
+- Add a new `liftUp` event at `0.125s` offset using `liftUpAtOffset:` method
+- Add the generated event path object to `XCSynthesizedEventRecord` instance using
+  `addPointerEventPath:` method
+- Execute the events using `synthesizeWithError:` method of `XCSynthesizedEventRecord` instance and
+  control the returned error
+
+There are several limitations to these APIs:
+
+- Each `XCPointerEventPath` instance can only be executed for a single action. If one tries to add,
+  for example, two taps to a single path, then these are effectively ignored
+- Each `XCPointerEventPath` instance can only be initialized for a particular pointer type: touch,
+  mouse (since Xcode 10.2) or keyboard (since Xcode 10.2)
+- Events can only be added with increasing offset values to an existing `XCPointerEventPath` instance
+
+## More Complicated Actions
+
+Unfortunately, because the API is private and has zero documentation, one can only figure out what
+it can do by playing with it and trying different input combinations.
+
+It is known that providing multiple `XCPointerEventPath` instances with overlapping timeouts will
+generate a multitouch action with the amount of fingers equal to the amount of the supplied event
+paths. So, in order to generate two-finger symmetric swipe we need to supply the following events:
+
+- Create a two `XCPointerEventPath` instances and init them for touch at the starting point
+- Add a `moveToPoint` event at `0.525s` offset using `moveToPoint:` method to each path
+- Add a `liftUp` eventa at `0.525s` offset using `liftUpAtOffset:` method to each path
+- Add the generated event paths to `XCSynthesizedEventRecord` instance using `addPointerEventPath:` method
+- Execute the events using `synthesizeWithError:` method of `XCSynthesizedEventRecord` instance and
+  control the returned error
+
+## Further Reading
+
+Unfortunately, there is no information on this topic at all (private API `¯\_(ツ)_/¯`). Consider
+visiting the following resources:
+
+* <https://github.com/appium/WebDriverAgent/tree/master/PrivateHeaders/XCTest>
+* <https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentTests/IntegrationTests/FBW3CTouchActionsIntegrationTests.m>
+* <https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentTests/IntegrationTests/FBW3CMultiTouchActionsIntegrationTests.m>
+* <https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentLib/Utilities/FBW3CActionsSynthesizer.m>

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

@@ -0,0 +1,19 @@
+---
+hide:
+  - toc
+
+title: Self-Signed Certificates
+---
+
+Unfortunately, Apple does not provide any command line options which can help to install self-signed
+certificate on a real device or simulator. However, there is
+[over-the-air](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/Introduction/Introduction.html)
+enrollment technology, which allows the deployment of several entity types, including such
+certificates, by simply downloading specially prepared configuration files with the built-in web
+browser. After the configuration is downloaded it can be installed and trusted by going through
+several simple wizard steps.
+
+You can use the following extension methods to assist with this:
+
+* [`mobile: installCertificate`](../reference/execute-methods.md#mobile-installcertificate)
+* [`mobile: removeCertificate`](../reference/execute-methods.md#mobile-removecertificate)

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/multiple-xcode-versions.md

@@ -0,0 +1,37 @@
+---
+hide:
+  - toc
+
+title: Managing Multiple Xcodes
+---
+
+If you have multiple Xcode installations, you may choose which toolset Appium should use with one
+of two ways:
+
+### `xcode-select` tool
+Only available with `sudo` privileges, affects the whole system.
+
+Assuming you want to choose `/Applications/Xcode13.app`:
+
+1. Set the default Xcode
+  ```
+  sudo xcode-select -s /Applications/Xcode13.app/Contents/Developer
+  ```
+2. Run Appium
+  ```
+  appium
+  ```
+
+### Environment variable
+No privileges needed, affects only the current shell, so Appium should be started within that shell.
+
+Assuming you want to choose `/Applications/Xcode12.app`:
+
+1. Set the `DEVELOPER_DIR` environment variable
+  ```
+  export DEVELOPER_DIR=/Applications/Xcode12.app/Contents/Developer
+  ```
+2. Run Appium
+  ```
+  appium
+  ```

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

@@ -0,0 +1,39 @@
+---
+hide:
+  - toc
+
+title: Testing 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`.