appium-mcp 0.0.1 → 1.1.5

package/src/resources/submodules/appium/packages/appium/docs/ja/guides/grid.md

@@ -0,0 +1,166 @@
+---
+title: Appium and Selenium Grid
+---
+
+## Using Selenium Grid 4+
+
+The
+[relay](https://www.selenium.dev/documentation/grid/configuration/toml_options/#relaying-commands-to-a-service-endpoint-that-supports-webdriver)
+feature in Grid 4 allows you to proxy Appium requests to an Appium server instance. Here is
+an example walkthrough of how you would connect two different Appium instances to a Selenium Grid.
+
+### Define the Appium configs
+
+Each Appium instance should have a config file that can be easily updated. It should contain any
+information which needs to be unique to that particular server (e.g., ports its drivers should use
+that others should not). We are going to have 2 Appium servers, so we will need 2 config files:
+
+```yaml
+# appium1.yml
+server:
+  port: 4723
+  use-drivers:
+    - xcuitest
+  default-capabilities:
+    wdaLocalPort: 8100
+    mjpegServerPort: 9100
+    mjpegScreenshotUrl: "http://localhost:9100"
+```
+
+In the above YAML config file, we specify the Appium server port, the driver used, and parameters
+for the driver that will be sent in as default capabilities. Our goal is to ensure that any other
+drivers running on this host will not compete with system ports or other resources. The second
+config file could look like the following, where we simply adjust a few ports to prevent clashes:
+
+```yaml
+# appium2.yml
+server:
+  port: 4733
+  use-drivers:
+    - xcuitest
+  default-capabilities:
+    wdaLocalPort: 8110
+    mjpegServerPort: 9110
+    mjpegScreenshotUrl: "http://localhost:9110"
+```
+
+### Define the Grid node configs
+
+We will be launching one Grid "node" per Appium server, to manage relaying commands and determining
+capacity and online status, etc... So we should have one config file per Grid node as well. Each
+node config should include the address of the Appium server it will target, as well as a list of
+capability "configs" it should accept to relay a session request to Appium. Here is what the config
+could look like for the two nodes:
+
+```toml
+# node1.toml
+[server]
+port = 5555
+
+[node]
+detect-drivers = false
+
+[relay]
+url = "http://localhost:4723"
+status-endpoint = "/status"
+configs = [
+    "1", "{\"platformName\": \"iOS\", \"appium:platformVersion\": \"15.5\", \"appium:deviceName\": \"iPhone 13\", \"appium:automationName\": \"XCUITest\"}"
+]
+```
+
+```toml
+# node2.toml
+[server]
+port = 5565
+
+[node]
+detect-drivers = false
+
+[relay]
+url = "http://localhost:4733"
+status-endpoint = "/status"
+configs = [
+    "1", "{\"platformName\": \"iOS\", \"appium:platformVersion\": \"15.5\", \"appium:deviceName\": \"iPhone 12\", \"appium:automationName\": \"XCUITest\"}"
+]
+```
+
+Note that each node config also specifies a different port itself for the node to run on.
+
+### Putting it together
+
+The Grid nodes aren't enough--you'll also want a Grid "hub" that acts as a load balancer and
+manager for all the nodes. So in the end we'll have 5 processes running at once: 2 Appium servers,
+2 Grid nodes, and 1 Grid hub. It's best to run each of these in a separate terminal window to avoid
+confusion of logs. Here is how you'd start each process:
+
+0. `appium --config appium1.yml`
+1. `appium --config appium2.yml`
+2. `java -jar /path/to/selenium.jar node --config node1.toml`
+3. `java -jar /path/to/selenium.jar node --config node2.toml`
+4. `java -jar /path/to/selenium.jar hub`
+
+Once you wait a few moments for the nodes to detect their Appium servers, and to register with the
+hub, you'll be able to send all your Appium traffic via the single hub endpoint (defaulting to
+`http://localhost:4444`).
+
+And of course, you're able to link up Appium servers and nodes running on different machines in
+your network to form a larger grid.
+
+## Using Selenium Grid 3
+
+It is possible to register your Appium server with a local [Selenium Grid 3](https://www.selenium.dev/documentation/legacy/selenium_3/grid_3/)
+([setup docs](https://www.selenium.dev/documentation/legacy/grid_3/setting_up_your_own_grid/)) instance by using the
+`--nodeconfig` server argument.
+
+```bash
+appium server --nodeconfig /path/to/nodeconfig.json --base-path=/wd/hub
+```
+
+In the referenced config file you have to define the `browserName`, `version` and `platform`
+capabilities and based on these parameters the grid will re-direct your test to the right device.
+You will also need to configure your host details and the Selenium Grid details. For a full list of
+all parameters and descriptions see
+[here](https://www.selenium.dev/documentation/legacy/selenium_3/grid_setup/).
+
+Once you start the Appium server it will register with the grid, and you will see your device on
+the grid console page:
+
+`http://**\<grid-ip-adress\>**:**\<grid-port\>**/grid/console`
+
+### Example Grid Node Configuration JSON
+
+```json
+{
+  "capabilities":
+      [
+        {
+          "browserName": "<e.g._iPhone5_or_iPad4>",
+          "version":"<version_of_iOS_e.g._7.1>",
+          "maxInstances": 1,
+          "platform":"<platform_e.g._MAC_or_ANDROID>"
+        }
+      ],
+  "configuration":
+  {
+    "cleanUpCycle":2000,
+    "timeout":30000,
+    "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
+    "url":"http://<host_name_appium_server_or_ip-address_appium_server>:<appium_port>/wd/hub",
+    "host": "<host_name_appium_server_or_ip-address_appium_server>",
+    "port": <appium_port>,
+    "maxSession": 1,
+    "register": true,
+    "registerCycle": 5000,
+    "hubPort": <grid_port>,
+    "hubHost": "<Grid_host_name_or_grid_ip-address>",
+    "hubProtocol": "<Protocol_of_Grid_defaults_to_http>"
+  }
+}
+```
+
+If `url`, `host`, and `port` are not given, the config will be auto updated to point to
+`localhost:<appium-port>`.
+
+If your Appium server is running on a different machine to your Selenium Grid server, make sure you
+use an external name/IP address in your `host` and `url` configuration; `localhost` and `127.0.0.1`
+will prevent Selenium Grid from connecting correctly.

package/src/resources/submodules/appium/packages/appium/docs/ja/guides/headers.md

@@ -0,0 +1,17 @@
+---
+title: Header Handling
+---
+
+# Header Handling
+
+## Request ID Tracking
+
+Appium supports setting the request ID for each request through the `x-request-id` header. This is useful for tracing requests through your system, especially in environments where multiple services are involved or when debugging across different requests.
+
+### Using `x-request-id`
+
+When making requests to Appium, you can include an `x-request-id` header with a unique identifier. This ID will be:
+
+- Used to track the request through Appium's logging system
+- Preserved across the entire request lifecycle
+- Generated automatically (as a UUID) if not provided

package/src/resources/submodules/appium/packages/appium/docs/ja/guides/log-filters.md

@@ -0,0 +1,86 @@
+---
+title: Filtering the Appium Log
+---
+
+Sometimes it might be necessary to hide sensitive information, like passwords, device identifiers,
+hashes, etc..., from the server log. Appium makes it possible to ensure such information is
+redacted in logs via the `--log-filters` command line argument. This argument allows you to provide
+the path to a special config file, containing one or more log obfuscation rules.
+
+## Config Format
+
+The filtering config must be one of:
+
+- a path to a valid JSON file containing an array of filtering rules
+- a `log-filters` entry in an [Appium Config](./config.md) file, with the rules array inline
+
+Each rule is an object with a set of predefined properties. The following rule properties are
+supported:
+
+- `pattern`: A valid Javascript RegExp pattern to replace. Must be a valid non-empty pattern.
+- `text`: A simple non-empty exact text match to replace. Either this property or the above one must
+  be provided. `pattern` has priority over `text` if both are provided.
+- `flags`: Regular expression flags for the given pattern. Supported flags are the same as for the
+  standard JavaScript [RegExp constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Advanced_searching_with_flags_2).
+  Note that the `g` (global matching) flag is always enabled.
+- `replacer`: The replacer value to use. By default it is `**SECURE**`. Empty values are allowed.
+
+### Config Examples
+
+Replace all occurrences of `my.magic.app` string with the default replacer:
+
+```json
+[
+    {
+        "text": "my.magic.app"
+    }
+]
+```
+
+Replace all occurrences of `my.magic.<any char>` string with a custom replacer (case insensitive):
+
+```json
+[
+    {
+        "pattern": "my\\.magic\\.\\w",
+        "flags": "i",
+        "replacer": "***"
+    }
+]
+```
+
+Replace all occurrences of `my.magic.<any chars>` and/or `your.magic` strings with a custom
+replacer (case insensitive):
+
+```json
+[
+    {
+        "pattern": "my\\.magic\\.\\w+",
+        "flags": "i",
+        "replacer": "***"
+    },
+    {
+        "pattern": "your\\.magic",
+        "flags": "i",
+        "replacer": "***"
+    }
+]
+```
+
+Truncate all log lines to max 15 chars (advanced):
+
+```json
+[
+	{
+        "pattern": "(.{1,15}).*",
+        "flags": "s",
+        "replacer": "$1"
+    }
+]
+```
+
+### Config Errors Handling
+
+If any of the config rules contains invalid items (such as empty/invalid pattern, empty rule, etc.)
+then Appium will print the detailed report about collected errors and will fail to start until
+these errors are addressed.

package/src/resources/submodules/appium/packages/appium/docs/ja/guides/managing-exts.md

@@ -0,0 +1,89 @@
+---
+title: Managing Drivers and Plugins
+---
+
+To do anything useful with Appium, you need to have at least one [Driver](../intro/drivers.md)
+installed, otherwise Appium won't know how to automate anything. There is an entire
+[Ecosystem](../ecosystem/index.md) of drivers and plugins out there!
+
+This guide helps explain how to manage these drivers and plugins. There are
+two basic strategies: using Appium's extension CLI interface, or managing extensions yourself in an
+`npm`-based project.
+
+!!! note
+
+```
+Other package managers are not currently supported.
+```
+
+## Using Appium's Extension CLI
+
+With Appium's [Extension CLI](../reference/cli/extensions.md), you let Appium manage drivers and plugins for
+you.  You will use CLI commands to tell Appium which extensions you would like to install, update,
+or remove. Here's an example of how you might install a driver using the CLI:
+
+```bash
+appium driver install xcuitest
+```
+
+This command will install the latest version of the
+[XCUITest Driver](https://github.com/appium/appium-xcuitest-driver). The Extension CLI comes with a variety
+of commands and parameters; see the documentation for that command for all the specifics.
+
+The all-important question when Appium is managing your extensions for you is: where are they installed?
+Appium manages extensions in a directory specified by the `APPIUM_HOME` environment variable. You
+can set that variable to anything you like, and Appium will manage its extensions there. You can
+therefore also use the `APPIUM_HOME` environment variable to manage different sets of extensions,
+for example if you want to have the same driver installed at conflicting versions:
+
+```bash
+APPIUM_HOME=/path/to/home1 appium driver install xcuitest@4.11.1
+APPIUM_HOME=/path/to/home2 appium driver install xcuitest@4.11.2
+```
+
+Running these commands will result in two separate `APPIUM_HOME` directories being created and
+populated with the corresponding version of the XCUITest driver. You can then use the same
+environment variables to direct Appium which version to use on launch:
+
+```bash
+APPIUM_HOME=/path/to/home1 appium  # use xcuitest driver 4.11.1
+APPIUM_HOME=/path/to/home2 appium  # use xcuitest driver 4.11.2
+```
+
+You don't need to set `APPIUM_HOME` if you don't want to! By default, Appium will set `APPIUM_HOME`
+to the directory `.appium` in your user home directory.
+
+These installed packages will be managed by `extensions.yaml` in `$APPIUM_HOME/node_modules/.cache/appium/extensions.yaml`.
+
+## Do-It-Yourself with `npm`
+
+Because Appium and Appium drivers are Node.js programs, if you are integrating your Appium scripts
+into your own Node.js project, there is an alternative way to manage drivers and plugins: via `npm`,
+like any other dependency. Basically, whenever you run Appium, if you have not explicitly set
+`APPIUM_HOME`, it will:
+
+1. Try to determine whether the _current directory_ is inside an `npm` package.
+2. If so, it will check whether `appium` is a dependency (dev, prod, or peer) in the project's
+   `package.json`
+3. If so, _unless you have specified `APPIUM_HOME` in your environment_, Appium will ignore load
+   drivers and plugins defined in that `package.json` file instead.
+
+This means you are freely able to add Appium drivers and plugins as regular package dependencies or
+dev dependencies. For example, if your project has a `package.json` which includes the following:
+
+```json
+{
+  "devDependencies": {
+    "appium": "^2.0.0",
+    "appium-xcuitest-driver": "^4.11.1"
+  }
+}
+```
+
+Then, if you run `npx appium` inside your project, Appium will detect that it is a dependency of
+the project, and will load the XCUITest driver which is also listed as a dev dependency for the
+project.
+
+This strategy is _only_ recommended if you are already using `npm` for your project.
+Otherwise, it is recommended that you use Appium's Extension CLI and, if necessary, adjust
+`APPIUM_HOME` to change the location of stored extensions.