appium-uiautomator2-driver 6.7.6 → 6.7.7

package/lib/commands/navigation.ts

@@ -0,0 +1,32 @@
+import type {AndroidUiautomator2Driver} from '../driver';
+
+/**
+ * Sets the URL for the current app.
+ * @param url - The URL to navigate to.
+ */
+export async function setUrl(this: AndroidUiautomator2Driver, url: string): Promise<void> {
+  await this.adb.startUri(url, this.opts.appPackage as string);
+}
+
+/**
+ * Starts a URL that takes users directly to specific content in the app.
+ * @param url - The deep link URL to start.
+ * @param pkg - Optional package name to start the URI with. If not provided, uses the current app package.
+ * @param waitForLaunch - If false, adb won't wait for the started activity to return control. Defaults to true.
+ */
+export async function mobileDeepLink(
+  this: AndroidUiautomator2Driver,
+  url: string,
+  pkg?: string,
+  waitForLaunch: boolean = true,
+): Promise<void> {
+  return await this.adb.startUri(url, pkg, {waitForLaunch});
+}
+
+/**
+ * Navigates back in the app.
+ */
+export async function back(this: AndroidUiautomator2Driver): Promise<void> {
+  await this.adb.keyevent(4);
+}
+

package/lib/commands/viewport.ts

@@ -0,0 +1,78 @@
+import type {Rect, Size} from '@appium/types';
+import type {AndroidUiautomator2Driver} from '../driver';
+import type {RelativeRect} from './types';
+
+/**
+ * Gets the status bar height in pixels.
+ * @returns The status bar height in pixels.
+ */
+export async function getStatusBarHeight(this: AndroidUiautomator2Driver): Promise<number> {
+  const {statusBar} = (await this.uiautomator2.jwproxy.command(`/appium/device/system_bars`, 'GET', {})) as {
+    statusBar: number;
+  };
+  return statusBar;
+}
+
+/**
+ * Gets the device pixel ratio.
+ * @returns The device pixel ratio as a string.
+ */
+export async function getDevicePixelRatio(this: AndroidUiautomator2Driver): Promise<string> {
+  return String(await this.uiautomator2.jwproxy.command('/appium/device/pixel_ratio', 'GET', {}));
+}
+
+/**
+ * Gets the viewport rectangle coordinates.
+ * @returns The viewport rectangle (left, top, width, height), accounting for status bar height.
+ */
+export async function getViewPortRect(this: AndroidUiautomator2Driver): Promise<RelativeRect> {
+  const windowSize = await this.getWindowSize();
+  const statusBarHeight = await this.getStatusBarHeight();
+  // android returns the upscaled window size, so to get the true size of the
+  // rect we have to downscale
+  return {
+    left: 0,
+    top: statusBarHeight,
+    width: windowSize.width,
+    height: windowSize.height - statusBarHeight,
+  };
+}
+
+/**
+ * Returns the viewport coordinates.
+ * @returns The viewport rectangle (left, top, width, height).
+ */
+export async function mobileViewPortRect(this: AndroidUiautomator2Driver): Promise<RelativeRect> {
+  return await this.getViewPortRect();
+}
+
+/**
+ * Gets the window rectangle (W3C endpoint).
+ * @returns The window rectangle (x, y, width, height).
+ */
+export async function getWindowRect(this: AndroidUiautomator2Driver): Promise<Rect> {
+  const {width, height} = await this.getWindowSize();
+  return {
+    width,
+    height,
+    x: 0,
+    y: 0,
+  };
+}
+
+/**
+ * Gets the display density.
+ * @returns The display density value.
+ */
+export async function getDisplayDensity(this: AndroidUiautomator2Driver): Promise<number> {
+  return (await this.uiautomator2.jwproxy.command('/appium/device/display_density', 'GET', {})) as number;
+}
+
+/**
+ * Gets the window size.
+ * @returns The window size (width, height).
+ */
+export async function getWindowSize(this: AndroidUiautomator2Driver): Promise<Size> {
+  return (await this.uiautomator2.jwproxy.command('/window/current/size', 'GET', {})) as Size;
+}
+

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-uiautomator2-driver",
-  "version": "6.7.6",
+  "version": "6.7.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-uiautomator2-driver",
-      "version": "6.7.6",
+      "version": "6.7.7",
       "license": "Apache-2.0",
       "dependencies": {
         "appium-adb": "^14.0.0",

package/package.json

@@ -7,7 +7,7 @@
     "automated testing",
     "android"
   ],
-  "version": "6.7.6",
+  "version": "6.7.7",
   "bugs": {
     "url": "https://github.com/appium/appium-uiautomator2-driver/issues"
   },

