chore: Improve type declarations (#925)

Author: mykola-mokhnach

lib/commands/general.js

@@ -122,22 +122,12 @@ commands.mobileBackgroundApp = async function mobileBackgroundApp (opts = {}) {
   return await this.background(seconds);
 };
 
-/**
- * @typedef {Object} DeviceInfo
- * @property {string} apiVersion
- * @property {string} platformVersion
- * @property {string} manufacturer
- * @property {string} model
- * @property {string} realDisplaySize
- * @property {string} displayDensity
- */
-
 /**
  * @this {import('../driver').EspressoDriver}
- * @returns {Promise<DeviceInfo>}
+ * @returns {Promise<import('../types').DeviceInfo>}
  */
 commands.mobileGetDeviceInfo = async function mobileGetDeviceInfo () {
-  return /** @type {DeviceInfo} */ (await this.espresso.jwproxy.command('/appium/device/info', 'GET'));
+  return /** @type {import('../types').DeviceInfo} */ (await this.espresso.jwproxy.command('/appium/device/info', 'GET'));
 };
 
 /**
@@ -473,11 +463,8 @@ commands.startActivity = async function startActivity (
 ) {
   // intentAction, intentCategory, intentFlags, optionalIntentArguments, dontStopAppOnReset
   // parameters are not supported by Espresso
-  /** @type {string} */
-  // @ts-ignore This should always be defined
-  const pkg = appPackage || this.caps.appPackage;
-  /** @type {string} */
-  const appWaitPkg = appWaitPackage || pkg;
+  const pkg = /** @type {string} */ (appPackage || this.caps.appPackage);
+  const appWaitPkg = /** @type {string} */ (appWaitPackage || pkg);
   const appAct = qualifyActivityName(appActivity, pkg);
   const appWaitAct = qualifyActivityName(appWaitActivity || appAct, appWaitPkg);
   this.log.debug(`Starting activity '${appActivity}' for package '${appPackage}'`);

lib/desired-caps.js lib/constraints.ts

@@ -1,6 +1,7 @@
-import { commonCapConstraints } from 'appium-android-driver';
+import {Constraints} from '@appium/types';
+import {commonCapConstraints} from 'appium-android-driver';
 
-const espressoCapConstraints = {
+export const ESPRESSO_CONSTRAINTS = {
   systemPort: {
     isNumber: true
   },
@@ -34,9 +35,7 @@ const espressoCapConstraints = {
   appLocale: {
     isObject: true,
   },
-};
-
-export const desiredCapConstraints = {
   ...commonCapConstraints,
-  ...espressoCapConstraints,
-};
+} as const satisfies Constraints;
+
+export type EspressoConstraints = typeof ESPRESSO_CONSTRAINTS;

lib/driver.js

@@ -13,7 +13,7 @@ import { DEFAULT_ADB_PORT } from 'appium-adb';
 import {
   androidHelpers, SETTINGS_HELPER_PKG_ID, AndroidDriver
 } from 'appium-android-driver';
-import { desiredCapConstraints } from './desired-caps';
+import { ESPRESSO_CONSTRAINTS } from './constraints';
 import { findAPortNotInUse } from 'portscanner';
 import { retryInterval } from 'asyncbox';
 import { qualifyActivityName, getPackageInfo } from './utils';
@@ -133,8 +133,21 @@ const APK_EXT = '.apk';
 const AAB_EXT = '.aab';
 const SUPPORTED_EXTENSIONS = [APK_EXT, AAB_EXT];
 
+/**
+ * @satisfies {import('@appium/types').ExternalDriver<
+ *   import('./constraints').EspressoConstraints,
+ *   string,
+ *   import('@appium/types').StringRecord
+ * >}
+ */
 class EspressoDriver extends AndroidDriver {
 
+  /** @type {import('./types').EspressoDriverOpts} */
+  opts;
+
+  /** @type {import('./types').EspressoDriverCaps} */
+  caps;
+
   /** @type {EspressoRunner} */
   espresso;
 
@@ -144,22 +157,21 @@ class EspressoDriver extends AndroidDriver {
     // `shell` overwrites adb.shell, so remove
     delete opts.shell;
 
-    // @ts-ignore Options are ok
-    super(opts, shouldValidateCaps);
+    super(/** @type {import('@appium/types').InitialOpts} */ (opts), shouldValidateCaps);
     this.locatorStrategies = [
       'id',
       'class name',
       'accessibility id',
     ];
-    this.desiredCapConstraints = desiredCapConstraints;
+    this.desiredCapConstraints = ESPRESSO_CONSTRAINTS;
     this.jwpProxyAvoid = NO_PROXY;
 
     this.settings = new DeviceSettings({}, this.onSettingsUpdate.bind(this));
 
-    this.chromedriver = null;
+    this.chromedriver = undefined;
   }
 
-  // @ts-ignore it's ok
+  // @ts-ignore it's ok to not care about exact args
   async createSession (...args) {
     try {
       // @ts-ignore it's ok to not care about exact args
@@ -200,24 +212,18 @@ class EspressoDriver extends AndroidDriver {
         }
       }
 
-      // @ts-ignore TODO: Make it typed
-      if (this.opts.reboot) {
-        this.setAvdFromCapabilities(caps);
-        this.addWipeDataToAvdArgs();
-      }
-
-      // @ts-ignore TODO: Make it typed
       this.opts.systemPort = this.opts.systemPort
         || await findAPortNotInUse(SYSTEM_PORT_RANGE[0], SYSTEM_PORT_RANGE[1]);
       this.opts.adbPort = this.opts.adbPort || DEFAULT_ADB_PORT;
       // get device udid for this session
       const {udid, emPort} = await helpers.getDeviceInfoFromCaps(this.opts);
       this.opts.udid = udid;
-      // @ts-ignore TODO: Make it typed
-      this.opts.emPort = emPort;
       // now that we know our java version and device info, we can create our
       // ADB instance
-      this.adb = await androidHelpers.createADB(this.opts);
+      this.adb = await androidHelpers.createADB({
+        ...this.opts,
+        emPort,
+      });
 
       if (this.opts.app) {
         // find and copy, or download and unzip an app url or path
@@ -295,7 +301,6 @@ class EspressoDriver extends AndroidDriver {
     const hasApkExt = (appPath) => _.endsWith(_.toLower(appPath), APK_EXT);
     const hasAabExt = (appPath) => _.endsWith(_.toLower(appPath), AAB_EXT);
     const extractUniversalApk = async (shouldExtract, appPath) =>
-      // @ts-ignore extractUniversalApk is there
       shouldExtract ? appPath : await this.adb.extractUniversalApk(appPath);
 
     let pathInCache = null;
@@ -353,32 +358,6 @@ class EspressoDriver extends AndroidDriver {
     return {};
   }
 
-  // TODO this method is duplicated from uiautomator2-driver; consolidate
-  setAvdFromCapabilities (caps) {
-    if (this.opts.avd) {
-      this.log.info('avd name defined, ignoring device name and platform version');
-    } else {
-      if (!caps.deviceName) {
-        this.log.errorAndThrow('avd or deviceName should be specified when reboot option is enables');
-      }
-      if (!caps.platformVersion) {
-        this.log.errorAndThrow('avd or platformVersion should be specified when reboot option is enabled');
-      }
-      let avdDevice = caps.deviceName.replace(/[^a-zA-Z0-9_.]/g, '-');
-      this.opts.avd = `${avdDevice}__${caps.platformVersion}`;
-    }
-  }
-
-  // TODO this method is duplicated from uiautomator2-driver; consolidate
-  addWipeDataToAvdArgs () {
-    if (!this.opts.avdArgs) {
-      this.opts.avdArgs = '-wipe-data';
-    // @ts-ignore This check will work
-    } else if (!_.includes(this.opts.avdArgs, '-wipe-data')) {
-      this.opts.avdArgs += ' -wipe-data';
-    }
-  }
-
   // TODO much of this logic is duplicated from uiautomator2
   async startEspressoSession () {
     const {manifestPayload} = await getPackageInfo();
@@ -396,13 +375,11 @@ class EspressoDriver extends AndroidDriver {
       // and get it onto our 'opts' object so we use it from now on
       Object.assign(this.opts, appInfo);
     } else {
-      // @ts-ignore This is ok
       appInfo = this.opts;
     }
 
     // start an avd, set the language/locale, pick an emulator, etc...
     // TODO with multiple devices we'll need to parameterize this
-    // @ts-ignore This is ok
     await helpers.initDevice(this.adb, this.opts);
 
     // https://github.com/appium/appium-espresso-driver/issues/72
@@ -411,16 +388,13 @@ class EspressoDriver extends AndroidDriver {
 
     // set actual device name, udid
     this.caps.deviceName = this.adb.curDeviceId;
-    // @ts-ignore This is ok
-    this.caps.deviceUDID = this.opts.udid;
+    this.caps.deviceUDID = /** @type {string} */ (this.opts.udid);
 
     // set up the modified espresso server etc
     this.initEspressoServer();
     // Further prepare the device by forwarding the espresso port
-    // @ts-ignore TODO: Make the module to .ts
     this.log.debug(`Forwarding Espresso Server port ${DEVICE_PORT} to ${this.opts.systemPort}`);
-    // @ts-ignore TODO: Make the module to .ts
-    await this.adb.forwardPort(this.opts.systemPort, DEVICE_PORT);
+    await this.adb.forwardPort(/** @type {number} */ (this.opts.systemPort), DEVICE_PORT);
 
     if (!this.opts.skipUnlock) {
       // unlock the device to prepare it for testing
@@ -517,64 +491,45 @@ class EspressoDriver extends AndroidDriver {
       realDisplaySize,
       displayDensity,
     } = await this.mobileGetDeviceInfo();
-    // @ts-ignore TODO: Make the module to .ts
     this.caps.deviceApiLevel = parseInt(apiVersion, 10);
     this.caps.platformVersion = platformVersion;
-    // @ts-ignore TODO: Make the module to .ts
     this.caps.deviceScreenSize = realDisplaySize;
-    // @ts-ignore TODO: Make the module to .ts
     this.caps.deviceScreenDensity = displayDensity;
-    // @ts-ignore TODO: Make the module to .ts
     this.caps.deviceModel = model;
-    // @ts-ignore TODO: Make the module to .ts
     this.caps.deviceManufacturer = manufacturer;
   }
 
   initEspressoServer () {
     // now that we have package and activity, we can create an instance of
     // espresso with the appropriate data
     this.espresso = new EspressoRunner(this.log, {
-      // @ts-ignore TODO: Make the module to .ts
+      // @ts-ignore TODO: Is .host a legacy property?
       host: this.opts.remoteAdbHost || this.opts.host || '127.0.0.1',
-      // @ts-ignore TODO: Make the module to .ts
       systemPort: this.opts.systemPort,
       devicePort: DEVICE_PORT,
       adb: this.adb,
       apk: this.opts.app,
       tmpDir: this.opts.tmpDir,
       appPackage: this.opts.appPackage,
       appActivity: this.opts.appActivity,
-      // @ts-ignore TODO: Make the module to .ts
       forceEspressoRebuild: !!this.opts.forceEspressoRebuild,
-      // @ts-ignore TODO: Make the module to .ts
       espressoBuildConfig: this.opts.espressoBuildConfig,
-      // @ts-ignore TODO: Make the module to .ts
       showGradleLog: !!this.opts.showGradleLog,
-      // @ts-ignore TODO: Make the module to .ts
       serverLaunchTimeout: this.opts.espressoServerLaunchTimeout,
       androidInstallTimeout: this.opts.androidInstallTimeout,
-      // @ts-ignore TODO: Make the module to .ts
       skipServerInstallation: this.opts.skipServerInstallation,
       useKeystore: this.opts.useKeystore,
       keystorePath: this.opts.keystorePath,
       keystorePassword: this.opts.keystorePassword,
       keyAlias: this.opts.keyAlias,
       keyPassword: this.opts.keyPassword,
-      // @ts-ignore TODO: Make the module to .ts
       disableSuppressAccessibilityService: this.opts.disableSuppressAccessibilityService,
     });
     this.proxyReqRes = this.espresso.proxyReqRes.bind(this.espresso);
     this.proxyCommand = this.espresso.proxyCommand.bind(this.espresso);
   }
 
-  // TODO this method is mostly duplicated from uiautomator2
   async initAUT () {
-    // set the localized strings for the current language from the apk
-    // TODO: incorporate changes from appium#5308 which fix a race cond-
-    // ition bug in old appium and need to be replicated here
-    // this.apkStrings[this.opts.language] = await androidHelpers.pushStrings(
-    //     this.opts.language, this.adb, this.opts);
-
     // Uninstall any uninstallOtherPackages which were specified in caps
     if (this.opts.uninstallOtherPackages) {
       await helpers.uninstallOtherPackages(
@@ -600,7 +555,6 @@ class EspressoDriver extends AndroidDriver {
     if (this.opts.app) {
       await helpers.installApk(this.adb, this.opts);
     }
-    // @ts-ignore TODO: Make the module to .ts
     if (this.opts.skipServerInstallation) {
       this.log.debug('skipServerInstallation capability is set. Not installig espresso-server ');
     } else {
@@ -665,22 +619,14 @@ class EspressoDriver extends AndroidDriver {
         await this.adb.uninstallApk(/** @type {string} */ (this.opts.appPackage));
       }
       await this.adb.stopLogcat();
-      // @ts-ignore TODO: Make the module to .ts
-      if (this.opts.reboot && this.opts.avd) {
-        let avdName = this.opts.avd.replace('@', '');
-        this.log.debug(`closing emulator '${avdName}'`);
-        await this.adb.killEmulator(avdName);
-      }
       if (await this.adb.getApiLevel() >= 28) { // Android P
         this.log.info('Restoring hidden api policy to the device default configuration');
         await this.adb.setDefaultHiddenApiPolicy(!!this.opts.ignoreHiddenApiPolicyError);
       }
     }
     await super.deleteSession();
-    // @ts-ignore TODO: Make the module to .ts
-    if (this.opts.systemPort !== undefined) {
+    if (this.opts.systemPort) {
       try {
-        // @ts-ignore TODO: Make the module to .ts
         await this.adb.removePortForward(this.opts.systemPort);
       } catch (error) {
         this.log.warn(`Unable to remove port forward '${error.message}'`);
@@ -723,8 +669,7 @@ class EspressoDriver extends AndroidDriver {
   }
 
   get appOnDevice () {
-    // @ts-ignore appPackage should always be defined
-    return !this.opts.app && this.helpers.isPackageOrBundle(this.opts.appPackage);
+    return !this.opts.app && this.helpers.isPackageOrBundle(/** @type {string} */ (this.opts.appPackage));
   }
 
   /**
@@ -733,7 +678,7 @@ class EspressoDriver extends AndroidDriver {
    * @returns {void}
    */
   suspendChromedriverProxy () {
-    this.chromedriver = null;
+    this.chromedriver = undefined;
     this.proxyReqRes = this.espresso.proxyReqRes.bind(this.espresso);
     this.proxyCommand = this.espresso.proxyCommand.bind(this.espresso);
     this.jwpProxyActive = true;

lib/types.ts

@@ -0,0 +1,27 @@
+import type {DriverCaps, DriverOpts, W3CDriverCaps} from '@appium/types';
+import type {EspressoConstraints} from './constraints';
+
+export type EspressoDriverOpts = DriverOpts<EspressoConstraints>;
+
+export type W3CEspressoDriverCaps = W3CDriverCaps<EspressoConstraints>;
+
+export interface DeviceInfo {
+  apiVersion: string;
+  platformVersion: string;
+  manufacturer: string;
+  model: string;
+  realDisplaySize: string;
+  displayDensity: number;
+}
+
+export interface DeviceInfoCaps {
+  deviceApiLevel: number;
+  platformVersion: string;
+  deviceScreenSize: string;
+  deviceModel: string;
+  deviceManufacturer: string;
+  deviceScreenDensity: number;
+  deviceUDID: string;
+}
+
+export type EspressoDriverCaps = DriverCaps<EspressoConstraints> & DeviceInfoCaps;