appium-chromedriver 5.2.16 → 5.3.0

package/lib/chromedriver.js

@@ -1,22 +1,24 @@
-// transpile:main
-
 import events from 'events';
-import { JWProxy, PROTOCOLS } from '@appium/base-driver';
+import {JWProxy, PROTOCOLS} from '@appium/base-driver';
 import cp from 'child_process';
-import { system, fs, logger, util } from '@appium/support';
-import { retryInterval, asyncmap } from 'asyncbox';
-import { SubProcess, exec } from 'teen_process';
+import {system, fs, logger, util} from '@appium/support';
+import {retryInterval, asyncmap} from 'asyncbox';
+import {SubProcess, exec} from 'teen_process';
 import B from 'bluebird';
 import {
-  getChromeVersion, getChromedriverDir, CHROMEDRIVER_CHROME_MAPPING,
-  getChromedriverBinaryPath, CD_CDN, generateLogPrefix
+  getChromeVersion,
+  getChromedriverDir,
+  CHROMEDRIVER_CHROME_MAPPING,
+  getChromedriverBinaryPath,
+  CD_CDN,
+  generateLogPrefix,
 } from './utils';
 import semver from 'semver';
 import _ from 'lodash';
 import path from 'path';
-import { compareVersions } from 'compare-versions';
+import {compareVersions} from 'compare-versions';
 import ChromedriverStorageClient from './storage-client';
-import { toW3cCapNames, getCapValue } from './protocol-helpers';
+import {toW3cCapNames, getCapValue} from './protocol-helpers';
 
 const NEW_CD_VERSION_FORMAT_MAJOR_VERSION = 73;
 const DEFAULT_HOST = '127.0.0.1';
@@ -24,16 +26,17 @@ const MIN_CD_VERSION_WITH_W3C_SUPPORT = 75;
 const DEFAULT_PORT = 9515;
 const CHROME_BUNDLE_ID = 'com.android.chrome';
 const WEBVIEW_SHELL_BUNDLE_ID = 'org.chromium.webview_shell';
