@appium/mcp-documentation 1.0.3 → 1.0.4

package/src/resources/submodules/appium-xcuitest-driver/README.md

@@ -0,0 +1,55 @@
+# appium-xcuitest-driver
+
+[![npm version](http://img.shields.io/npm/v/appium-xcuitest-driver.svg)](https://npmjs.org/package/appium-xcuitest-driver)
+[![Downloads](http://img.shields.io/npm/dm/appium-xcuitest-driver.svg)](https://npmjs.org/package/appium-xcuitest-driver)
+
+[![Release](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml/badge.svg)](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml)
+
+This is an [Appium](https://appium.github.io/appium) driver for automating iOS applications on iOS,
+iPadOS, and tvOS.
+
+> [!IMPORTANT]
+> Only macOS is supported as the host platform, as it requires Xcode and developer tools.
+
+> [!IMPORTANT]
+> Since major version *10.0.0*, this driver is only compatible with Appium 3. Use the `appium driver install xcuitest`
+> command to add it to your distribution.
+
+
+## Documentation
+
+The [Documentation](https://appium.github.io/appium-xcuitest-driver) is hosted separately at
+[https://appium.github.io/appium-xcuitest-driver](https://appium.github.io/appium-xcuitest-driver)
+
+## Contributing & Development
+
+Clone this project from GitHub and run:
+
+```bash
+npm install
+```
+
+To watch changes during the development:
+
+```bash
+npm run watch
+```
+
+To run unit/functional tests:
+
+```bash
+npm test # unit
+npm run e2e-test # functional
+```
+
+There are also a number of environment variables that can be used when running
+the tests locally. These include:
+
+* `REAL_DEVICE` - set to anything truthy, makes the tests use real device capabilities
+* `_FORCE_LOGS` - set to `1` to get the log output, not just spec
+* `PLATFORM_VERSION` - change the version to run the tests against (defaults to `9.3`)
+* `XCCONFIG_FILE` - specify where the xcode config file is for a real device run (if
+  blank, and running a real device test, it will search for the first file in
+  the root directory of the repo with the extension "xcconfig")
+* `UICATALOG_REAL_DEVICE` - path to the real device build of UICatalog, in case
+  the npm installed one is not built for real device

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

@@ -0,0 +1,45 @@
+---
+hide:
+  - navigation
+  - toc
+
+title: Contributing
+---
+
+Contributions to this project are welcome! To start off, clone it from GitHub and run:
+
+```bash
+npm install
+```
+
+To watch changes during development:
+
+```bash
+npm run watch
+```
+
+To run unit/functional tests:
+
+```bash
+npm run test # unit 
+npm run e2e-test # functional
+```
+
+To develop documentation:
+
+```bash
+npm run install-docs-deps # install the dependencies (Python packages)
+npm run dev:docs # serve the docs locally and watch for changes
+```
+
+There are also a number of environment variables that can be used when running
+the tests locally. These include:
+
+* `REAL_DEVICE` - set to anything truthy, makes the tests use real device capabilities
+* `_FORCE_LOGS` - set to `1` to get the log output, not just spec
+* `PLATFORM_VERSION` - change the version to run the tests against (defaults to `11.3`)
+* `XCCONFIG_FILE` - specify where the Xcode config file is for a real device run (if
+  blank, and running a real device test, it will search for the first file in
+  the root directory of the repo with the extension `.xcconfig`)
+* `UICATALOG_REAL_DEVICE` - path to the real device build of UICatalog, in case
+  the `npm` installed one is not built for a real device

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

@@ -0,0 +1,61 @@
+## WebDriverAgent JSONWP Endpoints
+
+### Session-less commands
+
+| method | endpoint                               | req params | opt params |
+| ------ | -------------------------------------- | ---------- | ---------- |
+| POST   | /wda/homescreen                        | | |
+| GET    | /source                                | | accessible |
+| GET    | /inspector                             | | |
+| GET    | /inspector.js                          | | |
+| GET    | /screenshot                            | | |
+| POST   | /session                               | desiredCapabilities
+| GET    | /status                                | | |
+| GET    | /*                                     | ** | |
+| POST   | /*                                     | ** | |
+| PUT    | /*                                     | ** | |
+| DELETE | /*                                     | ** | |
+
+
+### Session commands
+
+| method | endpoint                               | req params | opt params |
+| ------ | -------------------------------------- | ---------- | ---------- |
+| GET    | /alert/text                            | | |
+| POST   | /alert/accept                          | | |
+| POST   | /alert/dismiss                         | | |
+| POST   | /wda/deactivateApp                     | | duration |
+| POST   | /timeouts                              | * | |
+| GET    | /source                                | | accessible |
+| GET    | /element/:uuid/enabled                 | | |
+| GET    | /element/:uuid/rect                    | | |
+| GET    | /element/:uuid/attribute/:name         | | |
+| GET    | /element/:uuid/text                    | | |
+| GET    | /element/:uuid/displayed               | | |
+| GET    | /wda/element/:uuid/accessible          | | |
+| GET    | /element/:uuid/name                    | | |
+| POST   | /element/:uuid/value                   | value | |
+| POST   | /element/:uuid/click                   | | |
+| POST   | /element/:uuid/clear                   | | |
+| POST   | /wda/element/:uuid/doubleTap        | | |
+| POST   | /wda/element/:uuid/touchAndHold     | duration | |
+| POST   | /wda/element/:uuid/scroll           | | name, direction, predicateString, toVisible |
+| POST   | /uiaElement/:uuid/value                | value | |
+| POST   | /wda/element/:uuid/dragfromtoforduration | fromX, fromY, toX, toY, duration | |
+| POST   | /wda/tap/:uuid                         | x, y | |
+| POST   | /wda/keys                              | value | |
+| GET    | /window/size                           | | |
+| POST   | /element                               | using, value | |
+| POST   | /elements                              | using, value | |
+| GET    | /wda/uiaElement/:uuid/getVisibleCells  | | |
+| POST   | /element/:uuid/element                 | using, value | |
+| POST   | /element/:uuid/elements                | using, value | |
+| GET    | /orientation                           | | |
+| POST   | /orientation                           | orientation | |
+| GET    | /screenshot                            | | |
+| POST   | /wda/touch_id                | match | |
+
+
+\* implemented but intentionally not supported
+
+** not implemented handlers

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

@@ -0,0 +1,95 @@
+## Appium iOS JSONWP Endpoints
+
+### Session-less commands
+
+| method | endpoint                                 | req params | opt params |
+| ------ | ---------------------------------------- | ---------- | ---------- |
+| GET    | /status                                  | | |
+| POST   | /session                                 | desiredCapabilities | requiredCapabilities |
+| GET    | /sessions                                | | |
+
+
+### Session commands
+
+| method | endpoint                                 | req params | opt params |
+| ------ | ---------------------------------------- | ---------- | ---------- |
+| GET    | /:sessionId                              | | |
+| DELETE | /:sessionId                              | | |
+| POST   | /timeouts                                | type, ms | |
+| POST   | /timeouts/async_script                   | ms | |
+| POST   | /timeouts/implicit_wait                  | ms | |
+| GET    | /window_handle                           | | |
+| GET    | /window_handles                          | | |
+| GET    | /url                                     | | |
+| POST   | /url                                     | url | |
+| POST   | /forward                                 | none | |
+| POST   | /back                                    | none | |
+| POST   | /refresh                                 | none | |
+| POST   | /execute                                 | script, args | |
+| POST   | /execute_async                           | script, args | |
+| GET    | /screenshot                              | | |
+| POST   | /frame                                   | id | |
+| POST   | /window                                  | name | |
+| DELETE | /window                                  | | |
+| GET    | /window/:windowhandle/size               | | |
+| GET    | /cookie                                  | | |
+| POST   | /cookie                                  | cookie | |
+| DELETE | /cookie                                  | | | | |
+| DELETE | /cookie/:name                            | | |
+| GET    | /source                                  | | |
+| GET    | /title                                   | | |
+| POST   | /element                                 | using, value | |
+| POST   | /elements                                | using, value | |
+| POST   | /element/active                          | none | |
+| POST   | /element/:elementId/element              | using, value | |
+| POST   | /element/:elementId/elements             | using, value | |
+| POST   | /element/:elementId/click                | none | |
+| POST   | /element/:elementId/submit               | none | |
+| GET    | /element/:elementId/text                 | none | |
+| POST   | /element/:elementId/value                | value | |
+| POST   | /keys                                    | value | |
+| GET    | /element/:elementId/name                 | | |
+| POST   | /element/:elementId/clear                | none | |
+| GET    | /element/:elementId/selected             | | |
+| GET    | /element/:elementId/enabled              | | |
+| GET    | /element/:elementId/attribute/:name      | | |
+| GET    | /element/:elementId/equals/:otherId      | | |
+| GET    | /element/:elementId/displayed            | | |
+| GET    | /element/:elementId/location             | | |
+| GET    | /element/:elementId/location_in_view     | | |
+| GET    | /element/:elementId/size                 | | |
+| GET    | /element/:elementId/css/:propertyName    | | |
+| GET    | /orientation                             | | |
+| POST   | /orientation                             | orientation | |
+| GET    | /alert_text                              | | |
+| POST   | /alert_text                              | text | |
+| POST   | /accept_alert                            | none | |
+| POST   | /dismiss_alert                           | none | |
+| POST   | /click                                   | | button |
+| GET    | /location                                | | |
+| POST   | /location                                | location | |
+| POST   | /log                                     | type | |
+| GET    | /log/types                               | | |
+| GET    | /context                                 | | |
+| POST   | /context                                 | name | |
+| GET    | /contexts                                | | |
+
+### Appium-specific commands
+
+| method | endpoint                                 | req params | opt params |
+| ------ | ---------------------------------------- | ---------- | ---------- |
+| POST   | /appium/device/shake                     | none | |
+| GET    | /appium/device/system_time               | | |
+| POST   | /appium/device/lock                      | | seconds |
+| POST   | /appium/device/rotate                    | x, y, radius, rotation, touchCount, duration | element |
+| POST   | /appium/device/remove_app                | appId or bundleId | |
+| POST   | /appium/device/hide_keyboard             | | strategy, key, keyCode, keyName |
+| POST   | /appium/device/push_file                 | path, data | |
+| POST   | /appium/device/pull_file                 | path | |
+| POST   | /appium/device/pull_folder               | path | |
+| POST   | /appium/simulator/touch_id               | match | |
+| POST   | /appium/app/launch                       | none | |
+| POST   | /appium/app/close                        | none | |
+| POST   | /appium/app/background                   | seconds | |
+| POST   | /appium/app/strings                      | | language, stringFile |
+| POST   | /appium/element/:elementId/value         | value | |

package/src/resources/submodules/appium-xcuitest-driver/docs/getting-started/device-setup.md

@@ -0,0 +1,81 @@
+---
+title: Device Preparation
+---
+
+Before using the XCUITest driver with any device (either simulator or real device), additional
+configuration is required on the device itself.
+
+## Automatic Adjustments
+
+The driver automatically adjusts certain device settings. Currently this only applies to
+keyboard-related preferences. Some of these preferences can still be adjusted manually via the
+[Settings API](https://appium.io/docs/en/latest/guides/settings/).
+
+- _Settings -> General -> Keyboard -> Auto-Correction_ is turned OFF
+- _Settings -> General -> Keyboard -> Predictive Text_ is turned OFF
+- The keyboard tutorial is marked as complete
+- (Simulator Only) Software keyboard is turned ON
+
+## Accessibility Settings
+
+Certain accessibility settings may affect the elements shown in the application page source.
+
+- Ensure zoom is turned off in order to avoid miscalculation of element coordinates:
+
+    > _Settings_ -> _Accessibility_ -> _Zoom_ -> Turn _Zoom_ OFF
+
+- Other settings may be adjusted depending on your testing requirements:
+
+    > _Settings_ -> _Accessibility_ -> _Read & Speak_ -> _Speak Selection_
+
+## Real Devices
+
+In order to communicate with both simulators and real devices, the XCUITest driver must install
+the `WebDriverAgentRunner-Runner` (WDA) application on the device. Unlike simulators, real devices
+will not allow this by default, and have several security restrictions that need to be manually
+lifted beforehand.
+
+### Trusting the Device
+
+The device [needs to be trusted in order to appear as a run destination in Xcode](https://developer.apple.com/documentation/xcode/pairing-your-devices-with-xcode#Manage-your-real-devices-in-Xcode).
+
+#### Wired Devices
+
+1. On your macOS computer, open Xcode
+2. Physically connect the device to the computer
+3. On the device, a _Trust This Computer_ popup should appear - accept it
+
+#### Wireless tvOS Devices
+
+1. On your macOS computer, open Xcode
+2. Ensure the Apple TV is on the same network as the macOS host (no firewall blocking)
+3. On the Apple TV, enable discovery mode in _Settings_ -> _Remotes and Devices_ -> _Remote App and Device_
+4. In Xcode, open _Window_ -> _Devices and Simulators_ - the Apple TV should appear
+5. Click _Pair_, enter the PIN that appears on the Apple TV, then click _Connect_
+
+### Required Settings
+
+- The device must have [Developer Mode enabled](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)
+  (iOS/iPadOS 16+ only):
+
+    > _Settings_ -> _Privacy & Security_ -> _Developer Mode_ -> Turn _Developer Mode_ ON
+
+    You can also use the `devmodectl streaming` CLI on macOS 13+ and install development signed
+    apps to enable this mode.
+
+- UI Automation must be enabled:
+
+    > _Settings_ -> _Developer_ -> Turn _Enable UI Automation_ ON
+
+- For webview testing, Safari automation-related settings must be enabled:
+
+    > _Settings_ -> _Apps_ -> _Safari_ -> _Advanced_ -> Turn _Web Inspector_ ON
+
+    > _Settings_ -> _Apps_ -> _Safari_ -> _Advanced_ -> Turn _Remote Automation_ ON
+
+### Provisioning Profile
+
+In addition to all of the above device configuration, the WDA application must have a valid
+provisioning profile in order for it to be installable on your target device. Refer to
+[the Provisioning Profile guide](./provisioning-profile/index.md) for more details on how to
+configure this.

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

@@ -0,0 +1,36 @@
+---
+hide:
+  - toc
+
+title: Getting Started
+---
+
+Learn how to set up the driver prerequisites, install it, and prepare your device under test.
+
+<div class="grid cards" markdown>
+
+-   :octicons-checklist-16: [__System Requirements__](./system-requirements.md)
+
+    ---
+
+    Identify your target driver version and its requirements
+
+-   :material-download: [__Installation__](./installation.md)
+
+    ---
+
+    Install and load the driver 
+
+-   :material-devices: [__Device Setup__](./device-setup.md)
+
+    ---
+
+    Set up your target device for automation 
+
+-   :material-card-account-details: [__Provisioning Profile__](./provisioning-profile/index.md)
+
+    ---
+
+    Configure a provisioning profile for real device testing  
+
+</div>

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

@@ -0,0 +1,38 @@
+---
+hide:
+  - toc
+
+title: Installation
+---
+
+Provided you have set up [all the prerequisites](./system-requirements.md), or at the very least,
+a compatible macOS version with Appium, you can install the driver using Appium's
+[extension CLI](https://appium.io/docs/en/latest/cli/extensions/):
+
+```bash
+appium driver install xcuitest
+```
+
+You can also specify an exact driver version:
+
+```bash
+appium driver install xcuitest@7.16.0
+```
+
+Alternatively, if you are running a Node.js project, you can include `appium-xcuitest-driver` as
+one of your project dependencies. [Refer to the Appium documentation](https://appium.io/docs/en/latest/guides/managing-exts/#do-it-yourself-with-npm)
+for more information about this approach.
+
+## Verify the Installation
+
+In order to check that the driver was installed correctly, simply launch the Appium server:
+
+```bash
+appium
+```
+
+The server log output should include a line like the following:
+
+```
+[Appium] XCUITestDriver has been successfully loaded in 0.789s
+```

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

@@ -0,0 +1,54 @@
+---
+hide:
+  - toc
+
+title: Basic Automatic Configuration
+---
+
+If you have a paid Apple Developer account, the easiest way to create the provisioning profile is
+to use the automatic configuration strategy. There are two ways to do this:
+
+* Use the `xcodeOrgId` and `xcodeSigningId` [capabilities](../../reference/capabilities.md):
+    ```json
+    {
+      "appium:xcodeOrgId": "<Team ID>",
+      "appium:xcodeSigningId": "Apple Developer",
+      "appium:updatedWDABundleId": "<bundle id your provisioning profile can accept>"
+    }
+    ```
+* Create a `.xcconfig` file somewhere on your file system and add the following to it:
+  ```ini
+  DEVELOPMENT_TEAM = <Team ID>
+  CODE_SIGN_IDENTITY = Apple Developer
+  ```
+  Then use the `xcodeConfigFile` capability to specify the path to this file:
+  ```json
+  {
+    "appium:xcodeConfigFile": "/path/to/xcconfig/file"
+  }
+  ```
+
+Note that these are mutually exclusive strategies; use _either_ the `appium:xcodeConfigFile` capability
+_or_ the combination of `appium:xcodeOrgId` and `appium:xcodeSigningId`.
+
+* `appium:xcodeOrgId` / `DEVELOPMENT_TEAM` is a unique 10-character string generated by Apple that is
+  assigned to your team.
+    * Paid account only: To find this string, sign in to [developer.apple.com/account](https://developer.apple.com/account),
+      and click Membership in the sidebar. Your Team ID appears in the Membership Information
+      section under the team name. You can also find your Team ID listed under the "Organizational
+      Unit" field in your iPhone Developer certificate in your keychain.
+    * Paid account and free account: The result of `security find-certificate -c "Apple Development: you@email.com" -p | openssl x509 -noout -subject`
+      helps for both cases. `you@email.com` is your Apple ID.
+      The output is `subject=UID=UID, CN=Apple Development: you@email.com (USER_TEAM_ID_PAID_ACCOUNT), OU=USER_TEAM_ID_FREE_ACCOUNT, O=acocunt name, C=US` format.
+      `USER_TEAM_ID_PAID_ACCOUNT` is the `xcodeOrgId` for the paid account. The `USER_TEAM_ID_FREE_ACCOUNT` is for the free account.
+      `security find-identity -v -p codesigning` prints available accounts for code signing on your local, which are needed to print account details as above.
+* `appium:xcodeSigningId` / `CODE_SIGN_IDENTITY` is usually either `Apple Developer` or `iPhone Developer`.
+* `appium:updatedWDABundleId` is the bundle id you would like to use for the built WebDriverAgent.
+    * Appium replaces the existing placeholder of `com.facebook.WebDriverAgentRunner` in `WebDriverAgent.xcodeproj` with the given capability value.
+    * `xcodebuild` adds `.xctrunner` automatically for XCTest package. Thus, the provisioning profile you're using should have the suffix explicitly, or it can be for bundle id which has `*`.
+        * For instance, when the `appium:updatedWDABundleId` is `io.appium.WebDriverAgentRunner`, the given provisioning profile should be for `io.appium.WebDriverAgentRunner.xctrunner`, `io.appium.WebDriverAgentRunner.*` or `*`.
+    * `appium:allowProvisioningDeviceRegistration` lets XCUITest driver set `-allowProvisioningUpdates` and `-allowProvisioningDeviceRegistration` flags for the `xcodebuild` command. They will help register the target device to the matched provisioning profile if it still doesn't have the device. Please check `man xcodebuild` output for more details.
+
+Once this configuration is done, you should specify your real device UDID with the `udid` desired
+capability, after which you should be able to start your session. Check [Common Issues](./index.md#common-issues)
+if you encountered any problems.

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

@@ -0,0 +1,40 @@
+---
+hide:
+  - toc
+
+title: Basic Manual Configuration
+---
+
+There are many cases in which the basic automatic configuration is not enough. Often this happens
+when the development account being used is a "Free" one, in which case it is not possible to create
+a wildcard provisioning profile.
+
+You can confirm this by opening the WDA project in Xcode. The issue will manifest as something like
+an error that Xcode failed to create provisioning profile:
+
+![No provisioning profile](./assets/images/no-prov-prof.png)
+
+The easiest way around this is to create a new project:
+
+![Create new project](./assets/images/create-new-project.png)
+
+The type does not matter, other than it being "iOS". "Single View Application" is the easiest:
+
+![Create single page](./assets/images/create-single-page.png)
+
+The important part is to use a unique "Product Name" and "Organization Name". Also, at this point,
+specify your "Team".
+
+![Setup bundle](./assets/images/set-up-bundle.png)
+
+You can confirm that the provisioning profile was created by looking at the "Project" tab:
+
+![Project pane](./assets/images/project-prov-prof.png)
+
+Or by going into your account preferences and seeing the provisioning profile:
+
+![Check provisioning profile](./assets/images/check-prov-prof.png)
+
+At this point you have a valid provisioning profile. Make note of the bundle identifier
+you associated with it, and add that in the `updatedWDABundleId` capability for your tests.
+Then follow the [initial instructions for automatic configuration](./auto-config.md).

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

@@ -0,0 +1,49 @@
+---
+hide:
+  - toc
+
+title: Full Manual Configuration
+---
+
+The provisioning profile can also be manually associated with the WDA project. Keep in mind that
+this will have to be done each time WDA is updated (such as when updating the XCUITest driver),
+and is _not_ recommended:
+
+* In the terminal, open the directory where WDA is located. Run the following to set the project up:
+  ```bash
+  mkdir -p Resources/WebDriverAgent.bundle
+  ```
+* Open `WebDriverAgent.xcodeproj` in Xcode. This will likely open a screen with an empty editor.
+* In the file browser on the left side, select the root _WebDriverAgent_ project, which will open
+  it in the editor. Then, under _Targets_, select _WebDriverAgentRunner_ (or
+  _WebDriverAgentRunner\_tvOS_ for tvOS), and switch to the _Signing & Capabilities_ tab.
+* Check _Automatically manage signing_, and then select your _Team_ (you may need to first sign
+  into Xcode). The outcome should be similar to the following:
+
+    ![WebDriverAgent in Xcode project](./assets/images/xcode-config.png)
+
+* Xcode will likely fail to create a provisioning profile due to an invalid bundle identifier:
+
+    ![Xcode provisioning fail](./assets/images/xcode-facebook-fail.png)
+
+* Change the _Bundle Identifier_ from `com.facebook.WebDriverAgentRunner` to something that Xcode
+  will accept. You can also do this in the _Build Settings_ tab:
+
+    ![Xcode bundle id](./assets/images/xcode-bundle-id.png)
+  
+!!! note
+
+    Versions of Xcode older than 11 have a different naming convention. This feature may not work
+    for a package which is built by Xcode versions below 12.
+
+* If your bundle identifier is accepted, you should see that Xcode has created a provisioning
+  profile and all is well:
+
+    ![Xcode provisioning profile](./assets/images/xcode-facebook-succeed.png)
+
+* Finally, you can verify that everything works:
+    * Select the scheme as _Product -> Scheme -> WebDriverAgentRunner_
+    * Select your real device in _Product -> Destination_
+    * Select _Product -> Test_ to build and install the WDA app
+
+Check [Common Issues](./index.md#common-issues) if you encountered any problems.