@appium/mcp-documentation 1.0.3 → 1.0.5

package/src/resources/submodules/appium-uiautomator2-driver/docs/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+```mermaid
+flowchart TD
+  subgraph ClientSide["Test Client"]
+    T["Test Code"]
+    CL["Appium Client Library<br/>(Java / Python / JS / Ruby / C#)"]
+  end
+
+  subgraph ServerHost["Automation Host"]
+    AS["Appium Server<br/>WebDriver HTTP API"]
+    XD["UiAutomator2 Driver<br/>(appium-uiautomator2-driver)"]
+    ADBM["ADB + Port Forwarding"]
+    CDM["Chromedriver Management<br/>(hybrid / webview only)"]
+  end
+
+  subgraph DeviceTarget["Android Device / Emulator"]
+    U2S["UiAutomator2 Server<br/>(instrumentation HTTP API)"]
+    UIA["UiAutomator Framework"]
+    CD["Chromedriver<br/>(in webview context)"]
+    AUT["Application Under Test"]
+  end
+
+  T --> CL
+  CL -->|"W3C WebDriver over HTTP"| AS
+  AS -->|"Forwards session commands to driver"| XD
+  XD -->|"Install, shell, forward ports"| ADBM
+  XD -->|"Context switch to WEBVIEW_*"| CDM
+  ADBM -->|"adb forward (e.g. host:8200 → device:6790)"| U2S
+  CDM -->|"Chromedriver HTTP"| CD
+  U2S -->|"UiAutomator APIs"| UIA
+  UIA -->|"UI interactions + accessibility tree"| AUT
+  CD -->|"WebDriver in webview"| AUT
+```

package/src/resources/submodules/appium-uiautomator2-driver/docs/bidi.md

