appium-mcp 0.0.1 → 1.1.4

package/src/resources/submodules/appium/packages/appium/docs/en/quickstart/test-rb.md

@@ -0,0 +1,83 @@
+---
+hide:
+  - toc
+
+title: Write a Test (Ruby)
+---
+
+
+The [AppiumLib](https://github.com/appium/ruby_lib) and the [AppiumLibCore](https://github.com/appium/ruby_lib_core) (**recommended**) are official Appium client libraries in Ruby, which are available via gem under the [appium_lib](https://rubygems.org/gems/appium_lib) and the [appium_lib_core](https://rubygems.org/gems/appium_lib_core) package names. The appium_lib_core inherits from the Selenium Ruby Binding, and the appium_lib inherits from the appium_lib_core, so installing these libraries include the selenium binding. We recommend `appium_lib_core` if you need a less complex client-side solution. The `appium_lib` has some useful methods the core does not have, but for the cost of greater complexity and historical methods which may not work in the latest environment.
+
+As the first step, let's initialize a Gemfile to manage the dependency:
+
+```bash
+bundle init
+```
+
+Then, you could add Appium Ruby Client dependency as below:
+
+```bash
+bundle add appium_lib_core
+# or
+# bundle add appium_lib
+```
+
+Test code example below uses `test-unit` module, thus please run:
+
+```bash
+bundle add test-unit
+```
+
+Once these steps has done, your `Gemfile` file should include:
+
+```ruby title="Gemfile"
+--8<-- "./sample-code/quickstarts/rb/Gemfile"
+```
+
+The `appium_lib_core` is the main part as an Appium client.
+`appium_lib` has various helper methods, but the driver instance was ordinary designed to be used as a global variable. It could causes an issue to handle the instance.
+`appium_lib_core` does not have such a global variable.
+
+This example is by the `appium_lib_core` with `test-unit` gem module.
+Tes code in `appium_lib` should be similar.
+
+```ruby title="test.rb"
+--8<-- "./sample-code/quickstarts/rb/test.rb"
+```
+
+!!! note
+
+    It's not within the scope of this guide to give a complete run-down on the Ruby client
+    library or everything that's happening here, so we'll leave the code itself unexplained in detail for now.
+
+    - You may want to read up particularly on Appium [Capabilities](../guides/caps.md).
+    - [functional test code](https://github.com/appium/ruby_lib_core/tree/master/test/functional) in the appium_lib_core GitHub repository should help to find more working example.
+    - Documentation [appium_lib_core](https://www.rubydoc.info/github/appium/ruby_lib_core) and [appium_lib](https://www.rubydoc.info/github/appium/ruby_lib) also helps to find available methods.
+
+!!! note
+
+    The sample code is available from [GitHub Appium repository](https://github.com/appium/appium/tree/master/packages/appium/sample-code/quickstarts/rb).
+
+
+Basically, this code is doing the following:
+
+1. Defining a set of "Capabilities" (parameters) to send to the Appium server so Appium knows what
+kind of thing you want to automate.
+1. Starting an Appium session on the built-in Android settings app.
+1. Finding the "Apps" list item and clicking it.
+1. Pausing for a moment purely for visual effect.
+1. Ending the Appium session.
+
+That's it! Let's give it a try. Before you run the test, make sure that you have an Appium server
+running in another terminal session, otherwise you'll get an error about not being able to connect
+to one. Then, you can execute the script:
+
+```bash
+# Please run "bundle install" first if your environment has not run the installation command yet.
+bundle exec ruby test.rb
+```
+
+If all goes well, you'll see the Settings app open up and navigate to the "Apps" view before the
+app closes again.
+
+Congratulations, you've started your Appium journey! Read on for some [next steps](./next-steps.md) to explore.

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

@@ -0,0 +1,144 @@
+---
+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](https://github.com/appium/appium-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/en/reference/api/appium.md

@@ -0,0 +1,394 @@
+---
+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/en/reference/api/bidi.md

@@ -0,0 +1,70 @@
+---
+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`