@appium/mcp-documentation 1.0.3 → 1.0.5

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>

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

@@ -0,0 +1,215 @@
+---
+title: JSON Wire Protocol
+---
+
+<style>
+  ul[data-md-component="toc"] .md-nav {
+    display: none;
+  }
+</style>
+
+The following is a list of legacy [JSON Wire Protocol (JSONWP)](https://www.selenium.dev/documentation/legacy/json_wire_protocol/)
+endpoints supported in Appium.
+
+### getSession
+
+```
+GET /session/:sessionId
+```
+
+> JSONWP documentation: [/session/:sessionId](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionid)
+
+Retrieves the capabilities of the current session.
+
+Appium implements a modified version of this endpoint. If the `appium:eventTimings` capability is
+set to `true`, the returned result will additionally include the `events` key, whose value contains
+the event history and timings.
+
+!!! warning "Deprecated"
+
+    For retrieving capabilities, please use [`getAppiumSessionCapabilities`](./appium.md#getappiumsessioncapabilities).<br />
+    For retrieving event history, please use [`getLogEvents`](./appium.md#getlogevents).
+
+#### Response
+
+`Capabilities` - an object containing the session capabilities, and the event history (if applicable)
+
+### availableIMEEngines
+
+```
+GET /session/:sessionId/ime/available_engines
+```
+
+> JSONWP documentation: [/session/:sessionId/ime/available_engines](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeavailable_engines)
+
+Retrieves all IME (input method editor) engines available on the device under test.
+
+!!! warning "Deprecated"
+
+    In the future, this endpoint will be moved to the [UiAutomator2 and Espresso drivers](../../ecosystem/drivers.md)
+
+#### Response
+
+`string[]` - a list of available IME engines
+
+### getActiveIMEEngine
+
+```
+GET /session/:sessionId/ime/active_engine
+```
+
+> JSONWP documentation: [/session/:sessionId/ime/active_engine](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactive_engine)
+
+Retrieves the name of the active IME engine.
+
+!!! warning "Deprecated"
+
+    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
+
+#### Response
+
+`string` - the name of the active IME engine
+
+### isIMEActivated
+
+```
+GET /session/:sessionId/ime/activated
+```
+
+> JSONWP documentation: [/session/:sessionId/ime/activated](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivated)
+
+Determines if IME input is available and active.
+
+!!! warning "Deprecated"
+
+    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
+
+#### Response
+
+`boolean` - `true` if IME is active, otherwise `false`
+
+### deactivateIMEEngine
+
+```
+POST /session/:sessionId/ime/deactivate
+```
+
+> JSONWP documentation: [/session/:sessionId/ime/deactivate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimedeactivate)
+
+Deactivates the currently active IME engine.
+
+!!! warning "Deprecated"
+
+    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
+
+#### Response
+
+`null`
+
+### activateIMEEngine
+
+```
+POST /session/:sessionId/ime/activate
+```
+
+> JSONWP documentation: [/session/:sessionId/ime/activate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivate)
+
+Activates an IME engine.
+
+!!! warning "Deprecated"
+
+    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
+
+#### Parameters
+
+| Name     | Description                        | Type   |
+| -------- | ---------------------------------- | ------ |
+| `engine` | Name of the IME engine to activate | string |
+
+#### Response
+
+`null`
+
+### getOrientation
+
+```
+GET /session/:sessionId/orientation
+```
+
+> JSONWP documentation: [/session/:sessionId/orientation](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidorientation)
+
+Retrieves the current orientation of the device under test.
+
+#### Response
+
+`string` - either `PORTRAIT` or `LANDSCAPE`
+
+### setOrientation
+
+```
+POST /session/:sessionId/orientation
+```
+
+> JSONWP documentation: [/session/:sessionId/orientation](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidorientation)
+
+Sets the orientation of the device under test.
+
+#### Parameters
+
+| Name          | Description                                                                                             | Type   |
+| ------------- | ------------------------------------------------------------------------------------------------------- | ------ |
+| `orientation` | New device orientation. Supported values are `PORTRAIT` or `LANDSCAPE`. | string |
+
+#### Response
+
+`null`
+
+### getGeoLocation
+
+```
+GET /session/:sessionId/location
+```
+
+> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
+
+Retrieves the current location of the device under test.
+
+!!! warning "Deprecated"
+
+    Please use driver-specific extension methods such as `mobile: getGeoLocation` or
+    `mobile: getSimulatedLocation`
+
+#### Response
+
+`Location` - an object with the following properties:
+
+| Name        | Description                      | Type   |
+| ----------- | -------------------------------- | ------ |
+| `altitude`  | Altitude of the device location  | number |
+| `latitude`  | Latitude of the device location  | number |
+| `longitude` | Longitude of the device location | number |
+
+### setGeoLocation
+
+```
+POST /session/:sessionId/location
+```
+
+> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
+
+Sets the current location of the device under test.
+
+!!! warning "Deprecated"
+
+    Please use driver-specific extension methods such as `mobile: setGeoLocation` or
+    `mobile: setSimulatedLocation`
+
+#### Parameters
+
+| Name       | Description                                 | Type                      |
+| ---------- | ------------------------------------------- | ------------------------- |
+| `location` | New device latitude, longitude and altitude | [`Location`](#response_6) |
+
+#### Response
+
+`null`