appium-mcp 0.0.1 → 1.1.5

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/uiauto2-driver.md

@@ -0,0 +1,148 @@
+---
+title: Install the UiAutomator2 Driver
+---
+
+You can't do much with Appium unless you have a [driver](../intro/drivers.md), which is an
+interface that allows Appium to automate a particular platform.
+
+!!! info
+
+```
+For this quickstart guide, we're going to be automating an app on the Android platform, because
+the system requirements for Android automation via Appium are the same as for Appium itself
+(whereas the iOS driver, for example, requires you to be using macOS).
+```
+
+The driver we're going to use is called the UiAutomator2
+Driver. It's worth visiting that driver's
+documentation and bookmarking it, because it will be an invaluable reference down the line.
+
+## Set up Android automation requirements
+
+According to the driver, in addition to a working Appium server, we also need to set up the following:
+
+### Android SDK
+
+- The easiest way to set up the Android SDK requirements is by downloading [Android Studio](https://developer.android.com/studio).
+  We need to use its SDK manager (_Settings -> Languages & Frameworks -> Android SDK_)
+  to download the following items:
+  - Android SDK Platform (select whichever Android platform we want to automate, for example, API level 30)
+  - Android SDK Platform-Tools
+- If you wish, you can also download these items without Android Studio:
+  - Android SDK Platform can be downloaded using `sdkmanager` included in [Android command-line tools](https://developer.android.com/studio#command-line-tools-only)
+  - [Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools)
+- Set up the `ANDROID_HOME` environment variable to point to the directory where the Android SDK is
+  installed. You can usually find the path to this directory in the Android Studio SDK manager. It
+  will contain the `platform-tools` and other directories.
+
+### Java JDK
+
+- Install the Java JDK (for the most recent Android API levels, JDK 9 is required, otherwise JDK
+  8 is required). You can download this from [Oracle](https://jdk.java.net/) or [Adoptium](https://adoptium.net/en-GB/temurin/releases/).
+  Make sure you get the JDK and not the JRE.
+- Set up the `JAVA_HOME` environment variable to point to the JDK home directory. It will contain
+  the `bin`, `include`, and other directories.
+
+### Prepare the Device
+
+- If using an emulator, use Android Studio to create and launch an Android Virtual Device (AVD).
+  You may need to download the system images for the API level of the emulator you want to
+  create. Using the AVD creation wizard in Android Studio is generally the easiest way to do all of
+  this.
+- If using a real device, you should [set it up for development and enable USB Debugging](https://developer.android.com/studio/debug/dev-options).
+- With the emulator or device connected, you can run `adb devices` (via the binary located at
+  `$ANDROID_HOME/platform-tools/adb`) to verify that your device shows up as connected.
+
+Once your device shows up as connected in `adb`, and you've verified that the environment variables
+are set up correctly, you should be good to go! If you ran into problems with any of these steps,
+refer to the driver documentation, or the various Android or Java documentation sites as necessary.
+
+Also, congratulations: whether or not you intended to, you now have the Android developer toolchain
+set up on your system, so you can get busy making Android apps if you want!
+
+## Install the driver itself
+
+### Standard Install
+
+Like all Appium drivers, the UiAutomator2 driver is installed via the [Appium Extension CLI](../reference/cli/extensions.md).
+Since UiAutomator2 is maintained by the core Appium team, it has an 'official' driver name
+(`uiautomator2`), which makes the installation simpler.
+
+Before installing, make sure your Appium server is _not_ running (if it is, quit it with _Ctrl-C_).
+Then run the following command:
+
+```bash
+appium driver install uiautomator2
+```
+
+It should produce output that looks something like:
+
+```
+Attempting to find and install driver 'uiautomator2'
+✔ Installing 'uiautomator2' using NPM install spec 'appium-uiautomator2-driver'
+Driver uiautomator2@2.0.5 successfully installed
+- automationName: UiAutomator2
+- platformNames: ["Android"]
+```
+
+Note how the installation process specifies what platforms is the driver valid for (in this case,
+`Android`), and what automation name (the `appium:automationName` [capability](../guides/caps.md))
+must be used to select this driver for use during an Appium session (in this case, `UiAutomator2`).
+
+!!! note
+
+```
+In this quickstart we have used the [Extension CLI](../reference/cli/extensions.md) to install the
+UiAutomator2 driver, but if you are incorporating Appium into a Node.js project, you might
+prefer to use `npm` to manage Appium and its connected drivers. To learn more about this
+technique, visit the guide on [managing Appium extensions](../guides/managing-exts.md).
+```
+
+### Batch Install
+
+You may want to use Appium with more than one driver. One way to accomplish this is to run
+`appium driver install <driver-name>` for each individual driver, but you can also install multiple
+drivers in one go:
+
+```
+appium setup
+```
+
+Running this will install Appium's mobile-specific drivers: UiAutomator2, [XCUITest](https://appium.github.io/appium-xcuitest-driver/)
+(only if running macOS), and [Espresso](https://github.com/appium/appium-espresso-driver).
+
+You can also use this command to batch install drivers for desktop applications or desktop browsers.
+For more details on this, refer to the [Setup command documentation](../reference/cli/setup.md).
+
+### Validating the Install
+
+The UiAutomator2 driver, like all official Appium drivers, comes with the Appium Doctor tool, which
+allows validating whether all prerequisites have been set up correctly:
+
+```
+appium driver doctor uiautomator2
+```
+
+This guide has focused on essential requirements, so Appium Doctor may suggest one or more optional
+fixes. But if you see `0 required fixes needed`, that means everything is set up!
+
+Now, start the Appium server again (run `appium`), and you should see that the newly-installed
+driver is listed as available:
+
+```
+[Appium] Available drivers:
+[Appium]   - uiautomator2@2.0.5 (automationName 'UiAutomator2')
+```
+
+With the Android setup complete and the UiAutomator2 driver installed, you're ready to write your
+first test! Now select your preferred language and give it a shot:
+
+<div class="grid cards" markdown>
+
+- :material-language-javascript: [**JavaScript**](./test-js.md)
+- :material-language-java: [**Java**](./test-java.md)
+- :material-language-python: [**Python**](./test-py.md)
+- :material-language-ruby: [**Ruby**](./test-rb.md)
+- :material-dot-net: [**.NET C#**](./test-dotnet.md)
+
+</div>

package/src/resources/submodules/appium/packages/appium/docs/zh/reference/api/appium.md

@@ -0,0 +1,395 @@
+---
+title: Appium Protocol
+---
+
+<style>
+  ul[data-md-component="toc"] .md-nav {
+    display: none;
+  }
+</style>
+
+The following is a list of endpoints supported in Appium, that are defined in the Appium extension
+of the W3C WebDriver protocol.
+
+### getAppiumSessions
+
+```
+GET /appium/sessions
+```
+
+Retrieves information about all active server sessions.
+
+!!! info
+
+    The `session_discovery` [insecure feature](../../guides/security.md) must be enabled to use this endpoint.
+
+#### Response
+
+`TimestampedMultiSessionData[]` - an array of session data objects. Each object has the following properties:
+
+| Name           | Description                                                                    | Type   |
+| -------------- | ------------------------------------------------------------------------------ | ------ |
+| `capabilities` | Session capabilities                                                           | object |
+| `created`      | Session creation time (in milliseconds) as a Unix timestamp | number |
+| `id`           | Session ID                                                                     | string |
+
+### getAppiumSessionCapabilities
+
+```
+GET /session/:sessionId/appium/capabilities
+```
+
+Retrieves the [session capabilities](../../guides/caps.md).
+
+#### Response
+
+`SessionCapabilities` - an object with the following properties:
+
+| Name           | Description          | Type   |
+| -------------- | -------------------- | ------ |
+| `capabilities` | Session capabilities | object |
+
+### getSettings
+
+```
+GET /session/:sessionId/appium/settings
+```
+
+Retrieves the [current session settings](../../guides/settings.md).
+
+#### Response
+
+`Settings` - an object containing setting names and their values
+
+### updateSettings
+
+```
+POST /session/:sessionId/appium/settings
+```
+
+Updates the specified session settings. Any other previously set settings will remain unchanged.
+
+#### Parameters
+
+| Name       | Description                                                          | Type   |
+| ---------- | -------------------------------------------------------------------- | ------ |
+| `settings` | Object containing the names and values of the settings to be updated | object |
+
+#### Response
+
+`null`
+
+### listCommands
+
+```
+GET /session/:sessionId/appium/commands
+```
+
+Retrieves the URL endpoints and WebDriver BiDi commands supported in the current session.
+
+#### Response
+
+`ListCommandsResponse` - an object containing all supported endpoints and BiDi commands, grouped by
+their origin (base Appium, driver-specific, or plugin-specific). Refer to [the type definition file](https://github.com/appium/appium/blob/master/packages/types/lib/command.ts)
+for a detailed structure of this object.
+
+### listExtensions
+
+```
+GET /session/:sessionId/appium/extensions
+```
+
+Retrieves the [execute methods](../../guides/execute-methods.md) supported in the current session.
+
+#### Response
+
+`ListExtensionsResponse` - an object containing all supported execute methods, grouped by their
+origin (driver-specific or plugin-specific). Refer to [the type definition file](https://github.com/appium/appium/blob/master/packages/types/lib/command.ts)
+for a detailed structure of this object.
+
+### getLogEvents
+
+```
+POST /session/:sessionId/appium/events
+```
+
+Retrieves events that have occurred in the current session. By default, only driver command
+executions are recorded in the log, but drivers or plugins may define additional event types.
+Clients can log events by using the [`logCustomEvent`](#logcustomevent) endpoint.
+
+#### Parameters
+
+| Name    | Description                                     | Type                    |
+| ------- | ----------------------------------------------- | ----------------------- |
+| `type?` | One or more types to filter the returned events | string or array<string> |
+
+#### Response
+
+`EventHistory` - an object whose keys correspond to the types of logged events. Event types can be
+grouped into three categories, as shown by the following example response:
+
+```json
+{
+  "commands": [
+    { "cmd": "getStatus", "startTime": 1756887645447, "endTime": 1756887645454 }
+  ],
+  "driverevent": [1756887645454],
+  "namespace:event": [1756887645454]
+}
+```
+
+- The `commands` key is always included in the endpoint response. Its value is an array of objects,
+  where each object includes 3 parameters:
+  - `cmd`: name of the executed command
+  - `startTime`: the command execution start time (in milliseconds), as a Unix timestamp
+  - `endTime`: the command execution end time (in milliseconds), as a Unix timestamp
+- Other non-namespaced keys are specific to driver/plugin implementations. Their value is an array
+  of event times (in milliseconds), as Unix timestamps.
+- Namespaced keys can be added using the `logCustomEvent` endpoint, but may also be provided by
+  drivers/plugins. Their value is an array of event times (in milliseconds), as Unix timestamps.
+
+### logCustomEvent
+
+```
+POST /session/:sessionId/appium/log_event
+```
+
+Logs a custom event, which can be retrieved using the [`getLogEvents`](#getlogevents) endpoint.
+
+#### Parameters
+
+| Name     | Description                                                                | Type   |
+| -------- | -------------------------------------------------------------------------- | ------ |
+| `vendor` | Name of the namespace (vendor) used to prefix the event | string |
+| `event`  | Name of the event                                                          | string |
+
+#### Response
+
+`null`
+
+### getDeviceTime
+
+```
+POST /session/:sessionId/appium/device/system_time
+```
+
+Retrieves the current system time of the device under test.
+
+#### Parameters
+
+| Name      | Description                              | Type   | Default                |
+| --------- | ---------------------------------------- | ------ | ---------------------- |
+| `format?` | Format to use for the returned timestamp | string | `YYYY-MM-DDTHH:mm:ssZ` |
+
+#### Response
+
+`string` - the device time
+
+### activateApp
+
+```
+POST /session/:sessionId/appium/device/activate_app
+```
+
+Activates an app on the device under test.
+
+#### Parameters
+
+| Name                  | Description                                                 | Type    |
+| --------------------- | ----------------------------------------------------------- | ------- |
+| `appId` or `bundleId` | App identifier such as Android app package or iOS bundle ID | string  |
+| `options?`            | Driver-specific launch options                              | unknown |
+
+#### Response
+
+`void`
+
+### terminateApp
+
+```
+POST /session/:sessionId/appium/device/terminate_app
+```
+
+Terminates an app on the device under test.
+
+#### Parameters
+
+| Name                  | Description                                                 | Type    |
+| --------------------- | ----------------------------------------------------------- | ------- |
+| `appId` or `bundleId` | App identifier such as Android app package or iOS bundle ID | string  |
+| `options?`            | Driver-specific termination options                         | unknown |
+
+#### Response
+
+`void`
+
+### queryAppState
+
+```
+POST /session/:sessionId/appium/device/app_state
+```
+
+Retrieves the state of an app on the device under test.
+
+#### Parameters
+
+| Name                  | Description                                                 | Type   |
+| --------------------- | ----------------------------------------------------------- | ------ |
+| `appId` or `bundleId` | App identifier such as Android app package or iOS bundle ID | string |
+
+#### Response
+
+`number` - an integer value indicating the app state:
+
+| Number | App State                       |
+| ------ | ------------------------------- |
+| `0`    | Not installed                   |
+| `1`    | Not running                     |
+| `2`    | Running in background suspended |
+| `3`    | Running in background           |
+| `4`    | Running in foreground           |
+
+### installApp
+
+```
+POST /session/:sessionId/appium/device/install_app
+```
+
+Installs an app on the device under test.
+
+#### Parameters
+
+| Name       | Description                                   | Type    |
+| ---------- | --------------------------------------------- | ------- |
+| `appPath`  | Absolute local filepath or URL to an app file | string  |
+| `options?` | Driver-specific install options               | unknown |
+
+#### Response
+
+`void`
+
+### removeApp
+
+```
+POST /session/:sessionId/appium/device/remove_app
+```
+
+Uninstalls an app from the device under test.
+
+#### Parameters
+
+| Name                  | Description                                                 | Type    |
+| --------------------- | ----------------------------------------------------------- | ------- |
+| `appId` or `bundleId` | App identifier such as Android app package or iOS bundle ID | string  |
+| `options?`            | Driver-specific uninstall options                           | unknown |
+
+#### Response
+
+`boolean` - `true` if uninstall was successful, otherwise `false`
+
+### isAppInstalled
+
+```
+POST /session/:sessionId/appium/device/app_installed
+```
+
+Determines if an app is installed on the device under test.
+
+#### Parameters
+
+| Name                  | Description                                                 | Type   |
+| --------------------- | ----------------------------------------------------------- | ------ |
+| `appId` or `bundleId` | App identifier such as Android app package or iOS bundle ID | string |
+
+#### Response
+
+`boolean` - `true` if app is installed, otherwise `false`
+
+### hideKeyboard
+
+```
+POST /session/:sessionId/appium/device/hide_keyboard
+```
+
+Attempts to hide the virtual keyboard on the device under test.
+
+#### Parameters
+
+| Name        | Description                                         | Type   |
+| ----------- | --------------------------------------------------- | ------ |
+| `key?`      | Text of a key to use to hide the keyboard           | string |
+| `keyCode?`  | Key code to trigger to hide the keyboard            | string |
+| `keyName?`  | Name of a key to use to hide the keyboard           | string |
+| `strategy?` | Driver-specific name of a hiding strategy to follow | string |
+
+#### Response
+
+`boolean` - `true` if the operation was successful, otherwise `false`. Note that some platforms
+may never return a `false` value.
+
+### isKeyboardShown
+
+```
+GET /session/:sessionId/appium/device/is_keyboard_shown
+```
+
+Determines if the virtual keyboard is shown on the device under test.
+
+#### Response
+
+`boolean` - `true` if the keyboard is shown, otherwise `false`
+
+### pushFile
+
+```
+POST /session/:sessionId/appium/device/push_file
+```
+
+Pushes data to a file on the device under test.
+
+#### Parameters
+
+| Name   | Description                                     | Type   |
+| ------ | ----------------------------------------------- | ------ |
+| `data` | Base64-encoded data to be written to the file   | string |
+| `path` | Remote path on the device to create the file at | string |
+
+#### Response
+
+`void`
+
+### pullFile
+
+```
+POST /session/:sessionId/appium/device/pull_file
+```
+
+Retrieves data from a file on the device under test.
+
+#### Parameters
+
+| Name   | Description                           | Type   |
+| ------ | ------------------------------------- | ------ |
+| `path` | Remote path of the file on the device | string |
+
+#### Response
+
+`string` - the Base64-encoded contents of the file
+
+### pullFolder
+
+```
+POST /session/:sessionId/appium/device/pull_folder
+```
+
+Retrieves data from a directory on the device under test.
+
+#### Parameters
+
+| Name   | Description                                | Type   |
+| ------ | ------------------------------------------ | ------ |
+| `path` | Remote path of the directory on the device | string |
+
+#### Response
+
+`string` - the Base64-encoded zip file of the directory contents

package/src/resources/submodules/appium/packages/appium/docs/zh/reference/api/bidi.md

@@ -0,0 +1,71 @@
+---
+title: WebDriver BiDi Protocol
+---
+
+<style>
+  ul[data-md-component="toc"] .md-nav {
+    display: none;
+  }
+</style>
+
+The following is a list of [W3C WebDriver BiDi protocol](https://w3c.github.io/webdriver-bidi/)
+commands supported in Appium.
+
+Unlike other protocols that specify URL endpoints, the WebDriver BiDi protocol specifies commands
+sent as a websocket event, that both drivers and clients can emit or listen to.
+
+### bidiStatus
+
+```
+session.status
+```
+
+> WebDriver BiDi documentation: [session.status](https://w3c.github.io/webdriver-bidi/#command-session-status)
+
+Retrieves the current status of the Appium server.
+
+#### Response
+
+[`GetStatusResult`](./webdriver.md#response_2)
+
+### bidiSubscribe
+
+```
+session.subscribe
+```
+
+> WebDriver BiDi documentation: [session.subscribe](https://w3c.github.io/webdriver-bidi/#command-session-subscribe)
+
+Subscribes to one or more BiDi events.
+
+#### Parameters
+
+| Name        | Description                                                                                                                              | Type                                                         | Default |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------- |
+| `contexts?` | Contexts in which to subscribe to the specified events. By default, the global context scope is applied. | string[] | `['']`  |
+| `events`    | Names of events to subscribe to                                                                                                          | string[] |         |
+
+#### Response
+
+`null`
+
+### bidiUnsubscribe
+
+```
+session.unsubscribe
+```
+
+> WebDriver BiDi documentation: [session.unsubscribe](https://w3c.github.io/webdriver-bidi/#command-session-unsubscribe)
+
+Unsubscribes from one or more BiDi events.
+
+#### Parameters
+
+| Name        | Description                                                                                                                          | Type                                                         | Default |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------- |
+| `contexts?` | Contexts in which to unsubscribe from the specified events. By default, the global scope is applied. | string[] | `['']`  |
+| `events`    | Names of events to unsubscribe from                                                                                                  | string[] |         |
+
+#### Response
+
+`null`

package/src/resources/submodules/appium/packages/appium/docs/zh/reference/api/index.md

@@ -0,0 +1,30 @@
+---
+hide:
+  - toc
+
+title: API Endpoints
+---
+
+Here you can find various API endpoints exposed by the main Appium module through its base driver,
+as well as the endpoints added or modified by official plugins.
+
+Since all Appium drivers inherit the Appium base driver, they support all of its endpoints as well,
+but may additionally define endpoints of their own. Refer to the documentation of your
+[Appium driver](../../ecosystem/drivers.md) to learn about its specific endpoints.
+
+The recommended way of calling these API endpoints is through your [Appium client](../../ecosystem/clients.md).
+Refer to the documentation of your client for the exact commands used to invoke specific endpoints.
+
+All endpoints are grouped by their protocol, with an additional group for plugin endpoints:
+
+<div class="grid cards" markdown>
+
+- [**WebDriver Protocol**](./webdriver.md)
+- [**WebDriver BiDi Protocol**](./bidi.md)
+- [**JSON Wire Protocol**](./jsonwp.md)
+- [**Mobile JSON Wire Protocol**](./mjsonwp.md)
+- [**Appium Protocol**](./appium.md)
+- [**Other Protocols**](./others.md)
+- [**Endpoints Used by Official Plugins**](./plugins.md)
+
+</div>