@@ -0,0 +1,50 @@
+# Supported BiDi Commands And Events
+
+Only events and commands mentioned below are supported.
+All other entities described in the spec throw not implemented errors.
+
+# Supported Events
+
+## log.entryAdded
+
+This event is emitted if the driver retrieves a new entry for any of the below log types.
+
+### syslog
+
+Events are emitted for both emulator and real devices. Each event contains a single device logcat line.
+Events are always emitted with the `NATIVE_APP` context.
+These events might be disabled if the `appium:skipLogcatCapture` capability is enabled.
+
+### server
+
+Events are emitted for both emulator and real devices. Each event contains a single Appium server log line.
+Events are always emitted with the `NATIVE_APP` context.
+Events are only emitted if the `get_server_logs` server security feature is enabled.
+
+## appium:uiautomator2.contextUpdate
+
+This event is emitted upon the context change, either explicit or implicit.
+The event is always emitted upon new session initialization.
+See the [GitHub feature ticket](https://github.com/appium/appium/issues/20741) for more details.
+
+### CDDL
+
+```cddl
+appium:uiautomator2.contextUpdated = {
+  method: "appium:uiautomator2.contextUpdated",
+  params: {
+    name: text,
+    type: "NATIVE" / "WEB",
+  },
+}
+```
+
+The event contains the following params:
+
+### name
+
+Contains the actual name of the new context, for example `NATIVE_APP`.
+
+### type
+
+Either `NATIVE` or `WEB` depending on which context is currently active in the driver session.

package/src/resources/submodules/appium-uiautomator2-driver/docs/capability-sets.md

@@ -0,0 +1,136 @@
+## Basic Examples of Session Capability Sets
+
+This article describes necessary capabilities that must be provided in order
+to implement some common automation testing scenarios.
+It only describes very minimum sets of capabilities required to
+be included. For refined setups more of them might need to be provided. Check the
+[Capabilities](../README.md#capabilities) section in README for more details
+on each option available for the fine-tuning of UIAutomator2 driver sessions.
+
+### Application File (Real Device)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "appium:platformVersion": "<Android_Version>",
+  "appium:udid": "<Phone_ID>",
+  "appium:app": "/path/to/local/package.apk"
+}
+```
+
+`appium:app` could also be a remote app or an archive:
+
+```
+  "appium:app": "https://example.com/package.apk"
+  "appium:app": "https://example.com/package.zip"
+```
+
+Sometimes it might also be necessary to explicitly provide
+`appium:appPackage` and `appium:appActivity` capability values
+if the driver is unable to autodetect them from the provided app package manifest.
+Check the [How To Troubleshoot Activities Startup](./activity-startup.md) article
+for more details.
+
+### Application File (Emulator)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "appium:avd": "<Emulator_Name>",
+  "appium:platformVersion": "<Android_Version>",
+  "appium:app": "/path/to/local/package.apk"
+}
+```
+
+`appium:app` could also be a remote app or an archive:
+
+```
+  "appium:app": "https://example.com/package.apk"
+```
+
+### Chrome (Real Device)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "browserName": "Chrome",
+  "appium:platformVersion": "<Android_Version>",
+  "appium:udid": "<Phone_ID>"
+}
+```
+
+### Chrome (Emulator)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "browserName": "Chrome",
+  "appium:avd": "<Emulator_Name>",
+  "appium:platformVersion": "<Android_Version>"
+}
+```
+
+### Pre-Installed App (Real Device)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "appium:platformVersion": "<Android_Version>",
+  "appium:udid": "<Phone_ID>",
+  "appium:appPackage": "<App_Package_Id>",
+  "appium:appActivity": "<App_Activity_Id>",
+  "appium:noReset": true
+}
+```
+
+The `appium:noReset` capability is set to `true` in order to tell the driver
+the app identified by `appium:appPackage` is already preinstalled and must not be reset.
+
+### Pre-Installed App (Emulator)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "appium:avd": "<Emulator_Name>",
+  "appium:platformVersion": "<Android_Version>",
+  "appium:appPackage": "<App_Package_Id>",
+  "appium:appActivity": "<App_Activity_Id>",
+  "appium:noReset": true
+}
+```
+
+### Custom Launch (Real Device)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "appium:platformVersion": "<Android_Version>",
+  "appium:udid": "<Phone_ID>"
+}
+```
+
+This will start your test at the Home screen.
+Afterwards you may use any of the application management
+methods, like [mobile: installApp](../README.md#mobile-installapp)
+or [mobile: activateApp](../README.md#mobile-activateapp)
+to manage the life cycle of your app or switch between contexts to
+manage web pages. Check the full list of
+[mobile: execute methods](../README.md#platform-specific-extensions) for more details.
+
+### Custom Launch (Emulator)
+
+```json
+{
+  "platformName": "Android",
+  "appium:automationName": "uiautomator2",
+  "appium:avd": "<Emulator_Name>",
+  "appium:platformVersion": "<Android_Version>"
+}
+```

package/src/resources/submodules/appium-uiautomator2-driver/docs/mjpeg.md

@@ -0,0 +1,111 @@
+# MJPEG Screen Streaming
+
+This guide describes the MJPEG (Motion JPEG) screen streaming support in the UiAutomator2 driver.
+
+## Overview
+
+The UiAutomator2 **server** (running on the Android device) includes a built-in MJPEG broadcaster. It captures the device screen at a configurable rate, encodes frames as JPEG, and serves them over TCP using the `multipart/x-mixed-replace` format. This allows:
+
+- **Live viewing** of the device screen by connecting to the stream (e.g. in a browser or a custom client).
+- **Screenshot from stream**: if the driver is configured to use the MJPEG URL, the standard screenshot command returns the latest frame from the stream instead of calling the server’s screenshot API.
+
+The MJPEG server on the device is started automatically when the UiAutomator2 instrumentation starts and listens on a fixed port on the device (default `7810`).
+
+## Use Cases
+
+| Use case | Description |
+|----------|-------------|
+| **Screen recording** | The UiAutomator2 driver can use the MJPEG stream as input for host-side screen recording tooling (for example, via `ffmpeg`) to produce MP4 (or other) video files. |
+| **Screenshots from stream** | If you set the `appium:mjpegScreenshotUrl` capability, the driver uses the **latest frame** from that MJPEG stream when you call the screenshot command instead of calling the server’s regular screenshot API. |
+| **Live viewing / custom tools** | Any HTTP client (browser, script, or custom app) can connect to the MJPEG URL (after port forwarding, if needed) to view or process the live screen. |
+
+## Configuration
+
+### Capabilities
+
+#### `appium:mjpegServerPort`
+
+- **Type:** integer (port number on the **host**)
+- **Description:** The port on the host machine to which the device MJPEG server port is forwarded via ADB. If not set, no port forwarding is done, so the device MJPEG service is not reachable from the host.
+- **Use case:** Set this when you want to connect to the device MJPEG stream from the host (e.g. `http://localhost:<mjpegServerPort>`) or when using screen recording so the host can receive the stream.
+- **Parallel sessions:** Use a **unique** `mjpegServerPort` per session when running multiple devices or parallel tests to avoid port conflicts.
+
+#### `appium:mjpegScreenshotUrl`
+
+- **Type:** string (URL)
+- **Description:** URL of a service that provides real-time device screenshots in MJPEG format. If set, the driver creates an MJPEG client that consumes this URL; the standard **screenshot** command then returns the latest frame from that stream instead of calling the UiAutomator2 server’s `/screenshot` endpoint.
+- **Typical value:** When you forward the device MJPEG port with `appium:mjpegServerPort`, you can set this to `http://localhost:<mjpegServerPort>` (or the same host/port your client uses to reach the stream) so that screenshot uses the MJPEG stream.
+- **Note:** The driver starts the MJPEG stream client after the session is created and stops it on session end. If the stream has not yet produced a frame, the screenshot command may fall back to the regular server screenshot.
+
+### Settings (device-side MJPEG broadcaster)
+
+These settings control the MJPEG broadcaster that runs **on the device** (in the UiAutomator2 server). They can be changed at runtime via the [Settings API](https://appium.io/docs/en/latest/guides/settings/) (e.g. `driver.update_settings({...})`).
+
+| Setting | Type | Range / values | Default | Description |
+|--------|------|----------------|---------|-------------|
+| `mjpegServerPort` | int | 1024..65535 | 7810 | Port on the **device** where the MJPEG server listens. The driver forwards this to the host when `appium:mjpegServerPort` capability is set. |
+| `mjpegServerFramerate` | int | 1..60 | 10 | Maximum frames per second. Higher values increase CPU load on the device. |
+| `mjpegScalingFactor` | int | 1..100 | 50 | Scale factor in percent (100 = no scaling). Lower values reduce size and CPU use. |
+| `mjpegServerScreenshotQuality` | int | 1..100 | 50 | JPEG quality (100 = best). Higher values improve quality but use more CPU. |
+| `mjpegBilinearFiltering` | boolean | true / false | false | Use bilinear filtering when scaling. Can improve scaled image quality with a small performance cost. |
+
+## How it Works
+
+1. When the UiAutomator2 server starts on the device, it starts an **MJPEG server** thread that listens on the configured device port (default 7810).
+2. For each TCP client that connects, the server sends an HTTP-like response with `Content-Type: multipart/x-mixed-replace; boundary=--BoundaryString` and then a continuous stream of JPEG frames (each frame preceded by a boundary and `Content-Length`).
+3. Frames are produced by the device at the configured framerate; each frame is taken via `UiAutomation.takeScreenshot()`, optionally scaled and compressed according to the settings above, then sent to all connected clients.
+4. If no clients are connected, the server does not capture at full rate (it sleeps) to save CPU.
+
+## Using the Stream
+
+### Port forwarding and connecting
+
+1. Set the capability **`appium:mjpegServerPort`** to a free port on the host (e.g. `7810` or any port you choose).
+2. The driver will run `adb forward <host port> 7810` (or the device port you set via the `mjpegServerPort` setting) so that the device MJPEG server is reachable at `http://localhost:<host port>` (or your host IP if you need remote access).
+3. Open that URL in a browser or use any MJPEG-capable client; you should see the live device screen.
+4. Optionally set **`appium:mjpegScreenshotUrl`** to the same URL (e.g. `http://localhost:7810`) so that the driver’s screenshot command uses the latest frame from this stream.
+
+### Screenshot behavior
+
+- **Without `appium:mjpegScreenshotUrl`:** The screenshot command is sent to the UiAutomator2 server (`GET /screenshot`), which takes a single screenshot on demand.
+- **With `appium:mjpegScreenshotUrl`:** The driver keeps an MJPEG client connected to the given URL. The screenshot command returns the latest frame received from that stream (as base64 PNG). If no frame is available yet, the driver falls back to the regular server screenshot and logs a warning.
+
+## Parallel Testing
+
+When running multiple sessions (e.g. parallel tests or multiple devices):
+
+- Set a **unique** `appium:mjpegServerPort` per session so each device’s MJPEG port is forwarded to a different host port.
+- This is especially important if you use screen recording or any tool that connects to the MJPEG stream.
+
+## Performance Considerations
+
+- Higher `mjpegServerFramerate` values increase the number of screenshots taken per second and therefore the CPU load.
+- Higher `mjpegServerScreenshotQuality` values increase JPEG encoding cost and network bandwidth.
+- Higher `mjpegScalingFactor` values (larger images) also increase encoding time and payload size.
+- Enabling `mjpegBilinearFiltering` can improve scaled image quality with a small extra performance cost.
+
+For long-running or parallel streaming, start with moderate defaults (for example, framerate `10`, scaling factor `50`, quality `50`) and then adjust as needed.
+
+## Relationship to `mobile: startScreenStreaming` / `stopScreenStreaming`
+
+The driver also supports **`mobile: startScreenStreaming`** and **`mobile: stopScreenStreaming`**. These are **different** from the built-in device MJPEG server:
+
+- They start or stop a **host-side** MJPEG server that uses **GStreamer** (and optionally ADB) to capture and broadcast the device screen. They require the `adb_screen_streaming` feature and GStreamer with `gst-plugins-base`, `gst-plugins-good`, and `gst-plugins-bad` on the **host**.
+- The **device MJPEG server** described in this guide runs entirely on the device, is built into the UiAutomator2 server, and does not require GStreamer.
+
+Use the **device MJPEG server** (with `appium:mjpegServerPort` and optionally `appium:mjpegScreenshotUrl`) when you only need a simple TCP MJPEG stream from the device. Use **`mobile: startScreenStreaming`** when you need the host-based GStreamer pipeline (e.g. for specific encoding or network options).
+
+## Requirements
+
+- For **device-side MJPEG streaming** itself, no extra tools are required beyond a compatible Android device and the UiAutomator2 server; the broadcaster runs entirely on the device.
+- For **tools that consume the stream** (for example, screen recording on the host), you must ensure whatever tool you use (such as `ffmpeg` or a custom recorder) understands MJPEG over HTTP and can connect to the forwarded MJPEG URL.
+- For **`mobile: startScreenStreaming` / `stopScreenStreaming`**, which are host-side and GStreamer-based, you must have GStreamer with `gst-plugins-base`, `gst-plugins-good`, and `gst-plugins-bad` installed and available on the host `PATH`.
+
+## Summary
+
+| What you want | What to use |
+|---------------|-------------|
+| Expose device screen as MJPEG on the host | Set `appium:mjpegServerPort` to a host port; connect to `http://localhost:<port>`. |
+| Screenshot from the MJPEG stream | Also set `appium:mjpegScreenshotUrl` to that URL (e.g. `http://localhost:<port>`). |
+| Tune framerate, size, or quality on the device | Use Settings API: `mjpegServerFramerate`, `mjpegScalingFactor`, `mjpegServerScreenshotQuality`, `mjpegBilinearFiltering`. |
+| Host-side GStreamer-based streaming | Use `mobile: startScreenStreaming` / `mobile: stopScreenStreaming` (see README). |

package/src/resources/submodules/appium-uiautomator2-driver/docs/scheduled-actions.md

@@ -0,0 +1,155 @@
+# Scheduled Actions
+
+## Problem Statement
+
+Sometimes it is necessary to verify a UI scenario where one has to assert a UI control has appeared on the screen and then perform a decision action on this control. An example of such control might be a notification or any other popup that automatically disappears shortly after being shown. The WebDriver protocol uses HTTP REST API to communicate with clients. This means if you want to assert the existence of the above popup in your test script or perform any action on it then it is necessary to send an HTTP request to the server and receive an answer from it. Furthermore, this is needed for each particular command or assertion you want to perform, e.g. click, find element, get text, etc. The time an HTTP request needs to reach the server and then its response to reach the client is the roundtrip time, and the length of it depends on many factors. For some complex setups the roundtrip duration may even be counted in seconds, which makes it impossible to quickly handle an UI element, because it would already not exist/disappear by the time your next request reaches the server.
+
+## Scheduled Actions Concept
+
+In order to address the problem above we have created the Scheduled Actions concept. The main idea there is to run the action code on the server side in asynchronous manner and only retrieve the detailed execution history if needed. `Action` is this context means emulating a gesture, or taking a screenshot, or taking a xml page source. More actions could be added later. The `scheduled` means after you create an action, or rather describe it in JSON, it is parsed and stored by the server for the further async execution. The client does not have any control over the previously scheduled action and can only unschedule it later or fetch its execution history. All actions are being scheduled on the main UI thread. All scheduled actions are reset automatically upon a new session creation.
+
+This feature is available in the UIA2 driver since version *2.26.0*
+
+## mobile: scheduleAction
+
+Adds a new action to the list of scheduled actions.
+
+### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+name | string | yes | The unique name of the action. | popupHandlingAction
+steps | ActionStep[] | yes | One or more action steps to execute. Steps are executed in sequential order. All steps are executed even if any of them fails. The execution is considered failed if at least one step fails. | Check [Action Steps](#action-steps)
+maxPass | number | no | If set to a number greater than zero then the action will stop rescheduling itself after it passes the desired number of times | 1
+maxFail | number | no | If set to a number greater than zero then the action will stop rescheduling itself after it fails the desired number of times | 1
+times | number | no | How many times the action must be executed itself. 1 by default | 10
+intervalMs | number | no | How long the interval in milliseconds between the next action reschedule should be. 1000 ms by default. | 100
+maxHistoryItems | number | no | The maximum size of the history items array that are stored for this action. Each action execution creates a new history item. All items are sorted in descending order by action execution timestamp. If the amount of executions reaches `maxHistoryItems` value then the oldest history item gets deleted. Be careful to not set this parameter to large values as you might get out of memory issues. 20 history items are being stored for each action by default. | 100
+
+#### Action Steps
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+type | string | yes | One of supported step types: `gesture`, `source`, `screenshot`. | gesture
+name | string | yes | Step name. It must not be unique, but is useful to track the step execution history. | click
+payload | map | yes | Step payload. The payload format depends on the actual step type. | Check on [Step Payload](#step-payload) below
+
+#### Step Payload
+
+Each step payload is required to contain the `subtype` item. Then the combination of step's `type` and `subtype` defines the actual payload content:
+
+Type | Subtype | Description | Payload Example
+--- | --- | --- | ---
+gesture | click | The payload is expected to be similar to the one the [mobile: clickGesture](./android-mobile-gestures.md#mobile-clickgesture) requires. | {subtype: 'click', locator: {strategy: 'id', selector: 'buttonIdentifier'}}
+gesture | longClick | The payload is expected to be similar to the one the [mobile: longClickGesture](./android-mobile-gestures.md#mobile-longclickgesture) requires. | {subtype: 'click', locator: {strategy: 'accessbility id', selector: 'buttonIdentifier'}}
+gesture | doubleClick | The payload is expected to be similar to the one the [mobile: doubleClickGesture](./android-mobile-gestures.md#mobile-doubleclickgesture) requires.  | {subtype: 'click', elementId: 'yolo', x: 150, y: 200}
+source | xml | The payload does not need to contain any other items. | {subtype: 'xml'}
+screenshot | png | The payload does not need to contain any other items. | {subtype: 'png'}
+
+## mobile: getActionHistory
+
+Returns the history of executions for the particular action.
+
+### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+name | string | yes | The unique name of the action. | popupHandlingAction
+
+### Returned Result
+
+The history of executions of the particular action. An error is thrown if no action with the given name has been scheduled before calling this API or if it has been already unscheduled.
+
+The returned result map has the following items:
+
+Name | Type | Description | Example
+--- | --- | --- | ---
+repeats | number | The number of times this action has been repeated so far. | 1
+stepResults | list<list<map>> | The history of step executions for each action run. Items in this list are sorted by execution timestamp in descending order. The maximum length of the list is limited by `maxHistoryItems` action value | See below
+
+The result of each action step is represented by the map inside each `stepResulsts` array item containing the following items:
+
+Name | Type | Description | Example
+--- | --- | --- | ---
+name | string | The name of the corresponding step. | clickStep
+type | string | One of supported step typed. | gesture
+timestamp | number | The Unix timestamp in milliseconds when the step started its execution. | 1685370112000
+passed | boolean | Whether the step has passed, e.g. no exceptions occurred during its execution. | true
+result | any | The actual step result. Depends on the step type and subtype. Might be null. Always null if exception is not null. | something
+exception | map | If an exception happens during the step execution then this map will contain the following items: name (the exception class name), message (the actual exception message), stacktrace (full exception stacktrace). If no exceptions occurs during step execution then the value of this item is always null | {name: 'java.lang.Exception', message: 'Bad things happen', stacktrace: 'happened somewhere'}
+
+## mobile: unscheduleAction
+
+Unschedules an action from the async execution and returns its history.
+
+### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+name | string | yes | The unique name of the action. | popupHandlingAction
+
+### Returned Result
+
+The same as in [mobile: getActionHistory](#mobile-getactionhistory) endpoint
+
+## Usage Example
+
+Let's assume our application under test shows a short-living popup with two buttons to either accept or reject it.
+At first, we need to figure out how the popup looks like in the page source to build element locators. For that we are going to create an action that periodically retrieves page source snapshots:
+
+```python
+driver.execute_script('mobile: scheduleAction', {
+  'name': 'myPopupHandlingAction',
+  'steps': [{
+    'type': 'source',
+    'name': 'fetchPageSourceStep',
+    'payload': {
+      'subtype': 'xml'
+    }
+  }],
+  'intervalMs': 1000,
+  'times': 30,
+  'maxHistoryItems': 30,
+})
+
+# doing some other stuff which is supposed to trigger the popup for the next 30 seconds
+
+history: Dict[str, Any] = driver.execute_script('mobile: unscheduleAction', {
+  'name': 'myPopupHandlingAction',
+})
+```
+
+In the example above we have scheduled an action which takes UI hierarchy snapshot every second. Eventually we can
+debug the value of `history` list and inspect each item for the presence of our expected popup element. After we have figured out locators for its Accept button our action may be updated to:
+
+```python
+driver.execute_script('mobile: scheduleAction', {
+  'name': 'myPopupHandlingAction',
+  'steps': [{
+    'type': 'gesture',
+    'name': 'acceptPopupStep',
+    'payload': {
+      'subtype': 'click'
+      'locator': {
+        'strategy': 'id',
+        'selector': 'acceptButtonIdentifier',
+      }
+    }
+  }],
+  'intervalMs': 1000,
+  'times': 30,
+  'maxPass': 1,
+  'maxHistoryItems': 30,
+})
+
+# doing some other stuff which is supposed to trigger the popup for the next 30 seconds
+
+history: Dict[str, Any] = driver.execute_script('mobile: unscheduleAction', {
+  'name': 'myPopupHandlingAction',
+})
+
+def did_execution_pass(execution: List[Dict]) -> bool:
+    return all((step['passed'] for step in execution))
+
+assert any((did_execution_pass(execution) for exection in history['stepResults']))
+```

package/src/resources/submodules/appium-uiautomator2-driver/docs/uiautomator-uiselector.md

@@ -0,0 +1,51 @@
+## Guide on UiAutomator Locator Types
+
+UIA2 driver enables elements lookup using [UiSelector](https://developer.android.com/reference/androidx/test/uiautomator/UiSelector).
+[UiScrollable](https://developer.android.com/reference/androidx/test/uiautomator/UiScrollable)
+is also supported.
+Both locator types are supported natively by Google's [UiAutomator](https://developer.android.com/training/testing/other-components/ui-automator) framework for Android. With these locators you could create flexible ways to reference complicated element paths, and their performance is very close to native.
+
+### Examples
+
+Note that the index selector is unreliable so prefer instance instead. The
+following examples are written against the [ApiDemos](https://github.com/appium/android-apidemos) apk using Ruby.
+
+Find the first textview.
+
+```ruby
+# ruby
+first_textview = find_element(:uiautomator, 'new UiSelector().className("android.widget.TextView").instance(0)');
+```
+
+Find the first element by text.
+
+```ruby
+# ruby
+first_text = find_element(:uiautomator, 'new UiSelector().text("Animation")')
+first_text.text # "Animation"
+```
+
+Find the first scrollable element, then find a TextView with the text "Tabs".
+The "Tabs" element will be scrolled into view.
+
+```ruby
+# ruby
+element = find_element(:uiautomator, 'new UiScrollable(new UiSelector().scrollable(true).instance(0)).getChildByText(new UiSelector().className("android.widget.TextView"), "Tabs")')
+```
+
+As a special case, scrollIntoView returns the element that is scrolled into view.
+scrollIntoView allows scrolling to any UiSelector.
+
+```ruby
+# ruby
+element = find_element(:uiautomator, 'new UiScrollable(new UiSelector().scrollable(true).instance(0)).scrollIntoView(new UiSelector().text("WebView").instance(0));')
+element.text # "WebView"
+```
+
+### More Resources
+
+- [How to Use UISelector in Appium](http://code2test.com/appium-tutorial/how-to-use-uiselector-in-appium/)
+- [How to use UiSelector to inspect elements on Android](https://www.automationtestinghub.com/uiselector-android/)
+- [UiAutomatorParserTests.java](https://github.com/appium/appium-uiautomator2-server/blob/master/app/src/test/java/io/appium/uiautomator2/utils/UiAutomatorParserTests.java)
+- [UiScrollableParserTests.java](https://github.com/appium/appium-uiautomator2-server/blob/master/app/src/test/java/io/appium/uiautomator2/utils/UiScrollableParserTests.java)
+- [UiSelectorParserTests.java](https://github.com/appium/appium-uiautomator2-server/blob/master/app/src/test/java/io/appium/uiautomator2/utils/UiSelectorParserTests.java)

package/src/resources/submodules/appium-uiautomator2-driver/docs/unlock/main.md

@@ -0,0 +1,95 @@
+# Unlock
+
+UiAutomator2 driver allows dealing with the Android lock screen using various APIs.
+This article describes available APIs and their options.
+
+## Unlock On Session Startup
+
+UiAutomator2 provides the following [capabilities](../../README.md#device-locking) to deal
+with the system lock screen:
+
+- appium:unlockStrategy
+- appium:unlockSuccessTimeout
+- appium:skipUnlock
+- appium:unlockType
+- appium:unlockKey
+
+These capabilities could be used to unlock the device under test during the driver session initialization
+as well as deal with different lock screen types.
+
+### appium:unlockStrategy
+
+Either `locksettings` (default since Android 8/API level 26) or `uiautomator` (legacy).
+
+The `locksettings` strategy uses `adb shell locksettings` CLI to deal with different
+types of device lock screens. It is fast, reliable, but has one downside: the actual
+pin, pattern or password must be temporarily removed in order to unlock the device and restored afterwards.
+
+Setting the strategy to `uiautomator` will enforce the driver to use UiAutomator framework in order
+to interact with the device's lock screen for various unlock types. It might be slower and less stable in comparison
+to the `locksettings` strategy, although there is no other alternative if tests are being executed on an older Android version
+or the application under test requires the device to constantly maintain display lock settings.
+
+### appium:unlockSuccessTimeout
+
+Maximum number of milliseconds to wait until the device is unlocked. `2000` ms by default
+
+### appium:skipUnlock
+
+The `appium:skipUnlock` capability is enabled by default and makes the driver to detect and handle the lock screen
+upon session startup _if it is present_. If the lock screen cannot be detected upon session startup then nothing will be
+done. By default, it is assumed the device has a "simple" lock screen, which could be removed by waking up the device.
+In case the device has a different type of the lock screen configured in its settings then the information about it
+must be provided in the below capability values.
+
+### appium:unlockType and appium:unlockKey
+
+This capability supports the following possible values:
+
+#### pin
+
+Assumes the device is protected with a PIN code. Expects the `appium:unlockKey` to contain a valid pin consisting
+of digits in range 0-9, for example `1111`.
+
+#### pinWithKeyEvent
+
+Same as [pin](#pin), but uses ADB instead of UiAutomator framework to enter the actual pin value.
+
+#### password
+
+Assumes the device is protected with a password. Expects the `appium:unlockKey` to contain a valid password consisting
+of latin characters, for example `abcd1234`.
+
+#### pattern
+
+Assumes the device is protected with a secret pattern. Check the example below for more details on the `appium:unlockKey`
+value for this particular unlock type.
+
+##### Example
+
+Let say you have a device that is locked with a pattern similar to the one on the image below,
+and you want to run a test over that device.
+
+<img src="./screen1.png" />
+
+We treat the pattern pins similarly to numbers on a digital phone dial. So, in this case the *unlockKey* is `729854163`
+
+<img src="./screen2.png" />
+
+and capabilities are:
+
+```json
+{
+  "appium:unlockType": "pattern",
+  "appium:unlockKey": "729854163"
+}
+```
+
+## Mid-Session Unlock
+
+There is also a possibility to interact with the device's lock screen while the test session is running.
+Use the following mobile extensions for this purpose:
+
+- [mobile: lock](../../README.md#mobile-lock)
+- [mobile: unlock](../../README.md#mobile-unlock)
+- [mobile: isLocked](../../README.md#mobile-islocked)

package/src/resources/submodules/appium-xcuitest-driver/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,4 @@
+**Warning:**
+
+These issues are not tracked. Please create new issues in the main Appium
+repository: https://github.com/appium/appium/issues/new