appium-mcp 0.0.1 → 1.1.5

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

@@ -0,0 +1,72 @@
+## Low-Level Insights on Android Input Events
+
+
+### What Are Input Events
+
+Android OS uses events concept to handle signals received from different input devices.
+It supports a wide range of different devices, such as touch screen, light pen, mouse, keyboard,
+but most of them are using [MotionEvent](https://developer.android.com/reference/android/view/MotionEvent) or [KeyEvent](https://developer.android.com/reference/android/view/KeyEvent) APIs, which are derived from the base [InputEvent](https://developer.android.com/reference/android/view/InputEvent) class. These APIs are quite flexible and support a wide range of different settings.
+We are particularly interested in the part of these APIs, which are responsible for touch and
+keyboard events generation/emulation.
+
+
+### How Input Events Are Working
+
+An event is an object, which is generated in response to a signal from an input device.
+These objects are then delivered to the corresponding kernel subsystem, which processes them
+and notifies all listening processes about taps, key presses, swipes, etc.
+This means that in order to emulate a signal generated by
+an external device, such as touch screen, it is necessary to just send event objects with
+the same properties and in the same sequence as they would be generated by a real device.
+
+
+### Lets Simulate a Single Tap
+
+Each input device has a set of actions whose property ranges and sequences are already predefined
+in the operating system. These actions we call "tap", "swipe" or "double tap", etc. The properties
+of each action could be found either in the Android documentation or in the OS source code.
+In order to perform events sequence, which is recognized as single tap, it is necessary to generate
+the following motion events:
+ - `ACTION_POINTER_DOWN`
+ - wait 125ms (525ms or longer wait will synthesize a long tap action instead)
+ - `ACTION_POINTER_UP`. The `downTime` property should be set to the same timestamp as for `ACTION_POINTER_DOWN`
+
+It is also important, that coordinates and other properties of both the starting and the closing event should be equal except of the `eventTime` one, which is always equal to the current system timestamp in milliseconds (`SystemClock.uptimeMillis()`).
+The `MotionEvent` object itself could be created via [obtain](https://developer.android.com/reference/android/view/MotionEvent#obtain(long,%20long,%20int,%20float,%20float,%20int)) API, where parameters are the corresponding event properties.
+
+After events are created they must be passed to the system for execution.
+Such action is not secure, so it is only possible in instrumented tests via [injectInputEvent](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/IUiAutomationConnection.aidl) method of `IUiAutomationConnection` interface.
+This is a very low-level method and it can only be accessed via reflection in automated tests.
+Normally, UiAutomator APIs have wrappers over it (like `touchDown`, `touchMove`, etc.), that already simulate the stuff described above.
+
+
+### How About More Complicated Actions
+
+In theory it is possible to emulate any input action using a generated events sequence.
+Although, some actions, like multi-finger swipe,
+are really complicated and require a lot of events to be generated
+with correct properties and timings. The OS simply ignores given events if they don't follow
+internal action requirements. There is also a little assistance from UiAutomator framework,
+because Google only has wrappers for a limited set of simple actions, like `tap`, `drag` or `swipe`.
+So, in order to generate two-finger symmetric swipe we need to supply the following events chain:
+ - `ACTION_POINTER_DOWN` (finger1)
+ - `ACTION_POINTER_DOWN` (finger2)
+ - start a loop, that generates `ACTION_POINTER_MOVE` event each `20ms` for both `finger1` and `finger2` until `ACTION_POINTER_UP` is performed. The `downTime` should be set to the same timestamp as for the corresponding `ACTION_POINTER_DOWN`. The coordinates of each move event should be points belonging to the path between the corresponding start and end point coordinates normalized by the current timestamp (x0 + sqrt(sqr(x0) + sqr(x1))) * k, y0 + sqrt(sqr(y0) + sqr(y1))) * k).
+ - `ACTION_POINTER_UP` (finger1) The `downTime` property should be set to the same timestamp as for the corresponding `ACTION_POINTER_DOWN`
+ - `ACTION_POINTER_UP` (finger2) The `downTime` property should be set to the same timestamp as for the corresponding `ACTION_POINTER_DOWN`
+
+Google uses 5ms as interval duration between move events in UiAutomator code,
+but according to our observations this value is too little,
+which causes noticeable delays in actions execution.
+
+
+### Further Reading
+
+Unfortunately, there is no so much detailed information on this topic. The only reliable source
+of the information are Android OS sources themselves. Consider visiting the following resources:
+
+- https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/view/ViewConfiguration.java
+- https://android.googlesource.com/platform/frameworks/uiautomator/+/refs/heads/master
+- https://github.com/appium/appium-uiautomator2-server/tree/master/app/src/main/java/io/appium/uiautomator2/utils/w3c
+- https://github.com/appium/appium-uiautomator2-server/tree/master/app/src/test/java/io/appium/uiautomator2/utils/w3c
+- https://github.com/appium/appium-espresso-driver/tree/master/espresso-server/library/src/main/java/io/appium/espressoserver/lib/helpers/w3c

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