-const WEBVIEW_BUNDLE_IDS = [
-  'com.google.android.webview',
-  'com.android.webview',
-];
+const WEBVIEW_BUNDLE_IDS = ['com.google.android.webview', 'com.android.webview'];
 const VERSION_PATTERN = /([\d.]+)/;
 
 const CD_VERSION_TIMEOUT = 5000;
 
 class Chromedriver extends events.EventEmitter {
-  constructor (args = {}) {
+  /**
+   *
+   * @param {import('./types').ChromedriverOpts} args
+   */
+  constructor(args = {}) {
     super();
 
     const {
@@ -75,28 +78,30 @@ class Chromedriver extends events.EventEmitter {
     this.logPath = logPath;
     this.disableBuildCheck = !!disableBuildCheck;
     this.storageClient = isAutodownloadEnabled
-      ? new ChromedriverStorageClient({ chromedriverDir: this.executableDir })
+      ? new ChromedriverStorageClient({chromedriverDir: this.executableDir})
       : null;
     this.details = details;
+    /** @type {any} */
     this.capabilities = {};
     this.desiredProtocol = PROTOCOLS.MJSONWP;
   }
 
-  get log () {
+  get log() {
     return this._log;
   }
 
-  async getDriversMapping () {
+  async getDriversMapping() {
     let mapping = _.cloneDeep(CHROMEDRIVER_CHROME_MAPPING);
     if (this.mappingPath) {
       this.log.debug(`Attempting to use Chromedriver->Chrome mapping from '${this.mappingPath}'`);
-      if (!await fs.exists(this.mappingPath)) {
+      if (!(await fs.exists(this.mappingPath))) {
         this.log.warn(`No file found at '${this.mappingPath}'`);
         this.log.info('Defaulting to the static Chromedriver->Chrome mapping');
       } else {
         try {
           mapping = JSON.parse(await fs.readFile(this.mappingPath, 'utf8'));
-        } catch (err) {
+        } catch (e) {
+          const err = /** @type {Error} */ (e);
           this.log.warn(`Error parsing mapping from '${this.mappingPath}': ${err.message}`);
           this.log.info('Defaulting to the static Chromedriver->Chrome mapping');
         }
@@ -117,7 +122,10 @@ class Chromedriver extends events.EventEmitter {
     return mapping;
   }
 
-  async getChromedrivers (mapping) {
+  /**
+   * @param {ChromedriverVersionMapping} mapping
+   */
+  async getChromedrivers(mapping) {
     // go through the versions available
     const executables = await fs.glob('*', {
       cwd: this.executableDir,
@@ -125,62 +133,78 @@ class Chromedriver extends events.EventEmitter {
       nodir: true,
       absolute: true,
     });
-    this.log.debug(`Found ${util.pluralize('executable', executables.length, true)} ` +
-      `in '${this.executableDir}'`);
-    const cds = (await asyncmap(executables, async (executable) => {
-      const logError = ({message, stdout = null, stderr = null}) => {
-        let errMsg = `Cannot retrieve version number from '${path.basename(executable)}' Chromedriver binary. ` +
-          `Make sure it returns a valid version string in response to '--version' command line argument. ${message}`;
-        if (stdout) {
-          errMsg += `\nStdout: ${stdout}`;
-        }
-        if (stderr) {
-          errMsg += `\nStderr: ${stderr}`;
-        }
-        this.log.warn(errMsg);
-        return null;
-      };
+    this.log.debug(
+      `Found ${util.pluralize('executable', executables.length, true)} ` +
+        `in '${this.executableDir}'`
+    );
+    const cds = (
+      await asyncmap(executables, async (executable) => {
+        /**
+         * @param {{message: string, stdout?: string, stderr?: string}} opts
+         */
+        const logError = ({message, stdout, stderr}) => {
+          let errMsg =
+            `Cannot retrieve version number from '${path.basename(
+              executable
+            )}' Chromedriver binary. ` +
+            `Make sure it returns a valid version string in response to '--version' command line argument. ${message}`;
+          if (stdout) {
+            errMsg += `\nStdout: ${stdout}`;
+          }
+          if (stderr) {
+            errMsg += `\nStderr: ${stderr}`;
+          }
+          this.log.warn(errMsg);
+          return null;
+        };
 
-      let stdout;
-      let stderr;
-      try {
-        ({stdout, stderr} = await exec(executable, ['--version'], {
-          timeout: CD_VERSION_TIMEOUT,
-        }));
-      } catch (err) {
-        if (!(err.message || '').includes('timed out') && !(err.stdout || '').includes('Starting ChromeDriver')) {
-          return logError(err);
-        }
+        let stdout;
+        let stderr;
+        try {
+          ({stdout, stderr} = await exec(executable, ['--version'], {
+            timeout: CD_VERSION_TIMEOUT,
+          }));
+        } catch (e) {
+          const err = /** @type {import('teen_process').ExecError} */ (e);
+          if (
+            !(err.message || '').includes('timed out') &&
+            !(err.stdout || '').includes('Starting ChromeDriver')
+          ) {
+            return logError(err);
+          }
 
-        // if this has timed out, it has actually started Chromedriver,
-        // in which case there will also be the version string in the output
-        stdout = err.stdout;
-      }
+          // if this has timed out, it has actually started Chromedriver,
+          // in which case there will also be the version string in the output
+          stdout = err.stdout;
+        }
 
-      const match = /ChromeDriver\s+\(?v?([\d.]+)\)?/i.exec(stdout); // https://regex101.com/r/zpj5wA/1
-      if (!match) {
-        return logError({message: 'Cannot parse the version string', stdout, stderr});
-      }
-      let version = match[1];
-      let minChromeVersion = mapping[version];
-      const coercedVersion = semver.coerce(version);
-      if (coercedVersion) {
-        // before 2019-03-06 versions were of the form major.minor
-        if (coercedVersion.major < NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
-          version = `${coercedVersion.major}.${coercedVersion.minor}`;
-          minChromeVersion = mapping[version];
+        const match = /ChromeDriver\s+\(?v?([\d.]+)\)?/i.exec(stdout); // https://regex101.com/r/zpj5wA/1
+        if (!match) {
+          return logError({message: 'Cannot parse the version string', stdout, stderr});
         }
-        if (!minChromeVersion && coercedVersion.major >= NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
-          // Assume the major Chrome version is the same as the corresponding driver major version
-          minChromeVersion = `${coercedVersion.major}`;
+        let version = match[1];
+        let minChromeVersion = mapping[version];
+        const coercedVersion = semver.coerce(version);
+        if (coercedVersion) {
+          // before 2019-03-06 versions were of the form major.minor
+          if (coercedVersion.major < NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
+            version = /** @type {keyof typeof mapping} */ (
+              `${coercedVersion.major}.${coercedVersion.minor}`
+            );
+            minChromeVersion = mapping[version];
+          }
+          if (!minChromeVersion && coercedVersion.major >= NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
+            // Assume the major Chrome version is the same as the corresponding driver major version
+            minChromeVersion = `${coercedVersion.major}`;
+          }
         }
-      }
-      return {
-        executable,
-        version,
-        minChromeVersion,
-      };
-    }))
+        return {
+          executable,
+          version,
+          minChromeVersion,
+        };
+      })
+    )
       .filter((cd) => !!cd)
       .sort((a, b) => compareVersions(b.version, a.version));
     if (_.isEmpty(cds)) {
@@ -189,19 +213,23 @@ class Chromedriver extends events.EventEmitter {
     }
     this.log.debug(`The following Chromedriver executables were found:`);
     for (const cd of cds) {
-      this.log.debug(`    '${cd.executable}' (version '${cd.version}', minimum Chrome version '${cd.minChromeVersion ? cd.minChromeVersion : 'Unknown'}')`);
+      this.log.debug(
+        `    '${cd.executable}' (version '${cd.version}', minimum Chrome version '${
+          cd.minChromeVersion ? cd.minChromeVersion : 'Unknown'
+        }')`
+      );
     }
     return cds;
   }
 
-  async getChromeVersion () {
+  async getChromeVersion() {
     // Try to retrieve the version from `details` property if it is set
     // The `info` item must contain the output of /json/version CDP command
     // where `Browser` field looks like `Chrome/72.0.3601.0``
     if (this.details?.info) {
       this.log.debug(`Browser version in the supplied details: ${this.details?.info?.Browser}`);
     }
-    const versionMatch = VERSION_PATTERN.exec(this.details?.info?.Browser);
+    const versionMatch = VERSION_PATTERN.exec(this.details?.info?.Browser ?? '');
     if (versionMatch) {
       const coercedVersion = semver.coerce(versionMatch[1]);
       if (coercedVersion) {
@@ -213,11 +241,13 @@ class Chromedriver extends events.EventEmitter {
 
     // in case of WebView Browser Tester, simply try to find the underlying webview
     if (this.bundleId === WEBVIEW_SHELL_BUNDLE_ID) {
-      for (const bundleId of WEBVIEW_BUNDLE_IDS) {
-        chromeVersion = await getChromeVersion(this.adb, bundleId);
-        if (chromeVersion) {
-          this.bundleId = bundleId;
-          return semver.coerce(chromeVersion);
+      if (this.adb) {
+        for (const bundleId of WEBVIEW_BUNDLE_IDS) {
+          chromeVersion = await getChromeVersion(this.adb, bundleId);
+          if (chromeVersion) {
+            this.bundleId = bundleId;
+            return semver.coerce(chromeVersion);
+          }
         }
       }
       return null;
@@ -226,8 +256,11 @@ class Chromedriver extends events.EventEmitter {
     // on Android 7-9 webviews are backed by the main Chrome, not the system webview
     if (this.adb) {
       const apiLevel = await this.adb.getApiLevel();
-      if (apiLevel >= 24 && apiLevel <= 28 &&
-          [WEBVIEW_SHELL_BUNDLE_ID, ...WEBVIEW_BUNDLE_IDS].includes(this.bundleId)) {
+      if (
+        apiLevel >= 24 &&
+        apiLevel <= 28 &&
+        [WEBVIEW_SHELL_BUNDLE_ID, ...WEBVIEW_BUNDLE_IDS].includes(this.bundleId ?? '')
+      ) {
         this.bundleId = CHROME_BUNDLE_ID;
       }
     }
@@ -239,16 +272,18 @@ class Chromedriver extends events.EventEmitter {
 
       // we have a webview of some sort, so try to find the bundle version
       for (const bundleId of WEBVIEW_BUNDLE_IDS) {
-        chromeVersion = await getChromeVersion(this.adb, bundleId);
-        if (chromeVersion) {
-          this.bundleId = bundleId;
-          break;
+        if (this.adb) {
+          chromeVersion = await getChromeVersion(this.adb, bundleId);
+          if (chromeVersion) {
+            this.bundleId = bundleId;
+            break;
+          }
         }
       }
     }
 
     // if we do not have a chrome version, it must not be a webview
-    if (!chromeVersion) {
+    if (!chromeVersion && this.adb) {
       chromeVersion = await getChromeVersion(this.adb, this.bundleId);
     }
 
@@ -256,15 +291,27 @@ class Chromedriver extends events.EventEmitter {
     return chromeVersion ? semver.coerce(chromeVersion) : null;
   }
 
-  async updateDriversMapping (newMapping) {
+  /**
+   *
+   * @param {ChromedriverVersionMapping} newMapping
+   * @returns {Promise<void>}
+   */
+  async updateDriversMapping(newMapping) {
     let shouldUpdateStaticMapping = true;
+    if (!this.mappingPath) {
+      this.log.warn('No mapping path provided');
+      return;
+    }
     if (await fs.exists(this.mappingPath)) {
       try {
         await fs.writeFile(this.mappingPath, JSON.stringify(newMapping, null, 2), 'utf8');
         shouldUpdateStaticMapping = false;
       } catch (e) {
-        this.log.warn(`Cannot store the updated chromedrivers mapping into '${this.mappingPath}'. ` +
-          `This may reduce the performance of further executions. Original error: ${e.message}`);
+        const err = /** @type {Error} */ (e);
+        this.log.warn(
+          `Cannot store the updated chromedrivers mapping into '${this.mappingPath}'. ` +
+            `This may reduce the performance of further executions. Original error: ${err.message}`
+        );
       }
     }
     if (shouldUpdateStaticMapping) {
@@ -272,7 +319,10 @@ class Chromedriver extends events.EventEmitter {
     }
   }
 
-  async getCompatibleChromedriver () {
+  /**
+   * @returns {Promise<string>}
+   */
+  async getCompatibleChromedriver() {
     if (!this.adb) {
       return await getChromedriverBinaryPath();
     }
@@ -283,11 +333,19 @@ class Chromedriver extends events.EventEmitter {
     }
 
     let didStorageSync = false;
+    /**
+     *
+     * @param {import('semver').SemVer} chromeVersion
+     */
     const syncChromedrivers = async (chromeVersion) => {
       didStorageSync = true;
+      if (!this.storageClient) {
+        return false;
+      }
       const retrievedMapping = await this.storageClient.retrieveMapping();
-      this.log.debug('Got chromedrivers mapping from the storage: ' +
-        JSON.stringify(retrievedMapping, null, 2));
+      this.log.debug(
+        'Got chromedrivers mapping from the storage: ' + JSON.stringify(retrievedMapping, null, 2)
+      );
       const driverKeys = await this.storageClient.syncDrivers({
         minBrowserVersion: chromeVersion.major,
       });
@@ -298,7 +356,7 @@ class Chromedriver extends events.EventEmitter {
         const {version, minBrowserVersion} = retrievedMapping[x];
         acc[version] = minBrowserVersion;
         return acc;
-      }, {});
+      }, /** @type {ChromedriverVersionMapping} */ ({}));
       Object.assign(mapping, synchronizedDriversMapping);
       await this.updateDriversMapping(mapping);
       return true;
@@ -307,6 +365,7 @@ class Chromedriver extends events.EventEmitter {
     do {
       const cds = await this.getChromedrivers(mapping);
 
+      /** @type {ChromedriverVersionMapping} */
       const missingVersions = {};
       for (const {version, minChromeVersion} of cds) {
         if (!minChromeVersion || mapping[version]) {
@@ -320,20 +379,30 @@ class Chromedriver extends events.EventEmitter {
         missingVersions[version] = minChromeVersion;
       }
       if (!_.isEmpty(missingVersions)) {
-        this.log.info(`Found ${util.pluralize('Chromedriver', _.size(missingVersions), true)}, ` +
-          `which ${_.size(missingVersions) === 1 ? 'is' : 'are'} missing in the list of known versions: ` +
-          JSON.stringify(missingVersions));
+        this.log.info(
+          `Found ${util.pluralize('Chromedriver', _.size(missingVersions), true)}, ` +
+            `which ${
+              _.size(missingVersions) === 1 ? 'is' : 'are'
+            } missing in the list of known versions: ` +
+            JSON.stringify(missingVersions)
+        );
         await this.updateDriversMapping(Object.assign(mapping, missingVersions));
       }
 
       if (this.disableBuildCheck) {
         if (_.isEmpty(cds)) {
-          this.log.errorAndThrow(`There must be at least one Chromedriver executable available for use if ` +
-            `'chromedriverDisableBuildCheck' capability is set to 'true'`);
+          this.log.errorAndThrow(
+            `There must be at least one Chromedriver executable available for use if ` +
+              `'chromedriverDisableBuildCheck' capability is set to 'true'`
+          );
         }
         const {version, executable} = cds[0];
-        this.log.warn(`Chrome build check disabled. Using most recent Chromedriver version (${version}, at '${executable}')`);
-        this.log.warn(`If this is wrong, set 'chromedriverDisableBuildCheck' capability to 'false'`);
+        this.log.warn(
+          `Chrome build check disabled. Using most recent Chromedriver version (${version}, at '${executable}')`
+        );
+        this.log.warn(
+          `If this is wrong, set 'chromedriverDisableBuildCheck' capability to 'false'`
+        );
         return executable;
       }
 
@@ -341,11 +410,15 @@ class Chromedriver extends events.EventEmitter {
       if (!chromeVersion) {
         // unable to get the chrome version
         if (_.isEmpty(cds)) {
-          this.log.errorAndThrow(`There must be at least one Chromedriver executable available for use if ` +
-            `the current Chrome version cannot be determined`);
+          this.log.errorAndThrow(
+            `There must be at least one Chromedriver executable available for use if ` +
+              `the current Chrome version cannot be determined`
+          );
         }
         const {version, executable} = cds[0];
-        this.log.warn(`Unable to discover Chrome version. Using Chromedriver ${version} at '${executable}'`);
+        this.log.warn(
+          `Unable to discover Chrome version. Using Chromedriver ${version} at '${executable}'`
+        );
         return executable;
       }
       this.log.debug(`Found Chrome bundle '${this.bundleId}' version '${chromeVersion}'`);
@@ -367,59 +440,82 @@ class Chromedriver extends events.EventEmitter {
               continue;
             }
           } catch (e) {
-            this.log.warn(`Cannot synchronize local chromedrivers with the remote storage at ${CD_CDN}: ` +
-              e.message);
-            this.log.debug(e.stack);
+            const err = /** @type {Error} */ (e);
+            this.log.warn(
+              `Cannot synchronize local chromedrivers with the remote storage at ${CD_CDN}: ` +
+                err.message
+            );
+            this.log.debug(err.stack);
           }
         }
         const autodownloadSuggestion =
           'You could also try to enable automated chromedrivers download as ' +
           'a possible workaround.';
-        throw new Error(`No Chromedriver found that can automate Chrome '${chromeVersion}'.` +
-          (this.storageClient ? '' : ` ${autodownloadSuggestion}`));
+        throw new Error(
+          `No Chromedriver found that can automate Chrome '${chromeVersion}'.` +
+            (this.storageClient ? '' : ` ${autodownloadSuggestion}`)
+        );
       }
 
       const binPath = matchingDrivers[0].executable;
-      this.log.debug(`Found ${util.pluralize('executable', matchingDrivers.length, true)} ` +
-        `capable of automating Chrome '${chromeVersion}'.\nChoosing the most recent, '${binPath}'.`);
-      this.log.debug('If a specific version is required, specify it with the `chromedriverExecutable`' +
-        'desired capability.');
+      this.log.debug(
+        `Found ${util.pluralize('executable', matchingDrivers.length, true)} ` +
+          `capable of automating Chrome '${chromeVersion}'.\nChoosing the most recent, '${binPath}'.`
+      );
+      this.log.debug(
+        'If a specific version is required, specify it with the `chromedriverExecutable`' +
+          'desired capability.'
+      );
       return binPath;
-    // eslint-disable-next-line no-constant-condition
+      // eslint-disable-next-line no-constant-condition
     } while (true);
   }
 
-  async initChromedriverPath () {
-    if (this.executableVerified) return; //eslint-disable-line curly
+  async initChromedriverPath() {
+    if (this.executableVerified && this.chromedriver) {
+      return /** @type {string} */ (this.chromedriver);
+    }
 
+    let chromedriver = this.chromedriver;
     // the executable might be set (if passed in)
     // or we might want to use the basic one installed with this driver
     // or we want to figure out the best one
-    if (!this.chromedriver) {
-      this.chromedriver = this.useSystemExecutable
+    if (!chromedriver) {
+      chromedriver = this.chromedriver = this.useSystemExecutable
         ? await getChromedriverBinaryPath()
         : await this.getCompatibleChromedriver();
     }
 
-    if (!await fs.exists(this.chromedriver)) {
-      throw new Error(`Trying to use a chromedriver binary at the path ` +
-                      `${this.chromedriver}, but it doesn't exist!`);
+    if (!(await fs.exists(chromedriver))) {
+      throw new Error(
+        `Trying to use a chromedriver binary at the path ` +
+          `${this.chromedriver}, but it doesn't exist!`
+      );
     }
     this.executableVerified = true;
     this.log.info(`Set chromedriver binary as: ${this.chromedriver}`);
+    return /** @type {string} */ (this.chromedriver);
   }
 
-  syncProtocol (cdVersion = null) {
+  /**
+   *
+   * @param {string} [cdVersion]
+   */
+  syncProtocol(cdVersion) {
     const coercedVersion = semver.coerce(cdVersion);
     if (!coercedVersion || coercedVersion.major < MIN_CD_VERSION_WITH_W3C_SUPPORT) {
-      this.log.debug(`Chromedriver v. ${cdVersion} does not fully support ${PROTOCOLS.W3C} protocol. ` +
-        `Defaulting to ${PROTOCOLS.MJSONWP}`);
+      this.log.debug(
+        `Chromedriver v. ${cdVersion} does not fully support ${PROTOCOLS.W3C} protocol. ` +
+          `Defaulting to ${PROTOCOLS.MJSONWP}`
+      );
       return;
     }
     const chromeOptions = getCapValue(this.capabilities, 'chromeOptions', {});
     if (chromeOptions.w3c === false) {
-      this.log.info(`Chromedriver v. ${cdVersion} supports ${PROTOCOLS.W3C} protocol, ` +
-        `but ${PROTOCOLS.MJSONWP} one has been explicitly requested`);
+      this.log.info(
+        `Chromedriver v. ${cdVersion} supports ${PROTOCOLS.W3C} protocol, ` +
+          `but ${PROTOCOLS.MJSONWP} one has been explicitly requested`
+      );
       return;
     }
     this.desiredProtocol = PROTOCOLS.W3C;
@@ -429,7 +525,12 @@ class Chromedriver extends events.EventEmitter {
     this.capabilities = toW3cCapNames(this.capabilities);
   }
 
-  async start (caps, emitStartingState = true) {
+  /**
+   *
+   * @param {object} caps
+   * @param {boolean} emitStartingState
+   */
+  async start(caps, emitStartingState = true) {
     this.capabilities = _.cloneDeep(caps);
 
     // set the logging preferences to ALL the console logs
@@ -458,16 +559,16 @@ class Chromedriver extends events.EventEmitter {
     args.push('--verbose');
     // what are the process stdout/stderr conditions wherein we know that
     // the process has started to our satisfaction?
-    const startDetector = (stdout) => stdout.startsWith('Starting ');
+    const startDetector = /** @param {string} stdout */ (stdout) => stdout.startsWith('Starting ');
 
     let processIsAlive = false;
     let webviewVersion;
     try {
-      await this.initChromedriverPath();
+      const chromedriverPath = await this.initChromedriverPath();
       await this.killAll();
 
       // set up our subprocess object
-      this.proc = new SubProcess(this.chromedriver, args);
+      this.proc = new SubProcess(chromedriverPath, args);
       processIsAlive = true;
 
       // handle log output
@@ -513,9 +614,11 @@ class Chromedriver extends events.EventEmitter {
       // handle out-of-bound exit by simply emitting a stopped state
       this.proc.on('exit', (code, signal) => {
         processIsAlive = false;
-        if (this.state !== Chromedriver.STATE_STOPPED &&
-            this.state !== Chromedriver.STATE_STOPPING &&
-            this.state !== Chromedriver.STATE_RESTARTING) {
+        if (
+          this.state !== Chromedriver.STATE_STOPPED &&
+          this.state !== Chromedriver.STATE_STOPPING &&
+          this.state !== Chromedriver.STATE_RESTARTING
+        ) {
           const msg = `Chromedriver exited unexpectedly with code ${code}, signal ${signal}`;
           this.log.error(msg);
           this.changeState(Chromedriver.STATE_STOPPED);
@@ -527,38 +630,41 @@ class Chromedriver extends events.EventEmitter {
       await this.waitForOnline();
       await this.startSession();
     } catch (e) {
-      this.log.debug(e);
-      this.emit(Chromedriver.EVENT_ERROR, e);
+      const err = /** @type {Error} */ (e);
+      this.log.debug(err);
+      this.emit(Chromedriver.EVENT_ERROR, err);
       // just because we had an error doesn't mean the chromedriver process
       // finished; we should clean up if necessary
       if (processIsAlive) {
-        await this.proc.stop();
+        await this.proc?.stop();
       }
 
       let message = '';
       // often the user's Chrome version is not supported by the version of Chromedriver
-      if (e.message.includes('Chrome version must be')) {
-        message += 'Unable to automate Chrome version because it is not supported by this version of Chromedriver.\n';
+      if (err.message.includes('Chrome version must be')) {
+        message +=
+          'Unable to automate Chrome version because it is not supported by this version of Chromedriver.\n';
         if (webviewVersion) {
           message += `Chrome version on the device: ${webviewVersion}\n`;
         }
-        const versionsSupportedByDriver = /Chrome version must be (.+)/.exec(e.message)?.[1] || '';
+        const versionsSupportedByDriver =
+          /Chrome version must be (.+)/.exec(err.message)?.[1] || '';
         if (versionsSupportedByDriver) {
           message += `Chromedriver supports Chrome version(s): ${versionsSupportedByDriver}\n`;
         }
         message += 'Check the driver tutorial for troubleshooting.\n';
       }
 
-      message += e.message;
+      message += err.message;
       this.log.errorAndThrow(message);
     }
   }
 
-  sessionId () {
+  sessionId() {
     return this.state === Chromedriver.STATE_ONLINE ? this.jwproxy.sessionId : null;
   }
 
-  async restart () {
+  async restart() {
     this.log.info('Restarting chromedriver');
     if (this.state !== Chromedriver.STATE_ONLINE) {
       throw new Error("Can't restart when we're not online");
@@ -568,7 +674,7 @@ class Chromedriver extends events.EventEmitter {
     await this.start(this.capabilities, false);
   }
 
-  async waitForOnline () {
+  async waitForOnline() {
     // we need to make sure that CD hasn't crashed
     let chromedriverStopped = false;
     await retryInterval(20, 200, async () => {
@@ -584,62 +690,89 @@ class Chromedriver extends events.EventEmitter {
     }
   }
 
-  async getStatus () {
+  async getStatus() {
     return await this.jwproxy.command('/status', 'GET');
   }
 
-  async startSession () {
-    const sessionCaps = this.desiredProtocol === PROTOCOLS.W3C
-      ? {capabilities: {alwaysMatch: this.capabilities}}
-      : {desiredCapabilities: this.capabilities};
-    this.log.info(`Starting ${this.desiredProtocol} Chromedriver session with capabilities: ` +
-      JSON.stringify(sessionCaps, null, 2));
+  async startSession() {
+    const sessionCaps =
+      this.desiredProtocol === PROTOCOLS.W3C
+        ? {capabilities: {alwaysMatch: this.capabilities}}
+        : {desiredCapabilities: this.capabilities};
+    this.log.info(
+      `Starting ${this.desiredProtocol} Chromedriver session with capabilities: ` +
+        JSON.stringify(sessionCaps, null, 2)
+    );
+    // jwproxy types have not been implemented yet
+    // @ts-expect-error
     await this.jwproxy.command('/session', 'POST', sessionCaps);
     this.log.prefix = generateLogPrefix(this, this.jwproxy.sessionId);
     this.changeState(Chromedriver.STATE_ONLINE);
   }
 
-  async stop (emitStates = true) {
+  async stop(emitStates = true) {
     if (emitStates) {
       this.changeState(Chromedriver.STATE_STOPPING);
     }
+    /**
+     *
+     * @param {() => Promise<any>|any} f
+     */
     const runSafeStep = async (f) => {
       try {
         return await f();
       } catch (e) {
-        this.log.warn(e.message);
-        this.log.debug(e.stack);
+        const err = /** @type {Error} */ (e);
+        this.log.warn(err.message);
+        this.log.debug(err.stack);
       }
     };
     await runSafeStep(() => this.jwproxy.command('', 'DELETE'));
-    await runSafeStep(() => this.proc.stop('SIGTERM', 20000));
+    await runSafeStep(() => this.proc?.stop('SIGTERM', 20000));
     this.log.prefix = generateLogPrefix(this);
     if (emitStates) {
       this.changeState(Chromedriver.STATE_STOPPED);
     }
   }
 
-  changeState (state) {
+  /**
+   *
+   * @param {string} state
+   */
+  changeState(state) {
     this.state = state;
     this.log.debug(`Changed state to '${state}'`);
     this.emit(Chromedriver.EVENT_CHANGED, {state});
   }
 
-  async sendCommand (url, method, body) {
+  /**
+   *
+   * @param {string} url
+   * @param {'POST'|'GET'|'DELETE'} method
+   * @param {any} body
+   * @returns
+   */
+  async sendCommand(url, method, body) {
     return await this.jwproxy.command(url, method, body);
   }
 
-  async proxyReq (req, res) {
+  /**
+   *
+   * @param {any} req
+   * @param {any} res
+   * @privateRemarks req / res probably from Express
+   */
+  async proxyReq(req, res) {
     return await this.jwproxy.proxyReqRes(req, res);
   }
 
-  async killAll () {
+  async killAll() {
     let cmd = system.isWindows()
       ? `wmic process where "commandline like '%chromedriver.exe%--port=${this.proxyPort}%'" delete`
       : `pkill -15 -f "${this.chromedriver}.*--port=${this.proxyPort}"`;
     this.log.debug(`Killing any old chromedrivers, running: ${cmd}`);
     try {
-      await (B.promisify(cp.exec))(cmd);
+      await B.promisify(cp.exec)(cmd);
       this.log.debug('Successfully cleaned up old chromedrivers');
     } catch (err) {
       this.log.warn('No old chromedrivers seem to exist');
@@ -667,13 +800,14 @@ class Chromedriver extends events.EventEmitter {
             await this.adb.removePortForward(params[1].replace(/[\D]*/, ''));
           }
         }
-      } catch (err) {
+      } catch (e) {
+        const err = /** @type {Error} */ (e);
         this.log.warn(`Unable to clean forwarded ports. Error: '${err.message}'. Continuing.`);
       }
     }
   }
 
-  async hasWorkingWebview () {
+  async hasWorkingWebview() {
     // sometimes chromedriver stops automating webviews. this method runs a
     // simple command to determine our state, and responds accordingly
     try {
@@ -693,5 +827,9 @@ Chromedriver.STATE_ONLINE = 'online';
 Chromedriver.STATE_STOPPING = 'stopping';
 Chromedriver.STATE_RESTARTING = 'restarting';
 
-export { Chromedriver };
+export {Chromedriver};
 export default Chromedriver;
+
+/**
+ * @typedef {import('./types').ChromedriverVersionMapping} ChromedriverVersionMapping
+ */