appium-espresso-driver 2.29.3 → 2.31.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.31.0](https://github.com/appium/appium-espresso-driver/compare/v2.30.0...v2.31.0) (2024-01-06)
+
+
+### Features
+
+* Add doctor checks ([#962](https://github.com/appium/appium-espresso-driver/issues/962)) ([bb153f4](https://github.com/appium/appium-espresso-driver/commit/bb153f413b5be3cb2f1a4f79032a5f50aefd377b))
+
+## [2.30.0](https://github.com/appium/appium-espresso-driver/compare/v2.29.3...v2.30.0) (2023-12-19)
+
+
+### Features
+
+* let mobile: getContexts gives waitForWebviewMs ([#960](https://github.com/appium/appium-espresso-driver/issues/960)) ([cefd205](https://github.com/appium/appium-espresso-driver/commit/cefd205a184187fb5c03c90defbc6acf02ed6e6d))
+
 ## [2.29.3](https://github.com/appium/appium-espresso-driver/compare/v2.29.2...v2.29.3) (2023-12-02)
 
 

package/README.md

@@ -37,6 +37,12 @@ On top of standard Appium requirements Espresso driver also expects the followin
 - Both the server package and the application under test must be signed with the same digital signature. Appium does sign them automatically upon session creation, so this could only be an issue if one wants to test an application, which is already installed on the device (using `noReset=true` capability).
 - The package under test must not have mangled class names (e.g. [Proguard](https://developer.android.com/studio/build/shrink-code) must not be enabled for it)
 
+### Doctor
+
+Since driver version 2.31.0 you can automate the validation for the most of the above
+requirements as well as various optional ones needed by driver extensions by running the
+`appium driver doctor espresso` server command.
+
 
 ## Scripts
 
@@ -655,7 +661,13 @@ buttonState | int | no | Button state id, `0` by default | 1
 
 ### mobile: getContexts
 
-Retrieves a webviews mapping based on CDP endpoints
+Retrieves a WebViews mapping based on CDP endpoints
+
+#### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+waitForWebviewMs | number | no | Tells Espresso driver for how long (in milliseconds) to wait for web view(s) to appear since Espresso driver v2.30.0. If a Chrome process running on the device under test fails to create a connection to the devtools socket, then the chromedriver will rise an error similar to `failed to connect to socket 'localabstract:chrome_devtools_remote'` in Espresso driver. It could cause no WebViews found result, although a couple of retrials may fix it. This argument helps to keep trying to get WebView(s) up to the given time milliseconds as one command call. This issue tends to occur Chrome v115 and over so far. [issues#19251](https://github.com/appium/appium/issues/19251) contains more details. If set to `0`ms (the default value), then Espresso driver only checks the WebView(s) availability once. | 10000
 
 #### Returns
 

package/build/lib/doctor/optional-checks.d.ts

@@ -0,0 +1,4 @@
+export const optionalBundletoolCheck: doctor.OptionalBundletoolCheck;
+export const optionalFfmpegCheck: doctor.OptionalFfmpegCheck;
+import { doctor } from 'appium-android-driver';
+//# sourceMappingURL=optional-checks.d.ts.map

package/build/lib/doctor/optional-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-checks.d.ts","sourceRoot":"","sources":["../../../lib/doctor/optional-checks.js"],"names":[],"mappings":"AAEA,qEAAsE;AACtE,6DAA8D;uBAHvC,uBAAuB"}

package/build/lib/doctor/optional-checks.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionalFfmpegCheck = exports.optionalBundletoolCheck = void 0;
+const appium_android_driver_1 = require("appium-android-driver");
+exports.optionalBundletoolCheck = appium_android_driver_1.doctor.optionalBundletoolCheck;
+exports.optionalFfmpegCheck = appium_android_driver_1.doctor.optionalFfmpegCheck;
+//# sourceMappingURL=optional-checks.js.map

package/build/lib/doctor/optional-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-checks.js","sourceRoot":"","sources":["../../../lib/doctor/optional-checks.js"],"names":[],"mappings":";;;AAAA,iEAA+C;AAElC,QAAA,uBAAuB,GAAG,8BAAM,CAAC,uBAAuB,CAAC;AACzD,QAAA,mBAAmB,GAAG,8BAAM,CAAC,mBAAmB,CAAC"}

package/build/lib/doctor/required-checks.d.ts

@@ -0,0 +1,30 @@
+export const androidHomeCheck: {
+    varName: string;
+    opts: doctorCommon.EnvVarCheckOptions;
+    diagnose(): Promise<import("@appium/types").DoctorCheckResult>;
+    fix(): Promise<string>;
+    hasAutofix(): boolean;
+    isOptional(): boolean;
+};
+export const javaHomeCheck: {
+    varName: string;
+    opts: doctorCommon.EnvVarCheckOptions;
+    diagnose(): Promise<import("@appium/types").DoctorCheckResult>;
+    fix(): Promise<string>;
+    hasAutofix(): boolean;
+    isOptional(): boolean;
+};
+export const javaHomeValueCheck: doctorCommon.JavaHomeValueCheck;
+export const androidSdkCheck: doctorCommon.AndroidSdkCheck;
+/** @satisfies {import('@appium/types').IDoctorCheck} */
+export class JavaVersionCheck {
+    MIN_JAVA_VERSION: number;
+    JAVA_VERSION_PATTERN: RegExp;
+    diagnose(): Promise<import("@appium/types").DoctorCheckResult>;
+    fix(): Promise<string>;
+    hasAutofix(): boolean;
+    isOptional(): boolean;
+}
+export const javaVersionCheck: JavaVersionCheck;
+import { doctor as doctorCommon } from 'appium-android-driver';
+//# sourceMappingURL=required-checks.d.ts.map

package/build/lib/doctor/required-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-checks.d.ts","sourceRoot":"","sources":["../../../lib/doctor/required-checks.js"],"names":[],"mappings":"AAKA;;;;;;;EAA8D;AAC9D;;;;;;;EAAwD;AACxD,iEAAkE;AAClE,2DAA4D;AAE5D,wDAAwD;AACxD;IACE,yBAAsB;IACtB,6BAA2D;IAE3D,+DAoBC;IAED,uBAGC;IAED,sBAEC;IAED,sBAEC;CACF;AACD,gDAAuD;uCAlDhB,uBAAuB"}

package/build/lib/doctor/required-checks.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.javaVersionCheck = exports.JavaVersionCheck = exports.androidSdkCheck = exports.javaHomeValueCheck = exports.javaHomeCheck = exports.androidHomeCheck = void 0;
+const appium_android_driver_1 = require("appium-android-driver");
+const teen_process_1 = require("teen_process");
+const support_1 = require("@appium/support");
+const node_path_1 = __importDefault(require("node:path"));
+exports.androidHomeCheck = appium_android_driver_1.doctor.androidHomeCheck;
+exports.javaHomeCheck = appium_android_driver_1.doctor.javaHomeCheck;
+exports.javaHomeValueCheck = appium_android_driver_1.doctor.javaHomeValueCheck;
+exports.androidSdkCheck = appium_android_driver_1.doctor.androidSdkCheck;
+/** @satisfies {import('@appium/types').IDoctorCheck} */
+class JavaVersionCheck {
+    constructor() {
+        this.MIN_JAVA_VERSION = 11;
+        this.JAVA_VERSION_PATTERN = /^\s*java\.version\s*=\s*([\d.]+)/m;
+    }
+    async diagnose() {
+        const javaHome = process.env.JAVA_HOME;
+        const fullJavaPath = node_path_1.default.join(javaHome ?? '', 'bin', `java${support_1.system.isWindows() ? '.exe' : ''}`);
+        if (!javaHome || !await support_1.fs.exists(fullJavaPath)) {
+            return support_1.doctor.nok(`Cannot retrieve Java version. Is Java installed and JAVA_HOME set to a proper path?`);
+        }
+        let javaVerMatch;
+        try {
+            const { stderr } = await (0, teen_process_1.exec)(fullJavaPath, ['-XshowSettings:properties', '-version']);
+            javaVerMatch = this.JAVA_VERSION_PATTERN.exec(stderr);
+        }
+        catch (e) {
+            return support_1.doctor.nok(`Cannot retrieve Java version: ${e.stderr || e.message}`);
+        }
+        if (!javaVerMatch) {
+            return support_1.doctor.nok(`The actual Java version cannot be retrieved`);
+        }
+        const majorVer = parseInt(javaVerMatch[1], 10);
+        return majorVer < this.MIN_JAVA_VERSION
+            ? support_1.doctor.nok(`The active Java version ${javaVerMatch[1]} is older than the required one`)
+            : support_1.doctor.ok(`The active Java version matches (${majorVer} >= ${this.MIN_JAVA_VERSION})`);
+    }
+    async fix() {
+        return `Upgrade to Java ${this.MIN_JAVA_VERSION}+ or update ` +
+            `the JAVA_HOME environment variable if it is already instsalled`;
+    }
+    hasAutofix() {
+        return false;
+    }
+    isOptional() {
+        return false;
+    }
+}
+exports.JavaVersionCheck = JavaVersionCheck;
+exports.javaVersionCheck = new JavaVersionCheck();
+//# sourceMappingURL=required-checks.js.map

package/build/lib/doctor/required-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-checks.js","sourceRoot":"","sources":["../../../lib/doctor/required-checks.js"],"names":[],"mappings":";;;;;;AAAA,iEAA+D;AAC/D,+CAAoC;AACpC,6CAAqD;AACrD,0DAA6B;AAEhB,QAAA,gBAAgB,GAAG,8BAAY,CAAC,gBAAgB,CAAC;AACjD,QAAA,aAAa,GAAG,8BAAY,CAAC,aAAa,CAAC;AAC3C,QAAA,kBAAkB,GAAG,8BAAY,CAAC,kBAAkB,CAAC;AACrD,QAAA,eAAe,GAAG,8BAAY,CAAC,eAAe,CAAC;AAE5D,wDAAwD;AACxD,MAAa,gBAAgB;IAA7B;QACE,qBAAgB,GAAG,EAAE,CAAC;QACtB,yBAAoB,GAAG,mCAAmC,CAAC;IAoC7D,CAAC;IAlCC,KAAK,CAAC,QAAQ;QACZ,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QACvC,MAAM,YAAY,GAAG,mBAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,gBAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjG,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,YAAE,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE;YAC/C,OAAO,gBAAM,CAAC,GAAG,CAAC,qFAAqF,CAAC,CAAC;SAC1G;QACD,IAAI,YAAY,CAAC;QACjB,IAAI;YACF,MAAM,EAAC,MAAM,EAAC,GAAG,MAAM,IAAA,mBAAI,EAAC,YAAY,EAAE,CAAC,2BAA2B,EAAE,UAAU,CAAC,CAAC,CAAC;YACrF,YAAY,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;SACvD;QAAC,OAAO,CAAC,EAAE;YACV,OAAO,gBAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;SAC7E;QACD,IAAI,CAAC,YAAY,EAAE;YACjB,OAAO,gBAAM,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAC;SAClE;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/C,OAAO,QAAQ,GAAG,IAAI,CAAC,gBAAgB;YACrC,CAAC,CAAC,gBAAM,CAAC,GAAG,CAAC,2BAA2B,YAAY,CAAC,CAAC,CAAC,iCAAiC,CAAC;YACzF,CAAC,CAAC,gBAAM,CAAC,EAAE,CAAC,oCAAoC,QAAQ,OAAO,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;IAC7F,CAAC;IAED,KAAK,CAAC,GAAG;QACP,OAAO,mBAAmB,IAAI,CAAC,gBAAgB,cAAc;YAC3D,gEAAgE,CAAC;IACrE,CAAC;IAED,UAAU;QACR,OAAO,KAAK,CAAC;IACf,CAAC;IAED,UAAU;QACR,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAtCD,4CAsCC;AACY,QAAA,gBAAgB,GAAG,IAAI,gBAAgB,EAAE,CAAC"}

package/lib/doctor/optional-checks.js

@@ -0,0 +1,4 @@
+import { doctor } from 'appium-android-driver';
+
+export const optionalBundletoolCheck = doctor.optionalBundletoolCheck;
+export const optionalFfmpegCheck = doctor.optionalFfmpegCheck;

package/lib/doctor/required-checks.js

@@ -0,0 +1,51 @@
+import { doctor as doctorCommon } from 'appium-android-driver';
+import { exec } from 'teen_process';
+import { fs, system, doctor } from '@appium/support';
+import path from 'node:path';
+
+export const androidHomeCheck = doctorCommon.androidHomeCheck;
+export const javaHomeCheck = doctorCommon.javaHomeCheck;
+export const javaHomeValueCheck = doctorCommon.javaHomeValueCheck;
+export const androidSdkCheck = doctorCommon.androidSdkCheck;
+
+/** @satisfies {import('@appium/types').IDoctorCheck} */
+export class JavaVersionCheck {
+  MIN_JAVA_VERSION = 11;
+  JAVA_VERSION_PATTERN = /^\s*java\.version\s*=\s*([\d.]+)/m;
+
+  async diagnose() {
+    const javaHome = process.env.JAVA_HOME;
+    const fullJavaPath = path.join(javaHome ?? '', 'bin', `java${system.isWindows() ? '.exe' : ''}`);
+    if (!javaHome || !await fs.exists(fullJavaPath)) {
+      return doctor.nok(`Cannot retrieve Java version. Is Java installed and JAVA_HOME set to a proper path?`);
+    }
+    let javaVerMatch;
+    try {
+      const {stderr} = await exec(fullJavaPath, ['-XshowSettings:properties', '-version']);
+      javaVerMatch = this.JAVA_VERSION_PATTERN.exec(stderr);
+    } catch (e) {
+      return doctor.nok(`Cannot retrieve Java version: ${e.stderr || e.message}`);
+    }
+    if (!javaVerMatch) {
+      return doctor.nok(`The actual Java version cannot be retrieved`);
+    }
+    const majorVer = parseInt(javaVerMatch[1], 10);
+    return majorVer < this.MIN_JAVA_VERSION
+      ? doctor.nok(`The active Java version ${javaVerMatch[1]} is older than the required one`)
+      : doctor.ok(`The active Java version matches (${majorVer} >= ${this.MIN_JAVA_VERSION})`);
+  }
+
+  async fix() {
+    return `Upgrade to Java ${this.MIN_JAVA_VERSION}+ or update ` +
+      `the JAVA_HOME environment variable if it is already instsalled`;
+  }
+
+  hasAutofix() {
+    return false;
+  }
+
+  isOptional() {
+    return false;
+  }
+}
+export const javaVersionCheck = new JavaVersionCheck();