@@ -0,0 +1,47 @@
+## How To Troubleshoot Activities Startup
+
+
+### Capabilities
+
+> The Activity class is a crucial component of an Android app, and the way activities are launched and put together is a fundamental part of the platform's application model. Unlike programming paradigms in which apps are launched with a main() method, the Android system initiates code in an Activity instance by invoking specific callback methods that correspond to specific stages of its lifecycle.
+> © [Android Developer Documentation](https://developer.android.com/guide/components/activities/intro-activities)
+
+Appium needs to know package and activity names in order to properly initialize the application under test. This information is expected to be provided in driver capabilities and consists of the following keys:
+
+- `appActivity`: The name of the main application activity
+- `appPackage`: The identifier of the application package
+- `appWaitActivity`: The name of the application activity to wait for/which starts the first
+- `appWaitPackage`: The id of the application package to wait for/which starts the first
+- `appWaitDuration`: The maximum duration to wait until the `appWaitActivity` is focused in milliseconds (20000 by default)
+- `appWaitForLaunch`: Whether to wait until Activity Manager returns the control to the calling process. By default the driver always waits until `appWaitDuration` is expired. Setting this capability to `false` effectively cancels this wait and unblocks the server loop as soon as `am` successfully triggers the command to start the activity.
+
+All these capabilities are optional. If they are not set explicitly then Appium tries to auto detect them by reading their values from the APK manifest. Although, if the application under test is supposed to be already installed on the device (`noReset=true`) then at least `appActivity` and `appPackage` options are required to be set, since no package manifest is available in such case. If you don't set `appWaitPackage` and `appWaitActivity` explicitly then these are getting assigned to `appPackage`/`appActivity` values automatically. For more details check on the implementation of `packageAndLaunchActivityFromManifest` method in the [appium-adb](https://github.com/appium/appium-adb/blob/master/lib/tools/android-manifest.js) package.
+
+
+### How Appium Starts Activities
+
+Activities are started by [Call activity manager `am`](https://developer.android.com/studio/command-line/adb#am). Appium tries to start the `appPackage`/`appActivity` combination using `am start` and then waits until the `appWaitPackage`/`appWaitActivity` is focused or the `appWaitDuration` timeout expires. The currently focused activity name is parsed from `adb shell dumpsys window windows` command output (`mFocusedApp` or `mCurrentFocus` entries). For more details check on the implementation of `startApp`, and `getFocusedPackageAndActivity` methods in the [appium-adb](https://github.com/appium/appium-adb/blob/master/lib/tools/apk-utils.js) package.
+
+
+### Possible Problems And Solutions
+
+#### java.lang.SecurityException: Permission Denial: starting Intent
+
+The full error description usually looks like `'java.lang.SecurityException: Permission Denial: starting Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] flg=0x10200000 cmp=com.mypackage/.myactivity.MainActivity launchParam=MultiScreenLaunchParams { mDisplayId=0 mBaseDisplayId=0 mFlags=0 } } from null (pid=11366, uid=2000) not exported from uid 10191`. Such error might be the indication of the fact that the combination of application package and activity name, which has been passed to Appium as `appPackage`/`appActivity` (or auto detected implicitly), is not the correct one to start the application under test. As a solution, it is necessary to check the correct values with the application developer and test them manually first by executing: `adb shell am start -W -n com.myfixedpackage/.myfixedactivity.MainActivity -S -a android.intent.action.MAIN -c android.intent.category.LAUNCHER -f 0x10200000`. If this commands succeeds manually and starts the necessary application on the device then it will work for Appium as well.
+
+Some devices might require customization of the security configuration in the developer options, or security preferences. For example, Realme devices require [_Disable Permission Monitoring_ and a couple of flags in the developer options](https://github.com/appium/appium/issues/13802#issuecomment-702789411) to avoid the _Permission Denial_ error.
+
+#### com.myactivity or com.myapp.com.myactivity never started
+
+This exception usually indicates, that the first application activity is not the same package/activity, as it is set (or auto detected) by `appWaitPackage`/`appWaitActivity`. Such error normally happens in applications having multiple activities. In order to resolve the problem one should check with application developer regarding which activity/package is the very first one that appears on application startup. The currently focused activity name might be verified using the `adb shell dumpsys window windows` command mentioned above. Also, Appium allows to use wildcards while setting `appWaitActivity` value. This might be particularly useful if the activity name is generated dynamically or it is not the same all the time. For example `com.mycomany.*` will match any of `com.mycomany.foo`, `com.mycomany.bar`.
+
+#### Command '…' timed out after X ms
+
+If you've double checked that activity names are correct, but the startup still times out, then try to increase the value of `appWaitDuration` capability. Normally, the default 20 seconds is enough for the most of applications, however, some bigger apps might require more time to start and show the first activity. Please, don't create such apps.
+
+There might be also situations where an activity does not return the control to the calling process at all, so `am start` call blocks forever independently of the value of `appWaitDuration`, thus causing the timeout. In such case setting `appWaitForLaunch` to `false` might help to resolve the issue. Although, by choosing this option, the driver cannot make sure the activity has fully started, so then it is up to the client code to verify the initial UI state is the one that is expected.
+
+
+#### java.util.concurrent.ExecutionException: com.google.firebase.installations.FirebaseInstallationsException
+
+`firebaseinstallations.googleapis.com` sends the apk's certificate information as the header `X-Android-Cert` in its initialization step. Appium UiAutomator2 driver resigns the application under test with the default Appium debug signature. It causes an exception, `java.util.concurrent.ExecutionException: com.google.firebase.installations.FirebaseInstallationsException`, when the application under test starts. To avoid the exception, the session must have `noSign: true` capability to avoid re-signing. [Unblocking Firebase Network Traffic in Modified Android Applications](https://www.thecobraden.com/posts/unblocking_firebase_ids/) explains the cause more.

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

@@ -0,0 +1,69 @@
+## How To Test Android App Bundle
+
+Google has released the [Android App Bundle](https://developer.android.com/platform/technology/app-bundle/) feature.
+An `.aab` file is generated by the feature, which we are supposed to upload to the Google Play Store. We can manage the `.aab` file via CLI using the official [bundletool](https://developer.android.com/studio/command-line/bundletool) which is available from [bundletool](https://github.com/google/bundletool). [The guide](https://developer.android.com/guide/app-bundle/) also help us to understand the feature.
+
+We can get distributed apk files from the `.aab` file via the CLI. Using the generated files, we can test against the release module. Since Appium 1.9.2, you can Appium tests against an `.apks` file using UiAutomator2 driver. [1](https://github.com/appium/appium-adb/pull/367) and [2](https://github.com/appium/appium-base-driver/pull/271) are PRs for the feature.
+
+## How to run tests
+
+1. Export `bundletool.jar` in your path
+    - Appium looks for `bundletool.jar` in your local environemnt. Make sure you can find the path with `which 'bundletool.jar'`. If you can't find it, please set the path correctly.
+    - Please make sure the bundletool version is above 1.6.0
+2. Generate the `.apks` file from the `.aab` file
+    - The `.aab` is available over Android Studio 3.2
+    - You must sign correctly when you generate `.apks` from `.aab`. This step requires data signing.
+
+```bash
+$ java -jar apks/bundletool.jar build-apks \
+    --bundle apks/release/release/app.aab \ # A generated aab file
+    --output apks/AppBundleSample.apks \    # An apks file you'd like to out put to
+    --ks apks/sign \                        # Signing keystore
+    --ks-key-alias key0 \                   # Alias of the keytstore
+    --ks-pass pass:kazucocoa \              # Password of the keystore
+    --overwrite                             # Overwrite any existing apks files
+```
+
+3. Use the path to the `.apks` file as your `app` capability.
+
+```ruby
+capabilities = {
+    platformName: :android,
+    automationName: 'uiautomator2',
+    platformVersion: '8.1',
+    deviceName: 'Android Emulator',
+    app: "path/to/your.apks",   # This line is important
+    fullReset: true,
+    ...
+}
+
+core = ::Appium::Core.for capabilities: capabilities
+driver = core.start_driver
+```
+
+You can find another way to get test APKs in https://developer.android.com/guide/app-bundle/
+
+You could also install `.apks` bundles via Install App command like below.
+
+```ruby
+# Ruby
+driver.execute_script 'mobile: installApp', {appPath: 'path/to/your.apks'}
+```
+
+## Tips
+### Make `bundletool.jar` executable
+
+Make sure the bundletool is executable.
+`$ chmod 655 /path/to/bundletool.jar` can make it executable, for example.
+
+### Test with different languages
+
+Set `fullReset: true` if you would like to test against the app using different languages' resources.
+
+Appium only installs the minimum set of resources, following the behavior of the appbundle feature. For example, if a device's language is set of English, Appium will only install the `en` resource. The installed apk will have no Japanese resources.
+
+In orfer to force re-install with a different set of language resources, specify `fullReset: true`
+
+## An example project
+
+- https://github.com/KazuCocoa/AppBundleSample

package/src/resources/submodules/appium-uiautomator2-driver/docs/android-mobile-gestures.md

@@ -0,0 +1,352 @@
+## Automating Mobile Gestures With UiAutomator2 Backend
+
+Touch actions are the most advanced and the most complicated way to
+implement any Android gesture. Although, there is a couple of basic
+gestures, like swipe, fling or pinch, which are commonly used in
+Android applications and for which it makes sense to have shortcuts,
+where only high-level options are configurable.
+
+
+### mobile: longClickGesture
+
+This gesture performs long click action on the given element/coordinates.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be clicked.
+  If the element is missing then both click offset coordinates must be provided.
+  If both the element id and offset are provided then the coordinates
+  are parsed as relative offsets from the top left corner of the element.
+ * _x_: The x-offset coordinate
+ * _y_: The y-offset coordinate
+ * _duration_: Click duration in milliseconds. `500` by default. The value must not be negative
+ * _locator_: The map containing [strategy and selector](../README.md#element-location) items to make it possible
+  to click dynamic elements.
+
+#### Usage examples
+
+```java
+// Java
+((JavascriptExecutor) driver).executeScript("mobile: longClickGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId()
+));
+```
+
+```python
+# Python
+driver.execute_script('mobile: longClickGesture', {'x': 100, 'y': 100, 'duration': 1000})
+```
+
+
+### mobile: doubleClickGesture
+
+This gesture performs double click action on the given element/coordinates.
+Available since Appium v1.21
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be clicked.
+  If the element is missing then both click offset coordinates must be provided.
+  If both the element id and offset are provided then the coordinates
+  are parsed as relative offsets from the top left corner of the element.
+ * _x_: The x-offset coordinate
+ * _y_: The y-offset coordinate
+ * _locator_: The map containing [strategy and selector](../README.md#element-location) items to make it possible
+  to click dynamic elements.
+
+#### Usage examples
+
+```java
+// Java
+((JavascriptExecutor) driver).executeScript("mobile: doubleClickGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId()
+));
+```
+
+```python
+# Python
+driver.execute_script('mobile: doubleClickGesture', {'x': 100, 'y': 100})
+```
+
+
+### mobile: clickGesture
+
+This gesture performs click action on the given element/coordinates.
+Available since Appium UiAutomator2 driver 1.71.0. Usage of this gesture is recommended
+as a possible workaround for cases where the "native" tap call fails,
+even though tap coordinates seem correct. This issue is related to the fact
+these calls use the legacy UIAutomator-based calls while this extension
+is based on the same foundation as W3C does.
+
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be clicked.
+  If the element is missing then both click offset coordinates must be provided.
+  If both the element id and offset are provided then the coordinates
+  are parsed as relative offsets from the top left corner of the element.
+ * _x_: The x-offset coordinate
+ * _y_: The y-offset coordinate
+ * _locator_: The map containing [strategy and selector](../README.md#element-location) items to make it possible
+  to click dynamic elements.
+
+#### Usage examples
+
+```java
+// Java
+driver.executeScript("mobile: clickGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId()
+));
+```
+
+```python
+# Python
+driver.execute_script('mobile: clickGesture', {'x': 100, 'y': 100})
+```
+
+```javascript
+// Javascript - @wdio
+await driver.executeScript('mobile: clickGesture', [{x: 100, y: 100}]);
+```
+
+### mobile: dragGesture
+
+This gesture performs drag action from the given element/coordinates to the given point.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be dragged.
+  If the element id is missing then both start coordinates must be provided.
+  If both the element id and the start coordinates are provided then these
+  coordinates are considered as offsets from the top left element corner.
+ * _startX_: The x-start coordinate
+ * _startY_: The y-start coordinate
+ * _endX_: The x-end coordinate. Mandatory argument
+ * _endY_: The y-end coordinate. Mandatory argument
+ * _speed_:  The speed at which to perform this gesture in pixels per second.
+  The value must not be negative. The default value is `2500 * displayDensity`
+
+#### Usage examples
+
+```java
+// Java
+((JavascriptExecutor) driver).executeScript("mobile: dragGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId(),
+    "endX", 100,
+    "endY", 100
+));
+```
+
+
+### mobile: flingGesture
+
+This gesture performs fling gesture on the given element/area.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be flinged.
+  If the element id is missing then fling bounding area must be provided.
+  If both the element id and the fling bounding area are provided then this
+  area is effectively ignored.
+ * _left_: The left coordinate of the fling bounding area
+ * _top_: The top coordinate of the fling bounding area
+ * _width_: The width of the fling bounding area
+ * _height_: The height of the fling bounding area
+ * _direction_: Direction of the fling. Mandatory value.
+  Acceptable values are: `up`, `down`, `left` and `right` (case insensitive)
+ * _speed_:  The speed at which to perform this
+  gesture in pixels per second. The value must be greater than the minimum fling
+  velocity for the given view (50 by default). The default value is `7500 * displayDensity`
+
+#### Returned value
+
+The returned value is a boolean one and equals to `true` if the object can still scroll in the given direction
+
+#### Usage examples
+
+```java
+// Java
+boolean canScrollMore = (Boolean) ((JavascriptExecutor) driver).executeScript("mobile: flingGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId(),
+    "direction", "down",
+    "speed", 500
+));
+```
+
+```javascript
+// Javascript - @wdio
+await driver.executeScript('mobile: flingGesture', [{
+    elementId: element.elementId,
+    direction: 'right',
+    speed: 500,
+}]);
+```
+
+
+### mobile: pinchOpenGesture
+
+This gesture performs pinch-open gesture on the given element/area.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be pinched.
+  If the element id is missing then pinch bounding area must be provided.
+  If both the element id and the pinch bounding area are provided then the
+  area is effectively ignored.
+ * _left_: The left coordinate of the pinch bounding area
+ * _top_: The top coordinate of the pinch bounding area
+ * _width_: The width of the pinch bounding area
+ * _height_: The height of the pinch bounding area
+ * _percent_: The size of the pinch as a percentage of the pinch area size.
+  Valid values must be float numbers in range 0..1, where 1.0 is 100%.
+  Mandatory value.
+ * _speed_:  The speed at which to perform this gesture in pixels per second.
+  The value must not be negative. The default value is `2500 * displayDensity`
+
+#### Usage examples
+
+```java
+// Java
+((JavascriptExecutor) driver).executeScript("mobile: pinchOpenGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId(),
+    "percent", 0.75
+));
+```
+
+
+### mobile: pinchCloseGesture
+
+This gesture performs pinch-close gesture on the given element/area.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be pinched.
+  If the element id is missing then pinch bounding area must be provided.
+  If both the element id and the pinch bounding area are provided then the
+  area is effectively ignored.
+ * _left_: The left coordinate of the pinch bounding area
+ * _top_: The top coordinate of the pinch bounding area
+ * _width_: The width of the pinch bounding area
+ * _height_: The height of the pinch bounding area
+ * _percent_: The size of the pinch as a percentage of the pinch area size.
+  Valid values must be float numbers in range 0..1, where 1.0 is 100%.
+  Mandatory value.
+ * _speed_:  The speed at which to perform this gesture in pixels per second.
+  The value must not be negative. The default value is `2500 * displayDensity`
+
+#### Usage examples
+
+```java
+// Java
+((JavascriptExecutor) driver).executeScript("mobile: pinchCloseGesture", ImmutableMap.of(
+    "elementId", ((RemoteWebElement) element).getId(),
+    "percent", 0.75
+));
+```
+
+```python
+# Python
+can_scroll_more = driver.execute_script('mobile: pinchCloseGesture', {
+    'elementId': element.id,
+    'percent': 0.75
+})
+```
+
+
+### mobile: swipeGesture
+
+This gesture performs swipe gesture on the given element/area.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be swiped.
+  If the element id is missing then swipe bounding area must be provided.
+  If both the element id and the swipe bounding area are provided then the
+  area is effectively ignored.
+ * _left_: The left coordinate of the swipe bounding area
+ * _top_: The top coordinate of the swipe bounding area
+ * _width_: The width of the swipe bounding area
+ * _height_: The height of the swipe bounding area
+ * _direction_: Swipe direction. Mandatory value.
+  Acceptable values are: `up`, `down`, `left` and `right` (case insensitive)
+ * _percent_: The size of the swipe as a percentage of the swipe area size.
+  Valid values must be float numbers in range 0..1, where 1.0 is 100%.
+  Mandatory value.
+ * _speed_:  The speed at which to perform this gesture in pixels per second.
+  The value must not be negative. The default value is `5000 * displayDensity`
+
+#### Usage examples
+
+```java
+// Java
+((JavascriptExecutor) driver).executeScript("mobile: swipeGesture", ImmutableMap.of(
+    "left", 100, "top", 100, "width", 200, "height", 200,
+    "direction", "left",
+    "percent", 0.75
+));
+```
+
+```python
+# Python
+driver.execute_script('mobile: swipeGesture', {
+    'left': 100,
+    'top': 100,
+    'width': 200,
+    'height': 200,
+    'direction': direction, 'percent': 0.75
+})
+```
+
+
+### mobile: scrollGesture
+
+This gesture performs scroll gesture on the given element/area.
+Available since Appium v1.19
+
+#### Supported arguments
+
+ * _elementId_: The id of the element to be scrolled.
+  If the element id is missing then scroll bounding area must be provided.
+  If both the element id and the scroll bounding area are provided then this
+  area is effectively ignored.
+ * _left_: The left coordinate of the scroll bounding area
+ * _top_: The top coordinate of the scroll bounding area
+ * _width_: The width of the scroll bounding area
+ * _height_: The height of the scroll bounding area
+ * _direction_: Scrolling direction. Mandatory value.
+  Acceptable values are: `up`, `down`, `left` and `right` (case insensitive)
+ * _percent_: The size of the scroll as a percentage of the scrolling area size.
+  Valid values must be float numbers greater than zero, where 1.0 is 100%.
+  Mandatory value.
+ * _speed_:  The speed at which to perform this gesture in pixels per second.
+  The value must not be negative. The default value is `5000 * displayDensity`
+
+#### Returned value
+
+The returned value is a boolean one and equals to `true` if the object can still scroll in the given direction
+
+#### Usage examples
+
+```java
+// Java
+boolean canScrollMore = (Boolean) ((JavascriptExecutor) driver).executeScript("mobile: scrollGesture", ImmutableMap.of(
+    "left", 100, "top", 100, "width", 200, "height", 200,
+    "direction", "down",
+    "percent", 1.0
+));
+```
+
+```python
+# Python
+can_scroll_more = driver.execute_script('mobile: scrollGesture', {
+    'left': 100, 'top': 100, 'width': 200, 'height': 200,
+    'direction': 'down',
+    'percent': 3.0
+})
+```

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.