appium-chromedriver 5.2.16 → 5.3.0

package/lib/install.js

@@ -7,7 +7,10 @@ import {
 
 const DOWNLOAD_TIMEOUT_MS = 15 * 1000;
 const LATEST_VERSION = 'LATEST';
-
+/**
+ *
+ * @param {string} ver
+ */
 async function formatCdVersion (ver) {
   return ver === LATEST_VERSION
     ? (await retrieveData(`${CD_CDN}/LATEST_RELEASE`, {
@@ -17,6 +20,10 @@ async function formatCdVersion (ver) {
     : ver;
 }
 
+/**
+ *
+ * @param {string} platformName
+ */
 async function prepareChromedriverDir (platformName) {
   const chromedriverDir = getChromedriverDir(platformName);
   if (!await fs.exists(chromedriverDir)) {

package/lib/protocol-helpers.js

@@ -3,12 +3,23 @@ import { isStandardCap } from '@appium/base-driver';
 
 const W3C_PREFIX = 'goog:';
 
+/**
+ *
+ * @param {string} capName
+ */
 function toW3cCapName (capName) {
   return (_.isString(capName) && !capName.includes(':') && !isStandardCap(capName))
     ? `${W3C_PREFIX}${capName}`
     : capName;
 }
 
+/**
+ *
+ * @param {Record<string,any>} allCaps
+ * @param {string} rawCapName
+ * @param {any} defaultValue
+ * @returns
+ */
 function getCapValue (allCaps = {}, rawCapName, defaultValue) {
   for (const [capName, capValue] of _.toPairs(allCaps)) {
     if (toW3cCapName(capName) === toW3cCapName(rawCapName)) {
@@ -18,11 +29,16 @@ function getCapValue (allCaps = {}, rawCapName, defaultValue) {
   return defaultValue;
 }
 
+/**
+ *
+ * @param {any} originalCaps
+ * @returns {Record<string,any>}
+ */
 function toW3cCapNames (originalCaps = {}) {
   return _.reduce(originalCaps, (acc, value, key) => {
     acc[toW3cCapName(key)] = value;
     return acc;
-  }, {});
+  }, /** @type {Record<string,any>} */({}));
 }
 
 export { toW3cCapNames, getCapValue };

package/lib/storage-client.js

@@ -1,28 +1,45 @@
 import {
-  getChromedriverDir, CD_CDN, retrieveData, getOsInfo,
-  OS, X64, X86, APPLE_ARM_SUFFIXES,
+  getChromedriverDir,
+  CD_CDN,
+  retrieveData,
+  getOsInfo,
+  OS,
+  X64,
+  X86,
+  APPLE_ARM_SUFFIXES,
 } from './utils';
 import _ from 'lodash';
 import xpath from 'xpath';
-import { DOMParser } from '@xmldom/xmldom';
+import {DOMParser} from '@xmldom/xmldom';
 import B from 'bluebird';
 import path from 'path';
 import os from 'os';
-import { system, fs, logger, tempDir, zip, util, net } from '@appium/support';
-
+import {system, fs, logger, tempDir, zip, util, net} from '@appium/support';
 
 const TIMEOUT_MS = 15000;
 const MAX_PARALLEL_DOWNLOADS = 5;
 
 const log = logger.getLogger('ChromedriverStorageClient');
 
-
-async function isCrcOk (src, checksum) {
+/**
+ *
+ * @param {string} src
+ * @param {string} checksum
+ * @returns {Promise<boolean>}
+ */
+async function isCrcOk(src, checksum) {
   const md5 = await fs.hash(src, 'md5');
   return _.toLower(md5) === _.toLower(checksum);
 }
 
-function findChildNode (parent, childName = null, text = null) {
+/**
+ *
+ * @param {Node|Attr} parent
+ * @param {string?} childName
+ * @param {string?} text
+ * @returns
+ */
+function findChildNode(parent, childName = null, text = null) {
   if (!childName && !text) {
     return null;
   }
@@ -31,7 +48,7 @@ function findChildNode (parent, childName = null, text = null) {
   }
 
   for (let childNodeIdx = 0; childNodeIdx < parent.childNodes.length; childNodeIdx++) {
-    const childNode = parent.childNodes[childNodeIdx];
+    const childNode = /** @type {Element|Attr} */ (parent.childNodes[childNodeIdx]);
     if (childName && !text && childName === childNode.localName) {
       return childNode;
     }
@@ -51,29 +68,35 @@ function findChildNode (parent, childName = null, text = null) {
   return null;
 }
 
-function extractNodeText (node) {
-  return (!node || !node.firstChild || !util.hasValue(node.firstChild.nodeValue))
+/**
+ *
+ * @param {Node?} node
+ * @returns
+ */
+function extractNodeText(node) {
+  return !node || !node.firstChild || !util.hasValue(node.firstChild.nodeValue)
     ? null
     : node.firstChild.nodeValue;
 }
 
-
 class ChromedriverStorageClient {
-  constructor (args = {}) {
-    const {
-      chromedriverDir = getChromedriverDir(),
-      timeout = TIMEOUT_MS,
-    } = args;
+  /**
+   *
+   * @param {import('./types').ChromedriverStorageClientOpts} args
+   */
+  constructor(args = {}) {
+    const {chromedriverDir = getChromedriverDir(), timeout = TIMEOUT_MS} = args;
     this.chromedriverDir = chromedriverDir;
     this.timeout = timeout;
+    /** @type {ChromedriverDetailsMapping} */
     this.mapping = {};
   }
 
   /**
    * @typedef {Object} AdditionalDriverDetails
-   * @property {?string} version - Chromedriver version
+   * @property {string?} version - Chromedriver version
    * or `null` if it cannot be found
-   * @property {?string} minBrowserVersion - The minimum browser version
+   * @property {string?} minBrowserVersion - The minimum browser version
    * supported by chromedriver or `null` if it cannot be found
    */
 
@@ -84,7 +107,7 @@ class ChromedriverStorageClient {
    * @param {string} content - Release notes of the corresponding chromedriver
    * @returns {AdditionalDriverDetails}
    */
-  parseNotes (content) {
+  parseNotes(content) {
     const result = {};
     const versionMatch = /^\s*[-]+ChromeDriver[\D]+([\d.]+)/im.exec(content);
     if (versionMatch) {
@@ -101,21 +124,27 @@ class ChromedriverStorageClient {
    * Downloads chromedriver release notes and puts them
    * into the dictionary argument
    *
+   * The method call mutates by merging `AdditionalDriverDetails`
    * @param {string} driverKey - Driver version plus archive name
    * @param {string} notesUrl - The URL of chromedriver notes
-   * @param {Object} infoDict - The dictionary containing driver info.
-   * The method call mutates by merging `AdditionalDriverDetails`
+   * @param {ChromedriverDetails} infoDict - The dictionary containing driver info.
    * @throws {Error} if the release notes cannot be downloaded
    */
-  async retrieveAdditionalDriverInfo (driverKey, notesUrl, infoDict) {
-    const notes = await retrieveData(notesUrl, {
-      'user-agent': 'appium',
-      accept: '*/*',
-    }, { timeout: this.timeout });
-    const { minBrowserVersion } = this.parseNotes(notes);
+  async retrieveAdditionalDriverInfo(driverKey, notesUrl, infoDict) {
+    const notes = await retrieveData(
+      notesUrl,
+      {
+        'user-agent': 'appium',
+        accept: '*/*',
+      },
+      {timeout: this.timeout}
+    );
+    const {minBrowserVersion} = this.parseNotes(notes);
     if (!minBrowserVersion) {
-      log.debug(`The driver '${driverKey}' does not contain valid release notes at ${notesUrl}. ` +
-        `Skipping it`);
+      log.debug(
+        `The driver '${driverKey}' does not contain valid release notes at ${notesUrl}. ` +
+          `Skipping it`
+      );
       return;
     }
     infoDict.minBrowserVersion = minBrowserVersion;
@@ -125,14 +154,16 @@ class ChromedriverStorageClient {
    * Parses chromedriver storage XML and stores
    * the parsed results into `this.mapping`
    *
-   * @param {DOMDocument} doc - The DOM representation
+   * @param {Document} doc - The DOM representation
    * of the chromedriver storage XML
    * @param {boolean} shouldParseNotes [true] - If set to `true`
    * then additional drivers information is going to be parsed
    * and assigned to `this.mapping`
    */
-  async parseStorageXml (doc, shouldParseNotes = true) {
-    const driverNodes = xpath.select(`//*[local-name(.)='Contents']`, doc);
+  async parseStorageXml(doc, shouldParseNotes = true) {
+    const driverNodes = /** @type {Array<Node|Attr>} */ (
+      xpath.select(`//*[local-name(.)='Contents']`, doc)
+    );
     log.debug(`Parsed ${driverNodes.length} entries from storage XML`);
     if (_.isEmpty(driverNodes)) {
       return;
@@ -140,10 +171,11 @@ class ChromedriverStorageClient {
 
     const promises = [];
     for (const driverNode of driverNodes) {
-      const key = extractNodeText(findChildNode(driverNode, 'Key'));
-      if (!_.includes(key, '/chromedriver_')) {
+      const k = extractNodeText(findChildNode(driverNode, 'Key'));
+      if (!_.includes(k, '/chromedriver_')) {
         continue;
       }
+      const key = String(k);
 
       const etag = extractNodeText(findChildNode(driverNode, 'ETag'));
       if (!etag) {
@@ -151,16 +183,20 @@ class ChromedriverStorageClient {
         continue;
       }
 
+      /** @type {ChromedriverDetails} */
       const cdInfo = {
         url: `${CD_CDN}/${key}`,
         etag: _.trim(etag, '"'),
-        version: _.first(key.split('/')),
+        version: /** @type {string} */ (_.first(key.split('/'))),
+        minBrowserVersion: null,
       };
       this.mapping[key] = cdInfo;
 
       const notesPath = `${cdInfo.version}/notes.txt`;
-      const isNotesPresent = !!driverNodes
-        .reduce((acc, node) => acc || findChildNode(node, 'Key', notesPath), false);
+      const isNotesPresent = !!driverNodes.reduce(
+        (acc, node) => Boolean(acc || findChildNode(node, 'Key', notesPath)),
+        false
+      );
       if (!isNotesPresent) {
         cdInfo.minBrowserVersion = null;
         if (shouldParseNotes) {
@@ -180,34 +216,23 @@ class ChromedriverStorageClient {
     log.info(`The total count of entries in the mapping: ${_.size(this.mapping)}`);
   }
 
-  /**
-   * @typedef {Object} DriverDetails
-   * @property {string} url - The full url to the corresponding driver in
-   * the remote storage
-   * @property {string} etag - The CRC of the driver archive
-   * @property {string} version - Chromedriver version
-   */
-
-  /**
-   * @typedef {Object} ChromedriversMapping
-   * @property {DriverDetails} - The keys are unique driver identifiers
-   * (version/archive name). The corresponding values have `DriverDetails`
-   * containing chromedriver details
-   */
-
   /**
    * Retrieves chromedriver mapping from the storage
    *
    * @param {boolean} shouldParseNotes [true] - if set to `true`
    * then additional chromedrivers info is going to be retrieved and
    * parsed from release notes
-   * @returns {ChromedriversMapping}
+   * @returns {Promise<ChromedriverDetailsMapping>}
    */
-  async retrieveMapping (shouldParseNotes = true) {
-    const xml = await retrieveData(CD_CDN, {
-      'user-agent': 'appium',
-      accept: 'application/xml, */*',
-    }, { timeout: this.timeout });
+  async retrieveMapping(shouldParseNotes = true) {
+    const xml = await retrieveData(
+      CD_CDN,
+      {
+        'user-agent': 'appium',
+        accept: 'application/xml, */*',
+      },
+      {timeout: this.timeout}
+    );
     const doc = new DOMParser().parseFromString(xml);
     await this.parseStorageXml(doc, shouldParseNotes);
     return _.cloneDeep(this.mapping);
@@ -220,54 +245,50 @@ class ChromedriverStorageClient {
    * @param {string} src - The source archive path
    * @param {string} dst - The destination chromedriver path
    */
-  async unzipDriver (src, dst) {
+  async unzipDriver(src, dst) {
     const tmpRoot = await tempDir.openDir();
     try {
       await zip.extractAllTo(src, tmpRoot);
-      const chromedriverPath = await fs.walkDir(tmpRoot, true, (itemPath, isDirectory) =>
-        !isDirectory && _.toLower(path.parse(itemPath).name) === 'chromedriver');
+      const chromedriverPath = await fs.walkDir(
+        tmpRoot,
+        true,
+        (itemPath, isDirectory) =>
+          !isDirectory && _.toLower(path.parse(itemPath).name) === 'chromedriver'
+      );
       if (!chromedriverPath) {
-        throw new Error('The archive was unzipped properly, but we could not find any chromedriver executable');
+        throw new Error(
+          'The archive was unzipped properly, but we could not find any chromedriver executable'
+        );
       }
       log.debug(`Moving the extracted '${path.basename(chromedriverPath)}' to '${dst}'`);
       await fs.mv(chromedriverPath, dst, {
-        mkdirp: true
+        mkdirp: true,
       });
     } finally {
       await fs.rimraf(tmpRoot);
     }
   }
 
-  /**
-   * @typedef {Object} OSInfo
-   * @property {string} name - The name of the host OS
-   * Can be either `mac`, `windows` or `linux`
-   * @property {string} arch - The architecture of the host OS.
-   * Can be either `32` or `64`
-   */
-
   /**
    * Filters `this.mapping` to only select matching
    * chromedriver entries by operating system information
    * and/or additional synchronization options (if provided)
    *
-   * @param {?OSInfo} osInfo
-   * @param {?SyncOptions} opts
+   * @param {OSInfo} osInfo
+   * @param {SyncOptions} opts
    * @returns {Array<String>} The list of filtered chromedriver
    * entry names (version/archive name)
    */
-  selectMatchingDrivers (osInfo, opts = {}) {
-    const {
-      minBrowserVersion,
-      versions = [],
-    } = opts;
+  selectMatchingDrivers(osInfo, opts = {}) {
+    const {minBrowserVersion, versions = []} = opts;
     let driversToSync = _.keys(this.mapping);
 
     if (!_.isEmpty(versions)) {
       // Handle only selected versions if requested
       log.debug(`Selecting chromedrivers whose versions match to ${versions}`);
-      driversToSync = driversToSync
-        .filter((cdName) => versions.includes(`${this.mapping[cdName].version}`));
+      driversToSync = driversToSync.filter((cdName) =>
+        versions.includes(`${this.mapping[cdName].version}`)
+      );
 
       log.debug(`Got ${util.pluralize('item', driversToSync.length, true)}`);
       if (_.isEmpty(driversToSync)) {
@@ -275,29 +296,41 @@ class ChromedriverStorageClient {
       }
     }
 
-    if (!isNaN(minBrowserVersion)) {
+    if (_.isString(minBrowserVersion) && !Number.isNaN(minBrowserVersion)) {
       // Only select drivers that support the current browser whose major version number equals to `minBrowserVersion`
       const minBrowserVersionInt = parseInt(minBrowserVersion, 10);
-      log.debug(`Selecting chromedrivers whose minimum supported browser version matches to ${minBrowserVersionInt}`);
+      log.debug(
+        `Selecting chromedrivers whose minimum supported browser version matches to ${minBrowserVersionInt}`
+      );
       let closestMatchedVersionNumber = 0;
       // Select the newest available and compatible chromedriver
       for (const cdName of driversToSync) {
-        const currentMinBrowserVersion = parseInt(this.mapping[cdName].minBrowserVersion, 10);
-        if (!isNaN(currentMinBrowserVersion)
-            && currentMinBrowserVersion <= minBrowserVersionInt
-            && closestMatchedVersionNumber < currentMinBrowserVersion) {
+        const currentMinBrowserVersion = parseInt(
+          String(this.mapping[cdName].minBrowserVersion),
+          10
+        );
+        if (
+          !Number.isNaN(currentMinBrowserVersion) &&
+          currentMinBrowserVersion <= minBrowserVersionInt &&
+          closestMatchedVersionNumber < currentMinBrowserVersion
+        ) {
           closestMatchedVersionNumber = currentMinBrowserVersion;
         }
       }
-      driversToSync = driversToSync.filter((cdName) => `${this.mapping[cdName].minBrowserVersion}` ===
-        `${closestMatchedVersionNumber > 0 ? closestMatchedVersionNumber : minBrowserVersionInt}`);
+      driversToSync = driversToSync.filter(
+        (cdName) =>
+          `${this.mapping[cdName].minBrowserVersion}` ===
+          `${closestMatchedVersionNumber > 0 ? closestMatchedVersionNumber : minBrowserVersionInt}`
+      );
 
       log.debug(`Got ${util.pluralize('item', driversToSync.length, true)}`);
       if (_.isEmpty(driversToSync)) {
         return [];
       }
-      log.debug(`Will select candidate ${util.pluralize('driver', driversToSync.length)} ` +
-        `versioned as '${_.uniq(driversToSync.map((cdName) => this.mapping[cdName].version))}'`);
+      log.debug(
+        `Will select candidate ${util.pluralize('driver', driversToSync.length)} ` +
+          `versioned as '${_.uniq(driversToSync.map((cdName) => this.mapping[cdName].version))}'`
+      );
     }
 
     if (!_.isEmpty(osInfo)) {
@@ -338,27 +371,28 @@ class ChromedriverStorageClient {
    * or return a boolean result if the driver retrieval process fails
    * @throws {Error} if there was a failure while retrieving the driver
    * and `isStrict` is set to `true`
-   * @returns {boolean} if `true` then the chromedriver is successfully
+   * @returns {Promise<boolean>} if `true` then the chromedriver is successfully
    * downloaded and extracted.
    */
-  async retrieveDriver (index, driverKey, archivesRoot, isStrict = false) {
-    const { url, etag, version } = this.mapping[driverKey];
+  async retrieveDriver(index, driverKey, archivesRoot, isStrict = false) {
+    const {url, etag, version} = this.mapping[driverKey];
     const archivePath = path.resolve(archivesRoot, `${index}.zip`);
     log.debug(`Retrieving '${url}' to '${archivePath}'`);
     try {
       await net.downloadFile(url, archivePath, {
         isMetered: false,
-        timeout: TIMEOUT_MS
+        timeout: TIMEOUT_MS,
       });
     } catch (e) {
-      const msg = `Cannot download chromedriver archive. Original error: ${e.message}`;
+      const err = /** @type {Error} */ (e);
+      const msg = `Cannot download chromedriver archive. Original error: ${err.message}`;
       if (isStrict) {
         throw new Error(msg);
       }
       log.error(msg);
       return false;
     }
-    if (!await isCrcOk(archivePath, etag)) {
+    if (!(await isCrcOk(archivePath, etag))) {
       const msg = `The checksum for the downloaded chromedriver '${driverKey}' did not match`;
       if (isStrict) {
         throw new Error(msg);
@@ -366,46 +400,33 @@ class ChromedriverStorageClient {
       log.error(msg);
       return false;
     }
-    const fileName = `${path.parse(url).name}_v${version}` +
-      (system.isWindows() ? '.exe' : '');
+    const fileName = `${path.parse(url).name}_v${version}` + (system.isWindows() ? '.exe' : '');
     const targetPath = path.resolve(this.chromedriverDir, fileName);
     try {
       await this.unzipDriver(archivePath, targetPath);
       await fs.chmod(targetPath, 0o755);
       log.debug(`Permissions of the file '${targetPath}' have been changed to 755`);
     } catch (e) {
+      const err = /** @type {Error} */ (e);
       if (isStrict) {
-        throw e;
+        throw err;
       }
-      log.error(e.message);
+      log.error(err.message);
       return false;
     }
     return true;
   }
 
-  /**
-   * @typedef {Object} SyncOptions
-   * @property {Array<String>} versions - The list of chromedriver
-   * versions to sync. If empty (the default value) then all available
-   * chromedrivers are going to be downloaded and extracted
-   * @property {string|number} minBrowserVersion - The minumum supported
-   * Chrome version that downloaded chromedrivers should support. Can match
-   * multiple drivers.
-   * @property {?OSInfo} osInfo - System information used to filter out
-   * the list of the retrieved drivers. If not provided then the script
-   * will try to retrieve it.
-   */
-
   /**
    * Retrieves chromedrivers from the remote storage
    * to the local file system
    *
-   * @param {?SyncOptions} opts
+   * @param {SyncOptions} opts
    * @throws {Error} if there was a problem while retrieving
    * the drivers
-   * @returns {Array<String} The list of successfully synchronized driver keys
+   * @returns {Promise<string[]>} The list of successfully synchronized driver keys
    */
-  async syncDrivers (opts = {}) {
+  async syncDrivers(opts = {}) {
     if (_.isEmpty(this.mapping)) {
       await this.retrieveMapping(!!opts.minBrowserVersion);
     }
@@ -413,24 +434,31 @@ class ChromedriverStorageClient {
       throw new Error('Cannot retrieve chromedrivers mapping from Google storage');
     }
 
-    const driversToSync = this.selectMatchingDrivers(opts.osInfo ?? await getOsInfo(), opts);
+    const driversToSync = this.selectMatchingDrivers(opts.osInfo ?? (await getOsInfo()), opts);
     if (_.isEmpty(driversToSync)) {
       log.debug(`There are no drivers to sync. Exiting`);
       return [];
     }
-    log.debug(`Got ${util.pluralize('driver', driversToSync.length, true)} to sync: ` +
-      JSON.stringify(driversToSync, null, 2));
-
+    log.debug(
+      `Got ${util.pluralize('driver', driversToSync.length, true)} to sync: ` +
+        JSON.stringify(driversToSync, null, 2)
+    );
+
+    /**
+     * @type {string[]}
+     */
     const synchronizedDrivers = [];
     const promises = [];
     const archivesRoot = await tempDir.openDir();
     try {
       for (const [idx, driverKey] of driversToSync.entries()) {
-        promises.push((async () => {
-          if (await this.retrieveDriver(idx, driverKey, archivesRoot, !_.isEmpty(opts))) {
-            synchronizedDrivers.push(driverKey);
-          }
-        })());
+        promises.push(
+          (async () => {
+            if (await this.retrieveDriver(idx, driverKey, archivesRoot, !_.isEmpty(opts))) {
+              synchronizedDrivers.push(driverKey);
+            }
+          })()
+        );
 
         if (promises.length % MAX_PARALLEL_DOWNLOADS === 0) {
           await B.all(promises);
@@ -441,8 +469,10 @@ class ChromedriverStorageClient {
       await fs.rimraf(archivesRoot);
     }
     if (!_.isEmpty(synchronizedDrivers)) {
-      log.info(`Successfully synchronized ` +
-        `${util.pluralize('chromedriver', synchronizedDrivers.length, true)}`);
+      log.info(
+        `Successfully synchronized ` +
+          `${util.pluralize('chromedriver', synchronizedDrivers.length, true)}`
+      );
     } else {
       log.info(`No chromedrivers were synchronized`);
     }
@@ -450,5 +480,11 @@ class ChromedriverStorageClient {
   }
 }
 
-
 export default ChromedriverStorageClient;
+
+/**
+ * @typedef {import('./types').SyncOptions} SyncOptions
+ * @typedef {import('./types').OSInfo} OSInfo
+ * @typedef {import('./types').ChromedriverDetails} ChromedriverDetails
+ * @typedef {import('./types').ChromedriverDetailsMapping} ChromedriverDetailsMapping
+ */