appium-mcp 0.0.1 → 1.1.5

package/src/resources/submodules/appium/packages/appium/docs/en/ecosystem/drivers.md

@@ -0,0 +1,207 @@
+---
+title: Appium Drivers
+---
+
+You can't use Appium without a driver! Here you can find a list of all known Appium drivers,
+along with their installation commands and links to their documentation.
+
+To learn more about drivers, check out the [Driver Intro](../intro/drivers.md).
+
+!!! note
+
+    If you maintain an Appium driver that you would like to be listed here, feel free to create a PR!
+
+## Official Drivers
+
+These drivers are currently maintained by the Appium team:
+
+### [Chromium](https://github.com/appium/appium-chromium-driver)
+
+* Target: Desktop and mobile Chromium browsers (Chrome, Microsoft Edge, etc.)
+* Mode: Web
+
+```sh title="Install This Driver"
+appium driver install chromium
+```
+
+### [Espresso](https://github.com/appium/appium-espresso-driver)
+
+* Target: Android applications
+* Mode: Native
+
+```sh title="Install This Driver"
+appium driver install espresso
+```
+
+### [Gecko](https://github.com/appium/appium-geckodriver)
+
+* Target: Desktop and mobile Gecko browsers (Firefox)
+* Mode: Web
+
+```sh title="Install This Driver"
+appium driver install gecko
+```
+
+### [Mac2](https://github.com/appium/appium-mac2-driver)
+
+* Target: macOS applications
+* Mode: Native
+
+```sh title="Install This Driver"
+appium driver install mac2
+```
+
+### [Safari](https://github.com/appium/appium-safari-driver)
+
+* Target: Desktop and mobile Safari browsers
+* Mode: Web
+
+```sh title="Install This Driver"
+appium driver install safari
+```
+
+### [UiAutomator2](https://github.com/appium/appium-uiautomator2-driver)
+
+* Target: Android, Android TV, Android Wear applications
+* Modes: Native, Hybrid, Web
+
+```sh title="Install This Driver"
+appium driver install uiautomator2
+```
+
+### [Windows](https://github.com/appium/appium-windows-driver)
+
+!!! warning
+
+    Only the Node.js-based driver part is maintained by the Appium team. The server part
+    (WinAppDriver executable) is provided by Microsoft, but has not been maintained since 2022.
+
+* Target: Windows applications
+* Mode: Native
+
+```sh title="Install This Driver"
+appium driver install windows
+```
+
+### [XCUITest](https://appium.github.io/appium-xcuitest-driver/)
+
+* Target: iOS, iPadOS, tvOS applications
+* Modes: Native, Hybrid, Web
+
+```sh title="Install This Driver"
+appium driver install xcuitest
+```
+
+## Other Drivers
+
+These drivers are not maintained by the Appium team and can be used to target other platforms:
+
+### [Flutter](https://github.com/appium/appium-flutter-driver)
+
+* Target: iOS and Android applications built with Flutter
+* Mode: Native
+* Supported by: Appium Team / Community
+
+```sh title="Install This Driver"
+appium driver install --source=npm appium-flutter-driver
+```
+
+### [Flutter Integration](https://github.com/AppiumTestDistribution/appium-flutter-integration-driver)
+
+* Target: iOS and Android applications built with Flutter
+* Mode: Native
+* Supported by: Community / `@AppiumTestDistribution`
+
+```sh title="Install This Driver"
+appium driver install --source=npm appium-flutter-integration-driver
+```
+
+### [LG WebOS](https://github.com/headspinio/appium-lg-webos-driver)
+
+* Target: LG TV web applications
+* Mode: Web
+* Supported by: HeadSpin
+
+```sh title="Install This Driver"
+appium driver install --source=npm appium-lg-webos-driver
+```
+
+### [Linux](https://github.com/fantonglang/appium-linux-driver)
+
+!!! warning
+
+    This driver has not been maintained since 2022 and requires a custom Appium installation
+
+* Target: Linux applications
+* Mode: Native
+* Supported by: `@fantonglang`
+
+```sh title="Install This Driver"
+git clone https://github.com/fantonglang/appium
+cd appium
+yarn install
+node ./
+```
+
+### [NovaWindows](https://github.com/AutomateThePlanet/appium-novawindows-driver)
+
+!!! info
+
+    This driver is recommended as a drop-in replacement for the partially unmaintained
+    [Windows driver](#windows)
+
+* Target: Windows applications
+* Mode: Native
+* Supported by: Community / Automate The Planet
+
+```sh title="Install This Driver"
+appium driver install --source=npm appium-novawindows-driver
+```
+
+### [Roku](https://github.com/headspinio/appium-roku-driver)
+
+* Target: Roku channels (applications)
+* Mode: Native
+* Supported by: HeadSpin
+
+```sh title="Install This Driver"
+appium driver install --source=npm @headspinio/appium-roku-driver
+```
+
+### [Tizen](https://github.com/Samsung/appium-tizen-driver)
+
+!!! warning
+
+    This driver has not been maintained since 2020 and is only compatible with Appium 1
+
+* Target: Tizen applications
+* Mode: Native
+* Supported by: Community / Samsung
+
+```sh title="Install This Driver"
+npm install appium-tizen-driver
+```
+
+### [TizenTV](https://github.com/headspinio/appium-tizen-tv-driver)
+
+* Target: Tizen TV web applications
+* Mode: Web
+* Supported by: HeadSpin
+
+```sh title="Install This Driver"
+appium driver install --source=npm appium-tizen-tv-driver
+```
+
+### [You.i Engine](https://github.com/YOU-i-Labs/appium-youiengine-driver)
+
+!!! warning
+
+    This driver has not been maintained since 2022 and is only compatible with Appium 1
+
+* Target: iOS, Android, macOS, Linux, tvOS applications built with You.i Engine
+* Mode: Native
+* Supported by: Community / You.i
+
+```sh title="Install This Driver"
+npm install appium-youiengine-driver
+```

package/src/resources/submodules/appium/packages/appium/docs/en/ecosystem/index.md

@@ -0,0 +1,45 @@
+---
+hide:
+  - toc
+
+title: The Appium Ecosystem
+---
+
+Appium has a wide ecosystem of related software and tools. This section of the Appium documentation
+aims to compile a listing of various officially-supported and community-supported Appium projects:
+
+<div class="grid cards" markdown>
+
+-   :material-car: __Drivers__
+
+    ---
+
+    Link Appium to your test device
+
+    [:octicons-arrow-right-24: View all drivers](./drivers.md)
+
+-   :octicons-code-16: __Clients__
+
+    ---
+
+    Link Appium to your automation code
+
+    [:octicons-arrow-right-24: View all clients](./clients.md)
+
+-   :fontawesome-solid-plug: __Plugins__
+
+    ---
+
+    Modify and extend Appium functionality
+
+    [:octicons-arrow-right-24: View all plugins](./plugins.md)
+
+-   :material-wrench: __Tools__
+
+    ---
+
+    Interact with Appium in other ways
+
+    [:octicons-arrow-right-24: View all tools](./tools.md)
+
+</div>

package/src/resources/submodules/appium/packages/appium/docs/en/ecosystem/plugins.md

@@ -0,0 +1,138 @@
+---
+title: Appium Plugins
+---
+
+Plugins offer various ways to extend or modify Appium's behaviour. They are _completely optional_
+and are not needed for standard automation functionality, but you may find them to be useful
+for more specialised automation workflows.
+
+!!! note
+
+    If you maintain an Appium plugin that you would like to be listed here, feel free to create a PR!
+
+## Official Plugins
+
+These plugins are are currently maintained by the Appium team:
+
+### [Execute Driver](https://github.com/appium/appium/tree/master/packages/execute-driver-plugin)
+
+Run entire batches of commands in a single call to the Appium server
+
+```sh title="Install This Plugin"
+appium plugin install execute-driver
+```
+
+### [Images](https://github.com/appium/appium/tree/master/packages/images-plugin)
+
+Add support for image matching and comparison features
+
+```sh title="Install This Plugin"
+appium plugin install images
+```
+
+### [Inspector](https://github.com/appium/appium-inspector/tree/main/plugins)
+
+Integrate the [Appium Inspector](https://appium.github.io/appium-inspector/) directly into your
+Appium server installation
+
+```sh title="Install This Plugin"
+appium plugin install inspector
+```
+
+### [Relaxed Caps](https://github.com/appium/appium/tree/master/packages/relaxed-caps-plugin)
+
+Relax Appium's requirement for vendor prefixes on capabilities
+
+```sh title="Install This Plugin"
+appium plugin install relaxed-caps
+```
+
+### [Storage](https://github.com/appium/appium/tree/master/packages/storage-plugin)
+
+Add server-side storage with client-side management
+
+```sh title="Install This Plugin"
+appium plugin install storage
+```
+
+### [Universal XML](https://github.com/appium/appium/tree/master/packages/universal-xml-plugin)
+
+Translate the default iOS and Android XML formats into a common format
+
+```sh title="Install This Plugin"
+appium plugin install universal-xml
+```
+
+## Other Plugins
+
+These plugins are not maintained by the Appium team and can provide additional functionality:
+
+### [AltUnity](https://github.com/headspinio/appium-altunity-plugin)
+
+Target Unity games and apps for automation via the AltUnityTester framework
+
+Supported by: HeadSpin
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-altunity-plugin
+```
+
+### [Device Farm](https://github.com/AppiumTestDistribution/appium-device-farm)
+
+Manage and create driver sessions on connected Android devices and iOS simulators
+
+Supported by: `@AppiumTestDistribution`
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-device-farm
+```
+
+### [Gestures](https://github.com/AppiumTestDistribution/appium-gestures-plugin)
+
+Perform basic gestures using W3C Actions
+
+Supported by: `@AppiumTestDistribution`
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-gestures-plugin
+```
+
+### [Interceptor](https://github.com/AppiumTestDistribution/appium-interceptor-plugin)
+
+Intercept and mock API requests and responses
+
+Supported by: `@AppiumTestDistribution`
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-interceptor
+```
+
+### [OCR](https://github.com/jlipps/appium-ocr-plugin)
+
+Find elements via OCR text
+
+Supported by: `@jlipps`
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-ocr-plugin
+```
+
+### [Reporter](https://github.com/AppiumTestDistribution/appium-reporter-plugin)
+
+Generate standalone consolidated HTML reports with screenshots
+
+Supported by: `@AppiumTestDistribution`
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-reporter-plugin
+```
+
+### [Wait](https://github.com/AppiumTestDistribution/appium-wait-plugin)
+
+Manage global element wait timeouts
+
+Supported by: `@AppiumTestDistribution`
+
+```sh title="Install This Plugin"
+appium plugin install --source=npm appium-wait-plugin
+```

package/src/resources/submodules/appium/packages/appium/docs/en/ecosystem/tools.md

@@ -0,0 +1,83 @@
+---
+title: Appium-Related Tools
+---
+
+The Appium ecosystem also includes several tools that have been created to assist with things not
+directly related to running tests, such as Appium installation, test development, and more.
+
+!!! note
+
+    If you maintain an Appium tool that you would like to be listed here, feel free to create a PR!
+
+## Official Tools
+
+These tools are currently maintained by the Appium team:
+
+### [Appium Inspector](https://appium.github.io/appium-inspector/)
+
+Appium has a graphical client which can be used to inspect application screenshots, view the
+application hierarchy, search for elements, run Appium commands, record app interactions, and more.
+It can be very useful for Appium test development.
+
+## Extension Tools
+
+Appium driver or plugin developers can choose to include these tools in their driver/plugin:
+
+### Appium Doctor
+
+The Appium Doctor tool can be used to validate whether all prerequisites and other environment
+details needed for the driver/plugin have been set up correctly. The tool can be accessed via the
+[`doctor` command in the Appium CLI](../reference/cli/extensions.md#doctor):
+
+```sh
+appium {driver|plugin} doctor <extension-name>
+```
+
+It shows no results if the driver/plugin author did not implement Doctor support.
+
+!!! note
+
+    If you maintain an Appium extension and would like to add Appium Doctor support for it, check
+    out the documentation on [Building Doctor Checks](../developing/build-doctor-checks.md).
+
+## Other Tools
+
+These tools are not maintained by the Appium team:
+
+### [Appium Installer](https://github.com/AppiumTestDistribution/appium-installer)
+
+Appium Installer is a command-line tool for simplifying setups of new Appium test environments.
+It includes commands for installing Appium, its drivers and plugins, as well as validating
+prerequisites for iOS or Android emulators or real devices.
+
+Supported by: `@AppiumTestDistribution`
+
+```sh title="Install This Tool"
+npm install -g appium-installer
+```
+
+### [Jarvis Appium](https://github.com/AppiumTestDistribution/mcp-appium)
+
+Jarvis Appium is a Model Context Protocol (MCP) server that provides mobile test development and
+automation capabilities using Appium.
+
+Supported by: `@AppiumTestDistribution`
+
+```json title="Install This Tool"
+// Add the following to your MCP client configuration
+{
+  "mcpServers": {
+    "jarvis-appium": {
+      "disabled": false,
+      "timeout": 100,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["jarvis-appium"],
+      "env": {
+        "ANDROID_HOME": "/path/to/android/sdk",
+        "CAPABILITIES_CONFIG": "/path/to/your/capabilities.json"
+      }
+    }
+  }
+}
+```

package/src/resources/submodules/appium/packages/appium/docs/en/guides/branch-testing.md

@@ -0,0 +1,57 @@
+---
+title: Local Validation Of Extension PRs
+---
+
+Sometimes it might be necessary to validate if a remote driver or a plugin PR works for the particular local
+environment before it is merged or published. This tutorial describes how to achieve that.
+
+## Requirements
+
+- Recent LTS version of NodeJS. Check [Node.js main page](https://nodejs.org) for the download link.
+- Recent version of the Appium server. Use the following commands to ensure you have
+  the latest version installed: `npm uninstall appium` and `npm install -g appium`.
+- [Git](https://git-scm.com/) should be available locally.
+
+## Installation
+
+- [Check out](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) the PR locally.
+  There is also an option (although it is less flexible, because you won't be able to easily fetch
+  any changes to this PR later) to simply [download](https://docs.github.com/en/repositories/working-with-files/using-files/downloading-source-code-archives) and unzip the sources
+  locally. If you choose the later option then no `git` tool would be necessary.
+- Navigate to the local driver or plugin folder and run `npm i` from that folder.
+- Make sure you don't have the given driver or plugin already installed. Use the `appium driver uninstall <driver_name>`
+  or `appium plugin uninstall <plugin_name>` CLI in order to delete any leftovers. The value of
+  `<driver_name>`/`<plugin_name>` depends on the actual driver or plugin name the PR has been prepared for.
+  If you are not sure which name you need to use then check the content of the `package.json` manifest,
+  which must be always located under the root folder of the fetched sources. You should be looking for
+  the `"appium" -> "driverName"` entry value there.
+- Change the current folder to the one, which is NOT the driver/plugin folder root or its subfolder.
+  Also, make sure your current working folder does not contain any extra `package.json` file. If
+  it does then simply navigate to any other folder that does not.
+- Run the following command in order to link the driver/plugin sources to the Appium server:
+  `appium driver install --source=local <full_path_to_driver_folder_with_fetched_sources>` or
+  `appium plugin install --source=local <full_path_to_plugin_folder_with_fetched_sources>`.
+- Stop the Appium server if it is running and start it again (`appium server --use-drivers=<driver_name>`)
+  to check the list of loaded drivers. If the linking succeeded then you must see the driver name and the path to its
+  parent folder in the server logs. In case of a plugin it is required to explicitly request
+  this plugin to be loaded upon server startup: `appium server --use-plugins=<plugin_name>`.
+
+## Update
+
+After you have tested the PR and there are issues it might be necessary to update the local branch with
+the recent changes from Git. Follow the next steps for that:
+
+- Navigate to the parent folder of your local driver/plugin and run `git pull`.
+- Stop Appium server if it is running.
+- Run `npm i` in the parent folder of your local driver/plugin to rebuild it and update any dependencies if necessary.
+- Start Appium server again similarly to how this is done in the corresponding [Installation](#installation) step above.
+
+## Switching Back To a Stable Release
+
+After the PR is merged there is no need to use the local plugin/driver deployment anymore, and it makes sense
+to switch back to the package managed by NPM. Follow the next steps for that:
+
+- Unlink the installed driver/plugin from the server by running `appium driver uninstall <driver_name>` or
+  `appium plugin uninstall <driver_name>`.
+- Delete the local source folder (`rm -rf <full_path_to_plugin_or_driver_folder_with_fetched_sources>`).
+- Install the driver or the plugin from NPM. Check the component README in order to find a proper command for that.

package/src/resources/submodules/appium/packages/appium/docs/en/guides/caching.md

@@ -0,0 +1,76 @@
+---
+title: Caching of Application Bundles
+---
+
+Appium's base driver provides a feature which enables caching of application builds provided, for example,
+as `app` capability value or to endpoints similar to the `installApp` one. This article explains common caching
+principles, so you could create more performant and efficient test suite execution strategies.
+
+## Why Caching Is Necessary
+
+Mobile application bundles could reach hundreds of megabytes is size. This could become a serious
+performance issue if a test suite is executed, and it is necessary to fetch/extract the same application
+bundle for each test.
+
+## What Is Cached
+
+Caching could be applied to application bundles generated by
+[`configureApp`](https://github.com/appium/appium/blob/master/packages/base-driver/lib/basedriver/helpers.js#L107) helper call.
+Inherited drivers can customize their caching logic by providing own `onPostProcess`
+(or both `inDownload` and `onPostProcess`) property definition, but the general
+rule of thumb is that we need to cache locally all application bundles need to be downloaded and/or extracted
+first before they could be actually installed on the device under test. On iOS, for example, these are `.ipa` or
+`.zip` compressed application bundles, or .`aab` on Android.
+
+## Caching of Remote Application Bundles
+
+In order to validate whether an app bundle downloaded from the given URL could be (re)used from the cache the following
+steps are applied:
+
+1. The script checks if the given URL is already present in the cache.
+   If yes then it tries to fetch previously remembered
+   [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified)
+   or [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header values for it.
+2. If `ETag` value is present then it is put into
+   [If-None-Match request header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match).
+   Else if `Last-Modified` header value is present then it is put into
+   [If-Modified-Since request header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since).
+   Otherwise, no caching is applied.
+3. If the response status is equal to `304` then the previously cached binary is used,
+   otherwise the cached entry is reset and refreshed.
+
+## Caching of Local Application Bundles
+
+It only makes sense to cache application bundles if they need some preprocessing before being installed on the device under test.
+For example, on iOS `.ipa` bundles must be unzipped, because the system installer only works with `.app` folders.
+
+1. The script verifies if the given bundle path is already present in the cache. If the bundle was not in the cache yet
+then it gets preprocessed and added there.
+2. The script validates the hashsum of the bundle and compares it to the previously stored one. If hash sums don't match
+then the cached item gets deleted and the preprocessing of the bundle repeats.
+
+## How The Cache File System Is Configured
+
+The cache where the base driver keeps all application bundles is located in the system temp folder. It is configured
+on per-process basis, so each test session initialized in scope of the same Appium server process takes advantages
+of it. It is a [LRU Cache](https://www.npmjs.com/package/lru-cache) with the following limitations:
+
+- Max items: 1024. You may customize it by providing a new value to
+  the [APPIUM_APPS_CACHE_MAX_ITEMS](../reference/cli/env-vars.md) environment variable.
+  Do not set it to a lower number than the amount of apps in all parallel sessions per process.
+- Max time to live (TTL) for each entry: 24 hours.
+  You may customize it by providing a new value to the
+  [APPIUM_APPS_CACHE_MAX_AGE](../reference/cli/env-vars.md) environment variable.
+  Do not set it to a lower number than the duration of a single session startup.
+- TTL is refreshed for each entry upon access
+- By default the full application URL is used as cache key. You may change this behavior
+  by enabling the [APPIUM_APPS_CACHE_IGNORE_URL_QUERY](../reference/cli/env-vars.md) environment variable.
+  If the above option is enabled then the 'search' part of the app URL will be cut off from cache keys.
+  See the corresponding [feature request](https://discuss.appium.io/t/regarding-app-caching-when-using-aws-s3-presigned-urls/42713)
+  for more details.
+
+!!! warning
+
+    Note: The cache root folder is set up for automatic deletion on Appium process termination. This would only
+    work if Appium server is killed with `SIGINT` or `SIGTERM`. If `SIGKILL` is used then no cache cleanup
+    would be performed.