appium-android-driver 7.8.2 → 8.0.0

package/lib/commands/types.ts

@@ -1,5 +1,6 @@
-import {HTTPMethod, StringRecord} from '@appium/types';
-import {InstallOptions, UninstallOptions} from 'appium-adb';
+import type {HTTPMethod, StringRecord} from '@appium/types';
+import type {InstallOptions, UninstallOptions} from 'appium-adb';
+import type {AndroidDriverCaps} from '../driver';
 
 export interface SwipeOpts {
   startX: number;
@@ -186,12 +187,16 @@ export interface WebviewsMapping {
   webview: string;
   /**
    * Webview information as it is retrieved by `/json/version` CDP endpoint
+   *
+   * This value becomes `undefined` when the retrieval failed.
    */
   info?: StringRecord;
   /**
    * Webview pages list as it is retrieved by `/json/list` CDP endpoint
+   *
+   * This value becomes `undefined` when the retrieval failed.
    */
-  pages: StringRecord[];
+  pages?: StringRecord[];
   /**
    * An actual webview name for switching context.
    *
@@ -1081,7 +1086,7 @@ export type SwipeAction = [
   NonReleaseTouchAction,
   NonReleaseTouchAction,
   NonReleaseTouchAction,
-  ReleaseTouchAction
+  ReleaseTouchAction,
 ];
 
 export type TouchDragAction = [NonReleaseTouchAction, NonReleaseTouchAction, ReleaseTouchAction];
@@ -1096,16 +1101,23 @@ export interface LockOpts {
 
 export interface DeviceidleOpts {
   /** The action name to execute */
-  action: 'whitelistAdd'|'whitelistRemove';
+  action: 'whitelistAdd' | 'whitelistRemove';
   /** Either a single package or multiple packages to add or remove from the idle whitelist */
-  packages?: string|string[];
+  packages?: string | string[];
 }
 
 export interface SendTrimMemoryOpts {
   /** The package name to send the `trimMemory` event to */
   pkg: string;
   /** The actual memory trim level to be sent */
-  level: 'COMPLETE' | 'MODERATE' | 'BACKGROUND' | 'UI_HIDDEN' | 'RUNNING_CRITICAL' | 'RUNNING_LOW' | 'RUNNING_MODERATE';
+  level:
+    | 'COMPLETE'
+    | 'MODERATE'
+    | 'BACKGROUND'
+    | 'UI_HIDDEN'
+    | 'RUNNING_CRITICAL'
+    | 'RUNNING_LOW'
+    | 'RUNNING_MODERATE';
 }
 
 export interface SetUiModeOpts {
@@ -1134,17 +1146,137 @@ export interface GetUiModeOpts {
 export interface SmsListResultItem {
   id: string;
   address: string;
-  person: string|null;
+  person: string | null;
   date: string;
   read: string;
   status: string;
   type: string;
-  subject: string|null;
+  subject: string | null;
   body: string;
-  serviceCenter: string|null;
+  serviceCenter: string | null;
 }
 
 export interface SmsListResult {
   items: SmsListResultItem[];
   total: number;
 }
+
+export interface GetWebviewsOpts {
+  /**
+   * device socket name
+   */
+  androidDeviceSocket?: string | null;
+  /**
+   * whether to check for webview page presence
+   */
+  ensureWebviewsHavePages?: boolean | null;
+  /**
+   * port to use for webview page presence check.
+   */
+  webviewDevtoolsPort?: number | null;
+  /**
+   * whether to collect web view details and send them to Chromedriver constructor, so it could select a binary more precisely based on this info.
+   */
+  enableWebviewDetailsCollection?: boolean | null;
+  /**
+   * @privateRemarks This is referenced but was not previously declared
+   */
+  isChromeSession?: boolean;
+
+  waitForWebviewMs?: number | string;
+}
+
+export interface ProcessInfo {
+  /**
+   * The process name
+   */
+  name: string;
+  /**
+   * The process id (if could be retrieved)
+   */
+  id?: string | null;
+}
+
+export interface WebViewDetails {
+  /**
+   * Web view process details
+   */
+  process?: ProcessInfo | null;
+  /**
+   * Web view details as returned by /json/version CDP endpoint
+   * @example
+   * {
+   *  "Browser": "Chrome/72.0.3601.0",
+   *  "Protocol-Version": "1.3",
+   *  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3601.0 Safari/537.36",
+   *  "V8-Version": "7.2.233",
+   *  "WebKit-Version": "537.36 (@cfede9db1d154de0468cb0538479f34c0755a0f4)",
+   *  "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/b0b8a4fb-bb17-4359-9533-a8d9f3908bd8"
+   * }
+   */
+  info?: StringRecord;
+}
+
+export interface DetailCollectionOptions {
+  /**
+   * The starting port to use for webview page presence check (if not the default of 9222).
+   */
+  webviewDevtoolsPort?: number | null;
+  /**
+   * Whether to check for webview pages presence
+   */
+  ensureWebviewsHavePages?: boolean | null;
+  /**
+   * Whether to collect web view details and send them to Chromedriver constructor, so it could
+   * select a binary more precisely based on this info.
+   */
+  enableWebviewDetailsCollection?: boolean | null;
+}
+
+export interface WebviewProps {
+  /**
+   * The name of the Devtools Unix socket
+   */
+  proc: string;
+  /**
+   * The web view alias. Looks like `WEBVIEW_` prefix plus PID or package name
+   */
+  webview: string;
+  /**
+   * Webview information as it is retrieved by /json/version CDP endpoint
+   */
+  info?: object | null;
+  /**
+   * Webview pages list as it is retrieved by /json/list CDP endpoint
+   */
+  pages?: object[] | null;
+}
+
+export interface WebviewProc {
+  /**
+   * The webview process name (as returned by getPotentialWebviewProcs)
+   */
+  proc: string;
+  /**
+   * The actual webview context name
+   */
+  webview: string;
+}
+
+export interface FastUnlockOptions {
+  credential: string;
+  /**
+   * @privateRemarks FIXME: narrow this type to whatever `appium-adb` expects
+   */
+  credentialType: string;
+}
+
+export interface ADBDeviceInfo {
+  udid: string;
+  emPort: number | false;
+}
+
+export type ADBLaunchInfo = Pick<
+  AndroidDriverCaps,
+  'appPackage' | 'appWaitActivity' | 'appActivity' | 'appWaitPackage'
+>;

package/lib/doctor/checks.js

@@ -4,14 +4,16 @@ import path from 'path';
 import '@colors/colors';
 import {getAndroidBinaryPath, getSdkRootFromEnv} from 'appium-adb';
 
-
 const JAVA_HOME_VAR_NAME = system.isWindows() ? '%JAVA_HOME%' : '$JAVA_HOME';
-const ENVIRONMENT_VARS_TUTORIAL_URL = 'https://github.com/appium/java-client/blob/master/docs/environment.md';
-const JAVA_HOME_TUTORIAL = 'https://docs.oracle.com/cd/E21454_01/html/821-2531/inst_jdk_javahome_t.html';
+const ENVIRONMENT_VARS_TUTORIAL_URL =
+  'https://github.com/appium/java-client/blob/master/docs/environment.md';
+const JAVA_HOME_TUTORIAL =
+  'https://docs.oracle.com/cd/E21454_01/html/821-2531/inst_jdk_javahome_t.html';
 const ANDROID_SDK_LINK1 = 'https://developer.android.com/studio#cmdline-tools';
 const ANDROID_SDK_LINK2 = 'https://developer.android.com/studio/intro/update#sdk-manager';
 const BUNDLETOOL_RELEASES_LINK = 'https://github.com/google/bundletool/releases/';
-const GSTREAMER_INSTALL_LINK = 'https://gstreamer.freedesktop.org/documentation/installing/index.html?gi-language=c';
+const GSTREAMER_INSTALL_LINK =
+  'https://gstreamer.freedesktop.org/documentation/installing/index.html?gi-language=c';
 const FFMPEG_INSTALL_LINK = 'https://www.ffmpeg.org/download.html';
 
 /**
@@ -39,7 +41,7 @@ class EnvVarAndPathCheck {
       return doctor.nok(`${this.varName} environment variable is NOT set!`);
     }
 
-    if (!await fs.exists(varValue)) {
+    if (!(await fs.exists(varValue))) {
       let errMsg = `${this.varName} is set to '${varValue}' but this path does not exist!`;
       if (system.isWindows() && varValue.includes('%')) {
         errMsg += ` Consider replacing all references to other environment variables with absolute paths.`;
@@ -49,10 +51,14 @@ class EnvVarAndPathCheck {
 
     const stat = await fs.stat(varValue);
     if (this.opts.expectDir && !stat.isDirectory()) {
-      return doctor.nok(`${this.varName} is expected to be a valid folder, got a file path instead`);
+      return doctor.nok(
+        `${this.varName} is expected to be a valid folder, got a file path instead`,
+      );
     }
     if (this.opts.expectFile && stat.isDirectory()) {
-      return doctor.nok(`${this.varName} is expected to be a valid file, got a folder path instead`);
+      return doctor.nok(
+        `${this.varName} is expected to be a valid file, got a folder path instead`,
+      );
     }
 
     return doctor.ok(`${this.varName} is set to: ${varValue}`);
@@ -86,18 +92,20 @@ export class JavaHomeValueCheck {
 
     const javaBinaryRelativePath = path.join('bin', `java${system.isWindows() ? '.exe' : ''}`);
     const javaBinary = path.join(envVar, javaBinaryRelativePath);
-    if (!await fs.exists(javaBinary)) {
+    if (!(await fs.exists(javaBinary))) {
       return doctor.nok(
         `${JAVA_HOME_VAR_NAME} is set to an invalid value. ` +
-        `It must be pointing to a folder containing ${javaBinaryRelativePath}`
+          `It must be pointing to a folder containing ${javaBinaryRelativePath}`,
       );
     }
     return doctor.ok(`'${javaBinaryRelativePath}' exists under '${envVar}'`);
   }
 
   async fix() {
-    return `Set ${JAVA_HOME_VAR_NAME} environment variable to the root folder path of your local JDK installation. ` +
-      `Read ${JAVA_HOME_TUTORIAL}`;
+    return (
+      `Set ${JAVA_HOME_VAR_NAME} environment variable to the root folder path of your local JDK installation. ` +
+      `Read ${JAVA_HOME_TUTORIAL}`
+    );
   }
 
   hasAutofix() {
@@ -121,9 +129,7 @@ export class AndroidSdkCheck {
     const listOfTools = this.TOOL_NAMES.join(', ');
     const sdkRoot = getSdkRootFromEnv();
     if (!sdkRoot) {
-      return doctor.nok(
-        `${listOfTools} could not be found because ANDROID_HOME is NOT set!`
-      );
+      return doctor.nok(`${listOfTools} could not be found because ANDROID_HOME is NOT set!`);
     }
 
     this.log.info(`   Checking ${listOfTools}`);
@@ -199,9 +205,11 @@ export class OptionalGstreamerCheck {
 
     return gstreamerPath && gstInspectPath
       ? doctor.okOptional(
-          `${this.GSTREAMER_BINARY} and ${this.GST_INSPECT_BINARY} are installed at: ${gstreamerPath} and ${gstInspectPath}`
+          `${this.GSTREAMER_BINARY} and ${this.GST_INSPECT_BINARY} are installed at: ${gstreamerPath} and ${gstInspectPath}`,
         )
-      : doctor.nokOptional(`${this.GSTREAMER_BINARY} and/or ${this.GST_INSPECT_BINARY} cannot be found`);
+      : doctor.nokOptional(
+          `${this.GSTREAMER_BINARY} and/or ${this.GST_INSPECT_BINARY} cannot be found`,
+        );
   }
 
   async fix() {