appium-mcp 0.0.1 → 1.1.4

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

@@ -0,0 +1,150 @@
+---
+hide:
+  - navigation
+
+title: Contributing to Appium
+---
+
+The Appium project would not exist without the many contributions of code, documentation,
+maintenance, and support from companies and volunteers. As such, we welcome contributions!
+
+There are a lot of different ways to help the project - see below for everything you can do and the
+processes to follow for each contribution method. Note that no matter how you contribute, your
+participation is governed by our [Code of Conduct](https://github.com/appium/appium/blob/master/CONDUCT.md).
+
+## Join the Discussion Forum
+
+You don't need to know the internals of Appium to be able to contribute! If you have experience with
+using Appium and feel like sharing your knowledge with others, consider helping out users on the
+Appium forums at [discuss.appium.io](https://discuss.appium.io/). Hop on over and see if there are
+any questions that you can answer.
+
+## Report Bugs or Feature Requests
+
+If you've encountered a bug, or have a cool feature in mind that you think Appium should support,
+make sure to let us know at our [GitHub issue tracker](https://github.com/appium/appium/issues).
+Please use the appropriate issue form template when creating your issue.
+
+## Triage Issues
+
+In addition to creating issues, you can also help us investigate already reported issues. All you
+need is enough familiarity with Appium to try and reproduce bugs.
+
+You can get started by checking our [GitHub issue tracker](https://github.com/appium/appium/issues)
+for issues with labels such as `Needs Triage` or `Needs Info`, and leaving relevant comments:
+
+-   If the issue is a duplicate, drop a link to the original issue
+-   If the user has not provided enough information (such as Appium logs), ask them for more details
+-   If you can reproduce the problem on your own environment, provide all the information that you think
+    would help us track down the cause of the issue
+
+For further information on triaging Appium issues (for any Appium project repository), please contact
+any member of the [Technical Committee](https://github.com/appium/appium/blob/master/GOVERNANCE.md#the-technical-committee).
+
+## Contribute Code
+
+We are always open to pull requests for improving the Appium code or documentation!
+
+!!! info
+
+    Developer information may not be kept up to date as frequently as user-facing information, or
+    it may be most relevant in its current form on the online repository, not in this published
+    version. Make sure to check the repo or discuss with maintainers. We would be glad to help
+    new contributors get started!
+
+Start by cloning the repository (we recommend [forking](https://github.com/appium/appium/fork)
+it first):
+```sh
+git clone https://github.com/appium/appium.git
+cd appium
+```
+
+!!! info
+
+    If you are VS Code user, you can easily check out the project using [Runme](https://runme.dev/api/runme?repository=https%3A%2F%2Fgithub.com%2Fappium%2Fappium.git&fileToOpen=packages%2Fappium%2Fdocs%2Fen%2Fcontributing%2Findex.md).
+
+Install dependencies:
+```sh
+npm install
+```
+
+From here on there are several things you can do.
+
+Build the project:
+```sh
+npm run build
+```
+
+Build the project and watch for changes:
+```sh
+npm run dev
+```
+
+Start the locally built Appium server:
+```sh
+npm start
+```
+
+Run various tests:
+```sh
+npm run lint
+npm run test:unit
+npm run test:types
+npm run test:smoke
+npm run test:e2e
+npm run test:quick # unit and types
+npm run test:slow # everything
+```
+
+You can also run tests for specific workspaces, e.g.:
+
+```sh
+export APPIUM_WORKSPACE=@appium/base-driver
+npm run test:unit -w $APPIUM_WORKSPACE
+```
+
+### Documentation
+
+The documentation for this project is [available in the project repository itself](https://github.com/appium/appium/tree/master/packages/appium/docs).
+It is contained in Markdown files, which are built by our documentation system in the
+`@appium/docutils` module. This module is based on [MkDocs](https://www.mkdocs.org/) and therefore
+requires [Python](https://www.python.org/) to be installed on your system.
+
+Install Python dependencies:
+```sh
+npm run install-docs-deps
+```
+
+After making your changes, you can run the documentation server in dev mode:
+```sh
+npm run dev:docs
+```
+
+You can then view the documentation at `http://127.0.0.1:8000/docs/en`.
+
+## Translating Appium Documentation
+
+The process of Appium documents localization into languages other than English is automated and is done via
+the [Crowdin Translations Management System](https://crowdin.com). Do not edit any translated documents
+directly in the GitHub Appium repository as they are going to be replaced with ones exported from Crowdin
+during an upcoming sync.
+
+### Where To Start
+
+If you would like to contribute to the translation of Appium documents into your language then simply join
+the translators group for the [Appium Documentation](https://crowdin.com/project/appium-documentation)
+Crowdin project, and start translating documents there. If you see that your language is missing from
+the list of available Crowdin languages then simply let us know by creating an
+[issue](https://github.com/appium/appium/issues).
+
+### Source Language Updates
+
+Changes in documents are synchronized to Crowdin automatically via the `Update Crowdin English Docs` GitHub action.
+This action is triggered automatically as soon as there are any changes under `packages/appium/docs/en/**.md`
+or `packages/appium/docs/mkdocs-en.yml`.
+
+### Fetching Translated Documents
+
+In order to fetch translated files from Crowdin to the GitHub repository it is necessary to trigger
+the `Sync Crowdin Docs Translations` action. This action should also automatically create a PR with
+corresponding translated resources included.

package/src/resources/submodules/appium/packages/appium/docs/en/developing/build-docs.md

@@ -0,0 +1,86 @@
+---
+title: Building Documentation
+---
+
+Once you've [built a driver](./build-drivers.md) or [built a plugin](./build-plugins.md) for Appium,
+you will hopefully want to document how that extension works for your users. The most basic way of
+doing this is to write up a quick `README.md` and keep it in the root of your project's repository.
+However, this can involve a lot of effort.
+
+The Appium project has built tools to help with this, and we've packaged up these tools so our
+ecosystem developers building drivers and plugins can _also_ use them. The best way to get going
+with these tools is probably to look at an existing Appium driver repo to see how it's done, for
+example the [XCUITest driver repo](https://github.com/appium/appium-xcuitest-driver). But this guide
+will outline the basic approach.
+
+### Conceptual architecture
+
+Appium settled on [MkDocs](https://www.mkdocs.org/) as a Markdown-based documentation site
+generator. It uses a Python toolchain (and not Node.js), but it turned out to be the best option
+for our purposes. You can adjust this, but by default Appium's utilities also assume that you'll be
+using the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme/extension for
+MkDocs.
+
+In order to make different versions of your docs available (one for each minor release of your
+extension, typically), we also bundle [Mike](https://github.com/jimporter/mike).
+
+From here, building a basic docs site is as easy as collecting your Markdown files together and
+defining how you want them to be organized.
+
+### Prerequisites
+
+To take advantage of Appium's documentation utilities, you'll need to install:
+
+- [Python v3+](https://www.python.org/downloads/)
+- [pip](https://pip.pypa.io/en/stable/installation/) (this may be installed automatically with Python)
+- The `@appium/docutils` package:
+
+    ```bash
+    npm install --save-dev @appium/docutils
+    ```
+
+### Initializing an Extension for Building Docs
+
+To prepare your extension for generating documentation, run the following command:
+
+```bash
+npx appium-docs init
+```
+
+This will:
+
+1. Create a `tsconfig.json` if one does not already exist. This is necessary even if your extension
+is not written in TypeScript.
+2. Create a `mkdocs.yml` with the necessary configuration for MkDocs.
+
+### Documenting Your Extension
+
+At this point, you can begin documenting your extension. By default, MkDocs will look for Markdown
+files in the `docs` directory. You can therefore create your Markdown documentation files, place
+them in `docs`, and add links to these files in `mkdocs.yml`.
+
+Refer to the [MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/) for
+information on how to organize and structure your documentation. 
+
+### Building the Docs
+
+At this point, you can use the `appium-docs` CLI tool. Run this tool with no arguments to get the
+full help output and see all the available subcommands and parameters. Here are a few usage
+examples:
+
+```bash
+# Generate reference and build the mkdocs site into the site dir
+npx appium-docs build
+
+# Same as build, but host the docs on a local dev server
+# and watch for changes and rebuild when files change
+npx appium-docs build --serve
+
+# Build the docs and deploy them with mike versioning to the docs-site branch
+# using the included commit message.
+# This is particularly useful for pushing content to a GitHub pages branch!
+npx appium-docs build \
+  --deploy \
+  -b docs-site \
+  -m 'docs: auto-build docs for appium-xcuitest-driver@%s'
+```

package/src/resources/submodules/appium/packages/appium/docs/en/developing/build-doctor-checks.md

@@ -0,0 +1,141 @@
+---
+title: Building Doctor Checks
+---
+
+The idea of Appium Doctor is to assist users with driver or plugin preconditions setup. Sometimes such
+preconditions might be quite complicated and require non-trivial technical knowledge. Doctor checks,
+which are vanilla Node.js class instances written by extension authors, simplify
+the setup process by automating diagnostics and possible fixes for the found issues. These checks
+might also be interactive to ensure better usage experience.
+
+This tutorial is supposed to be used by plugin or driver authors that would like to help their users
+to deal with complicated setup or configuration steps.
+
+## Adding Doctor Checks
+
+### Typing Requirements
+
+The term `Doctor Check` literally describes a single javascript class instance that implements the
+[IDoctorCheck interface](https://github.com/appium/appium/blob/master/packages/types/lib/doctor.ts).
+The interface defines the following methods and properties:
+
+- `diagnose(): Promise<DoctorCheckResult>`: Contains the code to diagnose a possible issue
+- `fix(): Promise<string|null>`: Either fixes the actual problem if `hasAutofix()` returns true or
+  returns a string description for possible manual fixes. If this method throws an exception named
+  `FixSkippedError` and `hasAutofix()` returns true then the result of the method invocation
+  is going to be ignored.
+- `hasAutofix(): boolean`: Whether calling `fix()` would resolve the found issue
+- `isOptional(): boolean`: Whether the found issue can be ignored and is not a showstopper
+- `log: AppiumLogger`: May be used for logging. This property may be assigned
+  by the instance itself or by the Appium server if it is left unassigned.
+
+The `DoctorCheckResult` object returned by the `diagnose()` method must contain the following properties:
+
+- `ok: boolean`: Whether the diagnosis found no issues
+- `optional: boolean`: Whether the diagnosed issue is safe to ignore
+- `message: string`: The text message describing the diagnostic result
+
+### Manifest Requirements
+
+A single extension may export multiple Doctor checks to Appium. In order for these checks to be properly
+picked up by the server CLI after the corresponding extension is installed they might be listed in the
+package .json manifest under the `appium.doctor.checks` section similar to the definition below:
+
+```json
+  // ...
+  "appium": {
+    "driverName": "fake",
+    "automationName": "Fake",
+    "platformNames": [
+      "Fake"
+    ],
+    "mainClass": "FakeDriver",
+    "schema": "./build/lib/fake-driver-schema.js",
+    "scripts": {
+      "fake-error": "./build/lib/scripts/fake-error.js",
+      "fake-success": "./build/lib/scripts/fake-success.js",
+      "fake-stdin": "./build/lib/scripts/fake-stdin.js"
+    },
+    "doctor": {
+      "checks": [
+        "./doctor/fake1.js",
+        "./doctor/fake2.js"
+        // ...
+      ]
+    }
+  },
+  // ...
+```
+
+Also, it makes sense to include the [@appium/types](https://www.npmjs.com/package/@appium/types) import
+to the package dev dependencies.
+
+### Implementation Example
+
+The below example is a "raw" Node.JS implementation that does not use any transpilation:
+
+```js
+const {fs, doctor} = require('@appium/support');
+
+/** @satisfies {import('@appium/types').IDoctorCheck} */
+class EnvVarAndPathCheck {
+  /**
+   * @param {string} varName
+   */
+  constructor(varName) {
+    this.varName = varName;
+  }
+
+  async diagnose() {
+    const varValue = process.env[this.varName];
+    if (typeof varValue === 'undefined') {
+      return doctor.nok(`${this.varName} environment variable is NOT set!`);
+    }
+
+    if (await fs.exists(varValue)) {
+      return doctor.ok(`${this.varName} is set to: ${varValue}`);
+    }
+
+    return doctor.nok(`${this.varName} is set to '${varValue}' but this is NOT a valid path!`);
+  }
+
+  async fix() {
+    return (
+      `Make sure the environment variable ${this.varName} is properly configured for the Appium server process`
+    );
+  }
+
+  hasAutofix() {
+    return false;
+  }
+
+  isOptional() {
+    return false;
+  }
+}
+
+const androidHomeCheck = new EnvVarAndPathCheck('ANDROID_HOME');
+
+module.exports = {androidHomeCheck};
+
+/**
+ * @typedef {import('@appium/types').DoctorCheckResult} CheckResult
+ */
+```
+
+This file could be saved as `doctor/android-home-check.js` and then added to the package.json manifest
+as
+
+```json
+  // ...
+  "appium": {
+    // ...
+    "doctor": {
+      "checks": [
+        "./doctor/android-home-check.js",
+      ]
+    }
+    // ...
+  },
+  // ...
+```