package/lib/commands/actions.js

@@ -1,107 +0,0 @@
-/**
- * @see https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-scheduleaction
- * @this {AndroidUiautomator2Driver}
- * @param {string} name
- * @param {import('@appium/types').StringRecord[]} steps
- * @param {number} [maxPass]
- * @param {number} [maxFail]
- * @param {number} [times]
- * @param {number} [intervalMs]
- * @param {number} [maxHistoryItems]
- * @returns {Promise<any>}
- */
-export async function mobileScheduleAction(
-  name,
-  steps,
-  maxPass,
-  maxFail,
-  times,
-  intervalMs,
-  maxHistoryItems,
-) {
-  return await this.uiautomator2.jwproxy.command(
-    '/appium/schedule_action',
-    'POST',
-    {
-      name,
-      steps,
-      maxFail,
-      maxPass,
-      times,
-      intervalMs,
-      maxHistoryItems,
-    }
-  );
-}
-
-/**
- * @see https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-getactionhistory
- * @this {AndroidUiautomator2Driver}
- * @param {string} name
- * @returns {Promise<import('./types').ActionResult>}
- */
-export async function mobileGetActionHistory(name) {
-  return /** @type {import('./types').ActionResult} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/appium/action_history',
-      'POST',
-      {name}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @see https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-unscheduleaction
- * @param {string} name
- * @returns {Promise<any>}
- */
-export async function mobileUnscheduleAction(name) {
-  return await this.uiautomator2.jwproxy.command(
-    '/appium/unschedule_action',
-    'POST',
-    {name}
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {import('@appium/types').StringRecord[]} actions
- * @returns {Promise<void>}
- */
-export async function performActions(actions) {
-  // This is mandatory, since Selenium API uses MOUSE as the default pointer type
-  const preprocessedActions = actions.map((action) =>
-    Object.assign(
-      {},
-      action,
-      action.type === 'pointer'
-        ? {
-            parameters: {
-              pointerType: 'touch',
-            },
-          }
-        : {}
-    )
-  );
-  this.log.debug(`Preprocessed actions: ${JSON.stringify(preprocessedActions, null, '  ')}`);
-  await this.uiautomator2.jwproxy.command(
-    '/actions',
-    'POST',
-    {
-      actions: preprocessedActions,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function releaseActions() {
-  this.log.info('On this platform, releaseActions is a no-op');
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/alert.js

@@ -1,63 +0,0 @@
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<string>}
- */
-export async function getAlertText() {
-  return String(
-    await this.uiautomator2.jwproxy.command(
-      '/alert/text',
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} [buttonLabel] The name of the button to click in order to accept the alert.
- * If the name is not provided
- * then the script will try to detect the button automatically.
- * @returns {Promise<void>}
- */
-export async function mobileAcceptAlert(buttonLabel) {
-  await this.uiautomator2.jwproxy.command(
-    '/alert/accept',
-    'POST',
-    {buttonLabel}
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function postAcceptAlert() {
-  await this.mobileAcceptAlert();
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} [buttonLabel] The name of the button to click in order to dismiss the alert.
- * If the name is not provided
- * then the script will try to detect the button automatically.
- * @returns {Promise<void>}
- */
-export async function mobileDismissAlert(buttonLabel) {
-  await this.uiautomator2.jwproxy.command(
-    '/alert/dismiss',
-    'POST',
-    {buttonLabel}
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function postDismissAlert() {
-  await this.mobileDismissAlert();
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/app-management.js

@@ -1,32 +0,0 @@
-import _ from 'lodash';
-import B from 'bluebird';
-import {errors} from 'appium/driver';
-import {APK_EXTENSION} from '../extensions';
-
-/**
- * Install multiple APKs with `install-multiple` option.
- * @this {AndroidUiautomator2Driver}
- * @param {string[]} apks The list of APKs to install. Each APK should be a path to a apk
- * or downloadable URL as HTTP/HTTPS.
- * @param {import('./types').InstallOptions} [options] Installation options.
- * @throws {Error} if an error occured while installing the given APKs.
- * @returns {Promise<void>}
- */
-export async function mobileInstallMultipleApks(apks, options) {
-  if (!_.isArray(apks) || _.isEmpty(apks)) {
-    throw new errors.InvalidArgumentError('No apks are given to install');
-  }
-  const configuredApks = await B.all(
-    apks.map((app) => this.helpers.configureApp(app, [APK_EXTENSION]))
-  );
-  await this.adb.installMultipleApks(configuredApks, options);
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */
-
-/**
- * @template [T=any]
- * @typedef {import('@appium/types').StringRecord<T>} StringRecord
- */

package/lib/commands/battery.js

@@ -1,23 +0,0 @@
-
-/**
- * Reads the battery information from the device under test.
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('./types').BatteryInfo>} The actual battery info
- */
-export async function mobileGetBatteryInfo() {
-  const result = /** @type {import('./types').MapKey<BatteryInfo, 'state', 'status'>} */ (
-    await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
-      this.uiautomator2
-    ).jwproxy.command('/appium/device/battery_info', 'GET', {})
-  );
-  const batteryInfo = /** @type {any} */ (result);
-  // Give it the same name as in iOS
-  batteryInfo.state = result.status;
-  delete batteryInfo.status;
-  return /** @type {BatteryInfo} */ (batteryInfo);
-}
-
-/**
- * @typedef {import('./types').BatteryInfo} BatteryInfo
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/clipboard.js

@@ -1,37 +0,0 @@
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<string>} Base64-encoded content of the clipboard
- * or an empty string if the clipboard is empty.
- */
-export async function getClipboard() {
-  return String(
-    (await this.adb.getApiLevel()) < 29
-      ? await this.uiautomator2.jwproxy.command(
-          '/appium/device/get_clipboard',
-          'POST',
-          {}
-        )
-      : await this.settingsApp.getClipboard()
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} content Base64-encoded clipboard payload
- * @param {'plaintext'} [contentType='plaintext'] Only a single
- * content type is supported, which is 'plaintext'
- * @param {string} [label] Optinal label to identify the current
- * clipboard payload
- * @returns {Promise<void>}
- */
-export async function setClipboard(content, contentType, label) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/device/set_clipboard',
-    'POST',
-    {content, contentType, label}
-  );
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/find.js

@@ -1,47 +0,0 @@
-import {CssConverter} from '../css-converter';
-
-// we override the xpath search for this first-visible-child selector, which
-// looks like /*[@firstVisible="true"]
-const MAGIC_FIRST_VIS_CHILD_SEL = /\/\*\[@firstVisible ?= ?('|")true\1\]/;
-
-const MAGIC_SCROLLABLE_SEL = /\/\/\*\[@scrollable ?= ?('|")true\1\]/;
-const MAGIC_SCROLLABLE_BY = 'new UiSelector().scrollable(true)';
-
-/**
- * @privateRemarks Overriding helpers.doFindElementOrEls functionality of appium-android-driver,
- * this.element initialized in find.js of appium-android-drive.
- *
- * @this {AndroidUiautomator2Driver}
- * @param {import('appium-android-driver').FindElementOpts} params
- * @returns {Promise<Element | Element[]>}
- */
-export async function doFindElementOrEls(params) {
-  const uiautomator2 = /** @type {import('../uiautomator2').UiAutomator2Server} */ (
-    this.uiautomator2
-  );
-  if (params.strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(params.selector)) {
-    let elementId = params.context;
-    return /** @type {Element} */ (
-      await uiautomator2.jwproxy.command(`/appium/element/${elementId}/first_visible`, 'GET', {})
-    );
-  }
-  if (params.strategy === 'xpath' && MAGIC_SCROLLABLE_SEL.test(params.selector)) {
-    params.strategy = '-android uiautomator';
-    params.selector = MAGIC_SCROLLABLE_BY;
-  }
-  if (params.strategy === 'css selector') {
-    params.strategy = '-android uiautomator';
-    params.selector = new CssConverter(
-      params.selector,
-      this.opts.appPackage
-    ).toUiAutomatorSelector();
-  }
-  return /** @type {Element|Element[]} */ (
-    await uiautomator2.jwproxy.command(`/element${params.multiple ? 's' : ''}`, 'POST', params)
-  );
-}
-
-/**
- * @typedef {import('@appium/types').Element} Element
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/keyboard.js

@@ -1,108 +0,0 @@
-import { errors } from 'appium/driver';
-import _ from 'lodash';
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|number} keycode
- * @param {number} [metastate]
- * @param {number} [flags]
- * @returns {Promise<void>}
- */
-export async function pressKeyCode(keycode, metastate, flags) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/device/press_keycode',
-    'POST',
-    {
-      keycode,
-      metastate,
-      flags,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|number} keycode
- * @param {number} metastate
- * @param {number} [flags]
- * @returns {Promise<void>}
- */
-export async function longPressKeyCode(keycode, metastate, flags) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/device/long_press_keycode',
-    'POST',
-    {
-      keycode,
-      metastate,
-      flags,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {number} keycode A valid Android key code. See https://developer.android.com/reference/android/view/KeyEvent
- * for the list of available key codes.
- * @param {number} [metastate] An integer in which each bit set to 1 represents a pressed meta key. See
- * https://developer.android.com/reference/android/view/KeyEvent for more details.
- * @param {string} [flags] Flags for the particular key event. See
- * https://developer.android.com/reference/android/view/KeyEvent for more details.
- * @param {boolean} [isLongPress=false] Whether to emulate long key press
- * @returns {Promise<void>}
- */
-export async function mobilePressKey(keycode, metastate, flags, isLongPress = false) {
-  await this.uiautomator2.jwproxy.command(
-    `/appium/device/${isLongPress ? 'long_' : ''}press_keycode`,
-    'POST',
-    {
-      keycode,
-      metastate,
-      flags,
-    }
-  );
-}
-
-/**
- * Types the given Unicode string.
- * It is expected that the focus is already put
- * to the destination input field before this method is called.
- *
- * @this {AndroidUiautomator2Driver}
- * @param {string | number | boolean} text The text to type. Can be a string, number or boolean.
- * @returns {Promise<boolean>} `true` if the input text has been successfully sent to adb
- * @throws {Error} if `text` property has not been provided
- */
-export async function mobileType(text) {
-  if (_.isUndefined(text)) {
-    throw new errors.InvalidArgumentError(`The 'text' argument is mandatory`);
-  }
-  return await this.settingsApp.typeUnicode(String(text));
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {import('appium-android-driver').SendKeysOpts} params
- * @returns {Promise<void>}
- */
-export async function doSendKeys(params) {
-  await this.uiautomator2.jwproxy.command(
-    '/keys',
-    'POST',
-    params
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|number} keycode
- * @param {number} [metastate]
- * @returns {Promise<void>}
- */
-export async function keyevent(keycode, metastate) {
-  this.log.debug(`Ignoring metastate ${metastate}`);
-  await this.adb.keyevent(keycode);
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/navigation.js

@@ -1,33 +0,0 @@
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} url
- * @returns {Promise<void>}
- */
-export async function setUrl(url) {
-  await this.adb.startUri(url, /** @type {string} */ (this.opts.appPackage));
-}
-
-/**
- * Start URL that take users directly to specific content in the app
- * @this {AndroidUiautomator2Driver}
- * @param {string} url The name of URL to start.
- * @param {string} [pkg] The name of the package to start the URI with.
- * @param {boolean} [waitForLaunch=true] If `false` then adb won't wait for
- * the started activity to return the control.
- * @returns {Promise<void>}
- */
-export async function mobileDeepLink(url, pkg, waitForLaunch) {
-  return await this.adb.startUri(url, pkg, {waitForLaunch});
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function back() {
-  await this.adb.keyevent(4);
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/viewport.js

@@ -1,100 +0,0 @@
-
-// memoized in constructor
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<number>}
- */
-export async function getStatusBarHeight() {
-  const {statusBar} = /** @type {{statusBar: number}} */ (
-    await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
-      this.uiautomator2
-    ).jwproxy.command(`/appium/device/system_bars`, 'GET', {})
-  );
-  return statusBar;
-}
-
-// memoized in constructor
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<string>}
- */
-export async function getDevicePixelRatio() {
-  return String(
-    await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
-      this.uiautomator2
-    ).jwproxy.command('/appium/device/pixel_ratio', 'GET', {})
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('./types').RelativeRect>}
- */
-export async function getViewPortRect() {
-  const windowSize = await this.getWindowSize();
-  const statusBarHeight = await this.getStatusBarHeight();
-  // android returns the upscaled window size, so to get the true size of the
-  // rect we have to downscale
-  return {
-    left: 0,
-    top: statusBarHeight,
-    width: windowSize.width,
-    height: windowSize.height - statusBarHeight,
-  };
-}
-
-/**
- * Returns the viewport coordinates.
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('./types').RelativeRect>} The viewport coordinates.
- */
-export async function mobileViewPortRect() {
-  return await this.getViewPortRect();
-}
-
-// For W3C
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('@appium/types').Rect>}
- */
-export async function getWindowRect() {
-  const {width, height} = await this.getWindowSize();
-  return {
-    width,
-    height,
-    x: 0,
-    y: 0,
-  };
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<number>}
- */
-export async function getDisplayDensity() {
-  return /** @type {number} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/appium/device/display_density',
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('@appium/types').Size>}
- */
-export async function getWindowSize() {
-  return /** @type {import('@appium/types').Size} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/window/current/size',
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */