appium-android-driver 15.0.0-beta.2 → 15.0.0

package/lib/commands/media-projection.ts

@@ -6,9 +6,24 @@ import type {HTTPMethod, StringRecord} from '@appium/types';
 import type {ADB} from 'appium-adb';
 import dayjs from 'dayjs';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {FormFields} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    mobileIsMediaProjectionRecordingRunning(
+      ...args: Parameters<typeof mobileIsMediaProjectionRecordingRunning>
+    ): ReturnType<typeof mobileIsMediaProjectionRecordingRunning>;
+    mobileStartMediaProjectionRecording(
+      ...args: Parameters<typeof mobileStartMediaProjectionRecording>
+    ): ReturnType<typeof mobileStartMediaProjectionRecording>;
+    mobileStopMediaProjectionRecording(
+      ...args: Parameters<typeof mobileStopMediaProjectionRecording>
+    ): ReturnType<typeof mobileStopMediaProjectionRecording>;
+  }
+}
+
 // https://github.com/appium/io.appium.settings#internal-audio--video-recording
 const DEFAULT_EXT = '.mp4';
 const MIN_API_LEVEL = 29;

package/lib/commands/memory.ts

@@ -1,8 +1,15 @@
 import {errors} from 'appium/driver.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {TrimMemoryLevel} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    mobileSendTrimMemory(...args: Parameters<typeof mobileSendTrimMemory>): ReturnType<typeof mobileSendTrimMemory>;
+  }
+}
+
 /**
  * Simulates the onTrimMemory() event for the given package.
  * Read https://developer.android.com/topic/performance/memory

package/lib/commands/misc.ts

@@ -1,9 +1,24 @@
 import type {Size, Rect, StringRecord} from '@appium/types';
 import {errors} from 'appium/driver.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {SmsListResult, ListSmsOpts} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    getWindowRect(...args: Parameters<typeof getWindowRect>): ReturnType<typeof getWindowRect>;
+    getWindowSize(...args: Parameters<typeof getWindowSize>): ReturnType<typeof getWindowSize>;
+    getDisplayDensity(...args: Parameters<typeof getDisplayDensity>): ReturnType<typeof getDisplayDensity>;
+    mobileGetNotifications(
+      ...args: Parameters<typeof mobileGetNotifications>
+    ): ReturnType<typeof mobileGetNotifications>;
+    mobileListSms(...args: Parameters<typeof mobileListSms>): ReturnType<typeof mobileListSms>;
+    openNotifications(...args: Parameters<typeof openNotifications>): ReturnType<typeof openNotifications>;
+    setUrl(...args: Parameters<typeof setUrl>): ReturnType<typeof setUrl>;
+  }
+}
+
 /**
  * Gets the window size.
  *

package/lib/commands/network.ts

@@ -1,9 +1,25 @@
 import {util} from '@appium/support';
 import {errors} from 'appium/driver.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {ServiceType, GetConnectivityResult} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    getNetworkConnection(...args: Parameters<typeof getNetworkConnection>): ReturnType<typeof getNetworkConnection>;
+    isWifiOn(...args: Parameters<typeof isWifiOn>): ReturnType<typeof isWifiOn>;
+    mobileGetConnectivity(...args: Parameters<typeof mobileGetConnectivity>): ReturnType<typeof mobileGetConnectivity>;
+    mobileSetConnectivity(...args: Parameters<typeof mobileSetConnectivity>): ReturnType<typeof mobileSetConnectivity>;
+    setNetworkConnection(...args: Parameters<typeof setNetworkConnection>): ReturnType<typeof setNetworkConnection>;
+    setWifiState(...args: Parameters<typeof setWifiState>): ReturnType<typeof setWifiState>;
+    setDataState(...args: Parameters<typeof setDataState>): ReturnType<typeof setDataState>;
+    toggleData(...args: Parameters<typeof toggleData>): ReturnType<typeof toggleData>;
+    toggleFlightMode(...args: Parameters<typeof toggleFlightMode>): ReturnType<typeof toggleFlightMode>;
+    toggleWiFi(...args: Parameters<typeof toggleWiFi>): ReturnType<typeof toggleWiFi>;
+  }
+}
+
 const AIRPLANE_MODE_MASK = 0b001;
 const WIFI_MASK = 0b010;
 const DATA_MASK = 0b100;
@@ -120,9 +136,9 @@ export async function mobileGetConnectivity(
   const unsupportedServices = svcs.filter((svc) => !SUPPORTED_SERVICE_NAMES.includes(svc));
   if (unsupportedServices.length > 0) {
     throw new errors.InvalidArgumentError(
-      `${util.pluralize('Service name', unsupportedServices.length, false)} ${unsupportedServices} ` +
+      `${util.pluralize('Service name', unsupportedServices.length, false)} ${unsupportedServices.join(', ')} ` +
         `${unsupportedServices.length === 1 ? 'is' : 'are'} not known. Only the following services are ` +
-        `suported: ${SUPPORTED_SERVICE_NAMES}`,
+        `suported: ${SUPPORTED_SERVICE_NAMES.join(', ')}`,
     );
   }
 

package/lib/commands/nfc.ts

@@ -1,8 +1,15 @@
 import {errors} from 'appium/driver.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {NfcAction} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    mobileNfc(...args: Parameters<typeof mobileNfc>): ReturnType<typeof mobileNfc>;
+  }
+}
+
 const SUPPORTED_ACTIONS = {
   ENABLE: 'enable',
   DISABLE: 'disable',
@@ -27,7 +34,7 @@ export async function mobileNfc(this: AndroidDriver, action: NfcAction): Promise
       break;
     default:
       throw new errors.InvalidArgumentError(
-        `You must provide a valid 'action' argument. Supported actions are: ${Object.values(SUPPORTED_ACTIONS)}`,
+        `You must provide a valid 'action' argument. Supported actions are: ${Object.values(SUPPORTED_ACTIONS).join(', ')}`,
       );
   }
 }

package/lib/commands/performance.ts

@@ -2,9 +2,22 @@ import {util} from '@appium/support';
 import {retryInterval} from 'asyncbox';
 import type {ExecError} from 'teen_process';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {PerformanceDataType} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    getPerformanceData(...args: Parameters<typeof getPerformanceData>): ReturnType<typeof getPerformanceData>;
+    getPerformanceDataTypes(
+      ...args: Parameters<typeof getPerformanceDataTypes>
+    ): ReturnType<typeof getPerformanceDataTypes>;
+    mobileGetPerformanceData(
+      ...args: Parameters<typeof mobileGetPerformanceData>
+    ): ReturnType<typeof mobileGetPerformanceData>;
+  }
+}
+
 export const NETWORK_KEYS = [
   ['bucketStart', 'activeTime', 'rxBytes', 'rxPackets', 'txBytes', 'txPackets', 'operations', 'bucketDuration'],
   ['st', 'activeTime', 'rb', 'rp', 'tb', 'tp', 'op', 'bucketDuration'],

package/lib/commands/permissions.ts

@@ -1,9 +1,19 @@
 import {util} from '@appium/support';
 import {errors} from 'appium/driver.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import {ADB_SHELL_FEATURE} from '../utils.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    mobileChangePermissions(
+      ...args: Parameters<typeof mobileChangePermissions>
+    ): ReturnType<typeof mobileChangePermissions>;
+    mobileGetPermissions(...args: Parameters<typeof mobileGetPermissions>): ReturnType<typeof mobileGetPermissions>;
+  }
+}
+
 const ALL_PERMISSIONS_MAGIC = 'all';
 const PM_ACTION = Object.freeze({
   GRANT: 'grant',
@@ -87,7 +97,9 @@ export async function mobileChangePermissions(
         action?.toLowerCase() as AppOpsAction,
       );
     default:
-      throw new errors.InvalidArgumentError(`'target' argument must be one of: ${Object.values(PERMISSION_TARGET)}`);
+      throw new errors.InvalidArgumentError(
+        `'target' argument must be one of: ${Object.values(PERMISSION_TARGET).join(', ')}`,
+      );
   }
 }
 /**
@@ -138,7 +150,7 @@ async function changePermissionsViaPm(
 
   let affectedPermissions = Array.isArray(permissions) ? permissions : [permissions];
   if (typeof permissions === 'string' && permissions.toLowerCase() === ALL_PERMISSIONS_MAGIC) {
-    const dumpsys = await this.adb.shell(['dumpsys', 'package', appPackage]);
+    const dumpsys = await this.adb.shell(['dumpsys', 'package', util.quote(appPackage)]);
     const grantedPermissions = await this.adb.getGrantedPermissions(appPackage, dumpsys);
     if (action === PM_ACTION.GRANT) {
       const reqPermissons = await this.adb.getReqPermissions(appPackage, dumpsys);
@@ -178,7 +190,7 @@ async function changePermissionsViaAppops(
   }
 
   const promises = (Array.isArray(permissions) ? permissions : [permissions]).map((permission) =>
-    this.adb.shell(['appops', 'set', appPackage, permission, action]),
+    this.adb.shell(['appops', 'set', util.quote(appPackage), util.quote(permission), action]),
   );
   await Promise.all(promises);
 }

package/lib/commands/recordscreen.ts

@@ -6,9 +6,17 @@ import type {ADB} from 'appium-adb';
 import {waitForCondition} from 'asyncbox';
 import {exec} from 'teen_process';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {StartScreenRecordingOpts, StopScreenRecordingOpts, ScreenRecordingProperties} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    startRecordingScreen(...args: Parameters<typeof startRecordingScreen>): ReturnType<typeof startRecordingScreen>;
+    stopRecordingScreen(...args: Parameters<typeof stopRecordingScreen>): ReturnType<typeof stopRecordingScreen>;
+  }
+}
+
 const RETRY_PAUSE = 300;
 const RETRY_TIMEOUT = 5000;
 const MAX_RECORDING_TIME_SEC = 60 * 3;

package/lib/commands/resources.ts

@@ -1,9 +1,17 @@
 import {fs, tempDir, util} from '@appium/support';
 import type {StringRecord} from '@appium/types';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver, AndroidDriverOpts} from '../driver.js';
 import type {Locale} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    getStrings(...args: Parameters<typeof getStrings>): ReturnType<typeof getStrings>;
+    ensureDeviceLocale(...args: Parameters<typeof ensureDeviceLocale>): ReturnType<typeof ensureDeviceLocale>;
+  }
+}
+
 /**
  * Gets the localized strings from the application.
  *
@@ -68,7 +76,7 @@ export async function ensureDeviceLocale(
       this.log.debug((e1 as Error).stack);
     }
     if (suggestions.length > 0) {
-      errMsg += ` You may want to apply one of the following locales instead: ${suggestions}`;
+      errMsg += ` You may want to apply one of the following locales instead: ${suggestions.join(', ')}`;
     }
     throw new Error(errMsg, {cause: e});
   }

package/lib/commands/shell.ts

@@ -3,9 +3,21 @@ import {errors} from 'appium/driver.js';
 import {exec} from 'teen_process';
 import type {ExecError} from 'teen_process';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import {ADB_SHELL_FEATURE} from '../utils.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    mobileShell<T extends boolean>(
+      command: string,
+      args?: string[],
+      timeout?: number,
+      includeStderr?: T,
+    ): Promise<T extends true ? {stdout: string; stderr: string} : string>;
+  }
+}
+
 /**
  * Executes a shell command on the device via ADB.
  *

package/lib/commands/streamscreen.ts

@@ -10,9 +10,21 @@ import {waitForCondition} from 'asyncbox';
 import {checkPortStatus} from 'portscanner';
 import {SubProcess, exec} from 'teen_process';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {DeviceInfo, InitGStreamerPipelineOpts} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    mobileStartScreenStreaming(
+      ...args: Parameters<typeof mobileStartScreenStreaming>
+    ): ReturnType<typeof mobileStartScreenStreaming>;
+    mobileStopScreenStreaming(
+      ...args: Parameters<typeof mobileStopScreenStreaming>
+    ): ReturnType<typeof mobileStopScreenStreaming>;
+  }
+}
+
 const RECORDING_INTERVAL_SEC = 5;
 const STREAMING_STARTUP_TIMEOUT_MS = 5000;
 const GSTREAMER_BINARY = `gst-launch-1.0${system.isWindows() ? '.exe' : ''}`;

package/lib/commands/system-bars.ts

@@ -2,9 +2,19 @@ import {util} from '@appium/support';
 import type {StringRecord} from '@appium/types';
 import {errors} from 'appium/driver.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 import type {StatusBarCommand, WindowProperties} from './types.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    getSystemBars(...args: Parameters<typeof getSystemBars>): ReturnType<typeof getSystemBars>;
+    mobilePerformStatusBarCommand(
+      ...args: Parameters<typeof mobilePerformStatusBarCommand>
+    ): ReturnType<typeof mobilePerformStatusBarCommand>;
+  }
+}
+
 const WINDOW_TITLE_PATTERN = /^\s+Window\s#\d+\sWindow\{[0-9a-f]+\s\w+\s([\w-]+)\}:$/;
 const FRAME_PATTERN = /\bm?[Ff]rame=\[([0-9.-]+),([0-9.-]+)\]\[([0-9.-]+),([0-9.-]+)\]/;
 // https://github.com/appium/appium-uiautomator2-driver/issues/904
@@ -88,7 +98,7 @@ export async function mobilePerformStatusBarCommand(
   if (!action) {
     throw new errors.InvalidArgumentError(
       `The '${command}' status bar command is unknown. Only the following commands ` +
-        `are supported: ${Object.keys(statusBarCommands)}`,
+        `are supported: ${Object.keys(statusBarCommands).join(', ')}`,
     );
   }
   return await action();
@@ -181,7 +191,7 @@ export function parseWindows(this: AndroidDriver, lines: string): SystemBarsResu
     this.log.info(
       `No windows have been found whose title matches to ` +
         `'${namePrefix}'. Assuming it is invisible. ` +
-        `Only the following windows are available: ${Object.keys(windows)}`,
+        `Only the following windows are available: ${Object.keys(windows).join(', ')}`,
     );
     result[window as keyof SystemBarsResult] = structuredClone(DEFAULT_WINDOW_PROPERTIES);
   }

package/lib/commands/time.ts

@@ -2,8 +2,16 @@ import dayjs from 'dayjs';
 import customParseFormat from 'dayjs/plugin/customParseFormat.js';
 import utc from 'dayjs/plugin/utc.js';
 
+import type {AndroidDriverConstraints} from '../constraints.js';
 import type {AndroidDriver} from '../driver.js';
 
+declare module '../driver.js' {
+  interface AndroidDriver<C extends AndroidDriverConstraints> {
+    getDeviceTime(...args: Parameters<typeof getDeviceTime>): ReturnType<typeof getDeviceTime>;
+    mobileGetDeviceTime(...args: Parameters<typeof mobileGetDeviceTime>): ReturnType<typeof mobileGetDeviceTime>;
+  }
+}
+
 dayjs.extend(utc);
 dayjs.extend(customParseFormat);
 

package/lib/constraints.ts

@@ -151,9 +151,6 @@ export const ANDROID_DRIVER_CONSTRAINTS = {
   recreateChromeDriverSessions: {
     isBoolean: true,
   },
-  autoLaunch: {
-    isBoolean: true,
-  },
   nativeWebScreenshot: {
     isBoolean: true,
   },
@@ -209,6 +206,22 @@ export const ANDROID_DRIVER_CONSTRAINTS = {
   localeScript: {
     isString: true,
   },
+  locale: {
+    isString: true,
+  },
+  language: {
+    isString: true,
+  },
+  autoWebview: {
+    isBoolean: true,
+  },
+  orientation: {
+    isString: true,
+    inclusionCaseInsensitive: ['LANDSCAPE', 'PORTRAIT'],
+  },
+  udid: {
+    isString: true,
+  },
   skipDeviceInitialization: {
     isBoolean: true,
   },