appium-mcp 0.0.1 → 1.1.4

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/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