appium-mac2-driver 4.5.0 → 4.6.0

package/node_modules/appium-chromedriver/lib/commands/version.ts

@@ -0,0 +1,108 @@
+import * as semver from 'semver';
+
+import {getChromeVersion} from '../utils.js';
+import {getCapValue} from './session.js';
+import type {ChromedriverCommandContext} from './types.js';
+
+const CHROME_BUNDLE_ID = 'com.android.chrome';
+const CHROME_BROWSER_BUNDLE_IDS = [CHROME_BUNDLE_ID, 'com.chrome.beta', 'com.chrome.dev', 'com.chrome.canary'] as const;
+const WEBVIEW_SHELL_BUNDLE_ID = 'org.chromium.webview_shell';
+const WEBVIEW_BUNDLE_IDS = ['com.google.android.webview', 'com.android.webview'] as const;
+const VERSION_PATTERN = /([\d.]+)/;
+
+/**
+ * Detects Chrome/WebView version to drive Chromedriver compatibility matching.
+ */
+export async function getChromeVersionForAutodetection(
+  this: ChromedriverCommandContext,
+): Promise<semver.SemVer | null> {
+  // Prefer already-collected CDP details when available.
+  const fromDetails = tryCoerceVersionFromCdpDetails(this);
+  if (fromDetails) {
+    return fromDetails;
+  }
+
+  // A Chrome browser session names its package, whose version may differ from the system WebView's.
+  if (!this.bundleId) {
+    const androidPackage = getCapValue(this.capabilities, 'chromeOptions')?.androidPackage;
+    if (CHROME_BROWSER_BUNDLE_IDS.includes(androidPackage)) {
+      this.bundleId = androidPackage;
+    }
+  }
+
+  // In WebView shell mode, probe known system webview packages first.
+  if (this.bundleId === WEBVIEW_SHELL_BUNDLE_ID) {
+    return await resolveChromeVersionForWebviewShell(this);
+  }
+
+  // Android 7-9 webviews are backed by main Chrome package.
+  await remapLegacyWebviewBundleId(this);
+
+  // Default to generic Chrome and fall back to known webview providers.
+  let chromeVersion: string | null = await resolveChromeVersionByProbingWebviews(this);
+
+  // If no webview package matched, check the selected/default bundle id directly.
+  if (!chromeVersion && this.adb) {
+    const bundleId = this.bundleId ?? CHROME_BUNDLE_ID;
+    chromeVersion = (await getChromeVersion(this.adb, bundleId)) ?? null;
+  }
+  return chromeVersion ? semver.coerce(chromeVersion) : null;
+}
+
+function tryCoerceVersionFromCdpDetails(ctx: ChromedriverCommandContext): semver.SemVer | null {
+  if (ctx.details?.info) {
+    ctx.log.debug(`Browser version in the supplied details: ${ctx.details?.info?.Browser}`);
+  }
+  const versionMatch = VERSION_PATTERN.exec(ctx.details?.info?.Browser ?? '');
+  if (!versionMatch) {
+    return null;
+  }
+  return semver.coerce(versionMatch[1]);
+}
+
+async function resolveChromeVersionForWebviewShell(ctx: ChromedriverCommandContext): Promise<semver.SemVer | null> {
+  if (!ctx.adb) {
+    return null;
+  }
+  for (const bundleId of WEBVIEW_BUNDLE_IDS) {
+    const chromeVersion = await getChromeVersion(ctx.adb, bundleId);
+    if (chromeVersion) {
+      ctx.bundleId = bundleId;
+      return semver.coerce(chromeVersion);
+    }
+  }
+  return null;
+}
+
+async function remapLegacyWebviewBundleId(ctx: ChromedriverCommandContext): Promise<void> {
+  if (!ctx.adb) {
+    return;
+  }
+  const apiLevel = await ctx.adb.getApiLevel();
+  const isLegacyWebviewBundle = [WEBVIEW_SHELL_BUNDLE_ID, ...WEBVIEW_BUNDLE_IDS].includes(ctx.bundleId ?? '');
+  if (apiLevel >= 24 && apiLevel <= 28 && isLegacyWebviewBundle) {
+    ctx.bundleId = CHROME_BUNDLE_ID;
+  }
+}
+
+/**
+ * When no bundle id is set, default to Chrome and probe known WebView providers.
+ * Returns a version string if a WebView package reports one; otherwise leaves bundleId as Chrome.
+ */
+async function resolveChromeVersionByProbingWebviews(ctx: ChromedriverCommandContext): Promise<string | null> {
+  if (ctx.bundleId) {
+    return null;
+  }
+  ctx.bundleId = CHROME_BUNDLE_ID;
+  if (!ctx.adb) {
+    return null;
+  }
+  for (const bundleId of WEBVIEW_BUNDLE_IDS) {
+    const chromeVersion = await getChromeVersion(ctx.adb, bundleId);
+    if (chromeVersion) {
+      ctx.bundleId = bundleId;
+      return chromeVersion;
+    }
+  }
+  return null;
+}

package/node_modules/appium-chromedriver/lib/constants.ts

@@ -0,0 +1,35 @@
+export const STORAGE_REQ_TIMEOUT_MS = 15000;
+export const GOOGLEAPIS_CDN =
+  process.env.npm_config_chromedriver_cdnurl ||
+  process.env.CHROMEDRIVER_CDNURL ||
+  'https://chromedriver.storage.googleapis.com';
+export const USER_AGENT = 'appium';
+export const CHROMELABS_URL =
+  process.env.npm_config_chromelabs_url || process.env.CHROMELABS_URL || 'https://googlechromelabs.github.io';
+export const OS = {
+  LINUX: 'linux',
+  WINDOWS: 'win',
+  MAC: 'mac',
+} as const;
+export const ARCH = {
+  X64: '64',
+  X86: '32',
+} as const;
+export const CPU = {
+  INTEL: 'intel',
+  ARM: 'arm',
+} as const;
+export const APPLE_ARM_SUFFIXES = ['64_m1', '_arm64'] as const;
+
+export const CHROMEDRIVER_EVENTS = {
+  ERROR: 'chromedriver_error',
+  CHANGED: 'stateChanged',
+} as const;
+
+export const CHROMEDRIVER_STATES = {
+  STOPPED: 'stopped',
+  STARTING: 'starting',
+  ONLINE: 'online',
+  STOPPING: 'stopping',
+  RESTARTING: 'restarting',
+} as const;

package/node_modules/appium-chromedriver/lib/index.ts

@@ -0,0 +1,5 @@
+import {Chromedriver} from './chromedriver.js';
+export {ChromedriverStorageClient} from './storage-client/storage-client.js';
+export default Chromedriver;
+export {Chromedriver};
+export type * from './types.js';

package/node_modules/appium-chromedriver/lib/storage-client/chromelabs.ts

@@ -0,0 +1,167 @@
+import path from 'node:path';
+
+import {logger} from '@appium/support';
+import * as semver from 'semver';
+
+import {ARCH, CPU} from '../constants.js';
+import type {ChromedriverDetailsMapping} from '../types.js';
+
+interface VersionEntry {
+  version: string;
+  revision?: string;
+  downloads?: {
+    chromedriver?: Array<{
+      platform: string;
+      url: string;
+    }>;
+  };
+}
+
+interface KnownGoodVersionsJson {
+  timestamp?: string;
+  versions?: VersionEntry[];
+}
+
+interface LatestKnownGoodVersionsJson {
+  timestamp?: string;
+  channels?: {
+    Stable?: {
+      channel?: string;
+      version?: string;
+      revision?: string;
+    };
+  };
+}
+
+const log = logger.getLogger('ChromedriverChromelabsStorageClient');
+
+/**
+ * Parses the output of the JSON API that retrieves Chromedriver versions
+ *
+ * See https://github.com/GoogleChromeLabs/chrome-for-testing#json-api-endpoints for more details.
+ *
+ * @param jsonStr - The JSON string from the known-good-versions-with-downloads API
+ * @returns A mapping of chromedriver entry keys to their details
+ * @throws {Error} if the JSON cannot be parsed or has an unsupported format
+ */
+export function parseKnownGoodVersionsWithDownloadsJson(jsonStr: string): ChromedriverDetailsMapping {
+  let json: KnownGoodVersionsJson;
+  try {
+    json = JSON.parse(jsonStr);
+  } catch (e) {
+    throw new Error(`Storage JSON cannot be parsed. Original error: ${e instanceof Error ? e.message : String(e)}`, {
+      cause: e,
+    });
+  }
+  /**
+   * Example output:
+   * {
+   * "timestamp":"2023-07-28T13:09:17.042Z",
+   * "versions":[
+   *    {
+   *       "version":"113.0.5672.0",
+   *       "revision":"1121455",
+   *       "downloads":{
+   *          "chromedriver":[
+   *             {
+   *                "platform":"linux64",
+   *                "url":"https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/113.0.5672.0/linux64/chrome-linux64.zip"
+   *             },
+   *             {
+   *                "platform":"mac-arm64",
+   *                "url":"https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/113.0.5672.0/mac-arm64/chrome-mac-arm64.zip"
+   *             },
+   *             {
+   *                "platform":"mac-x64",
+   *                "url":"https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/113.0.5672.0/mac-x64/chrome-mac-x64.zip"
+   *             },
+   *             {
+   *                "platform":"win32",
+   *                "url":"https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/113.0.5672.0/win32/chrome-win32.zip"
+   *             },
+   *             {
+   *                "platform":"win64",
+   *                "url":"https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/113.0.5672.0/win64/chrome-win64.zip"
+   *             }
+   *          ]
+   *       }
+   *    },
+   *    {
+   *       "version":"113.0.5672.35",
+   *       ...
+   */
+  const mapping: ChromedriverDetailsMapping = {};
+  if (!Array.isArray(json?.versions)) {
+    log.debug(jsonStr);
+    throw new Error('The format of the storage JSON is not supported');
+  }
+  for (const {version, downloads} of json.versions) {
+    if (!Array.isArray(downloads?.chromedriver)) {
+      continue;
+    }
+    const versionObj = semver.parse(version, {loose: true});
+    if (!versionObj) {
+      continue;
+    }
+    for (const downloadEntry of downloads.chromedriver) {
+      if (!downloadEntry?.url || !downloadEntry?.platform) {
+        continue;
+      }
+      const osNameMatch = /^[a-z]+/i.exec(downloadEntry.platform);
+      if (!osNameMatch) {
+        log.debug(`The entry '${downloadEntry.url}' does not contain valid platform name. Skipping it`);
+        continue;
+      }
+      const key =
+        `${path.basename(path.dirname(path.dirname(downloadEntry.url)))}/` + `${path.basename(downloadEntry.url)}`;
+      mapping[key] = {
+        url: downloadEntry.url,
+        etag: null,
+        version,
+        minBrowserVersion: `${versionObj.major}`,
+        os: {
+          name: osNameMatch[0],
+          arch: downloadEntry.platform.includes(ARCH.X64) ? ARCH.X64 : ARCH.X86,
+          cpu: downloadEntry.platform.includes(CPU.ARM) ? CPU.ARM : CPU.INTEL,
+        },
+      };
+    }
+  }
+  log.info(`The total count of entries in the mapping: ${Object.keys(mapping).length}`);
+  return mapping;
+}
+
+/**
+ * Parses the output of the JSON API that retrieves the most recent stable Chromedriver version
+ *
+ * See https://github.com/GoogleChromeLabs/chrome-for-testing#json-api-endpoints for more details.
+ *
+ * @param jsonStr - The JSON string from the last-known-good-versions API
+ * @returns The most recent available chromedriver version string
+ * @throws {Error} if the JSON cannot be parsed or has an unsupported format
+ */
+export function parseLatestKnownGoodVersionsJson(jsonStr: string): string {
+  let json: LatestKnownGoodVersionsJson;
+  try {
+    json = JSON.parse(jsonStr);
+  } catch (e) {
+    throw new Error(`Storage JSON cannot be parsed. Original error: ${e instanceof Error ? e.message : String(e)}`, {
+      cause: e,
+    });
+  }
+  /**
+   * Example output:
+   * "timestamp":"2023-07-28T13:09:17.036Z",
+   * "channels":{
+   *    "Stable":{
+   *       "channel":"Stable",
+   *       "version":"115.0.5790.102",
+   *       "revision":"1148114"
+   * ...
+   */
+  if (!json?.channels?.Stable?.version) {
+    log.debug(jsonStr);
+    throw new Error('The format of the storage JSON is not supported');
+  }
+  return json.channels.Stable.version;
+}

package/node_modules/appium-chromedriver/lib/storage-client/googleapis.ts

@@ -0,0 +1,199 @@
+import path from 'node:path';
+
+import {util, logger} from '@appium/support';
+import {DOMParser} from '@xmldom/xmldom';
+import {asyncmap} from 'asyncbox';
+import {select as xpathSelect} from 'xpath';
+
+import {STORAGE_REQ_TIMEOUT_MS, GOOGLEAPIS_CDN, ARCH, CPU, APPLE_ARM_SUFFIXES} from '../constants.js';
+import type {AdditionalDriverDetails, ChromedriverDetails, ChromedriverDetailsMapping} from '../types.js';
+import {retrieveData} from '../utils.js';
+
+const log = logger.getLogger('ChromedriverGoogleapisStorageClient');
+const MAX_PARALLEL_DOWNLOADS = 5;
+
+/**
+ * Finds a child node in an XML node by name and/or text content
+ *
+ * @param parent - The parent XML node to search in
+ * @param childName - Optional child node name to match
+ * @param text - Optional text content to match
+ * @returns The matching child node or null if not found
+ */
+export function findChildNode(
+  parent: Node | Attr,
+  childName: string | null = null,
+  text: string | null = null,
+): Node | Attr | null {
+  if (!childName && !text) {
+    return null;
+  }
+  if (!parent.hasChildNodes()) {
+    return null;
+  }
+
+  for (let childNodeIdx = 0; childNodeIdx < parent.childNodes.length; childNodeIdx++) {
+    const childNode = parent.childNodes[childNodeIdx] as Element | Attr;
+    if (childName && !text && childName === childNode.localName) {
+      return childNode;
+    }
+    if (text) {
+      const childText = extractNodeText(childNode);
+      if (!childText) {
+        continue;
+      }
+      if (childName && childName === childNode.localName && text === childText) {
+        return childNode;
+      }
+      if (!childName && text === childText) {
+        return childNode;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Gets additional chromedriver details from chromedriver
+ * release notes
+ *
+ * @param content - Release notes of the corresponding chromedriver
+ * @returns AdditionalDriverDetails
+ */
+export function parseNotes(content: string): AdditionalDriverDetails {
+  const result: AdditionalDriverDetails = {};
+  const versionMatch = /^\s*[-]+ChromeDriver[\D]+([\d.]+)/im.exec(content);
+  if (versionMatch) {
+    result.version = versionMatch[1];
+  }
+  const minBrowserVersionMatch = /^\s*Supports Chrome[\D]+(\d+)/im.exec(content);
+  if (minBrowserVersionMatch) {
+    result.minBrowserVersion = minBrowserVersionMatch[1];
+  }
+  return result;
+}
+
+/**
+ * Parses chromedriver storage XML and returns
+ * the parsed results
+ *
+ * @param xml - The chromedriver storage XML
+ * @param shouldParseNotes [true] - If set to `true`
+ * then additional drivers information is going to be parsed
+ * and assigned to `this.mapping`
+ * @returns Promise<ChromedriverDetailsMapping>
+ */
+export async function parseGoogleapiStorageXml(
+  xml: string,
+  shouldParseNotes = true,
+): Promise<ChromedriverDetailsMapping> {
+  const doc = new DOMParser().parseFromString(xml, 'text/xml');
+  const driverNodes = xpathSelect(`//*[local-name(.)='Contents']`, doc as unknown as Node) as Array<Node | Attr>;
+  log.debug(`Parsed ${driverNodes.length} entries from storage XML`);
+  if (driverNodes.length === 0) {
+    throw new Error('Cannot retrieve any valid Chromedriver entries from the storage config');
+  }
+
+  const infoParsers: Array<() => Promise<void>> = [];
+  const mapping: ChromedriverDetailsMapping = {};
+  for (const driverNode of driverNodes) {
+    const k = extractNodeText(findChildNode(driverNode, 'Key'));
+    if (!String(k).includes('/chromedriver_')) {
+      continue;
+    }
+    const key = String(k);
+    const versionSegment = key.split('/')[0];
+    if (!versionSegment) {
+      continue;
+    }
+
+    const etag = extractNodeText(findChildNode(driverNode, 'ETag'));
+    if (!etag) {
+      log.debug(`The entry '${key}' does not contain the checksum. Skipping it`);
+      continue;
+    }
+
+    const filename = path.basename(key);
+    const osNameMatch = /_([a-z]+)/i.exec(filename);
+    if (!osNameMatch) {
+      log.debug(`The entry '${key}' does not contain valid OS name. Skipping it`);
+      continue;
+    }
+
+    const cdInfo: ChromedriverDetails = {
+      url: `${GOOGLEAPIS_CDN}/${key}`,
+      etag: etag.replace(/^"+|"+$/g, ''),
+      version: versionSegment,
+      minBrowserVersion: null,
+      os: {
+        name: osNameMatch[1],
+        arch: filename.includes(ARCH.X64) ? ARCH.X64 : ARCH.X86,
+        cpu: APPLE_ARM_SUFFIXES.some((suffix) => filename.includes(suffix)) ? CPU.ARM : CPU.INTEL,
+      },
+    };
+    mapping[key] = cdInfo;
+
+    const notesPath = `${cdInfo.version}/notes.txt`;
+    const isNotesPresent = !!driverNodes.reduce(
+      (acc, node) => Boolean(acc || findChildNode(node, 'Key', notesPath)),
+      false,
+    );
+    if (!isNotesPresent) {
+      cdInfo.minBrowserVersion = null;
+      if (shouldParseNotes) {
+        log.info(`The entry '${key}' does not contain any notes. Skipping it`);
+      }
+      continue;
+    } else if (!shouldParseNotes) {
+      continue;
+    }
+
+    infoParsers.push(async () => {
+      await retrieveAdditionalDriverInfo(key, `${GOOGLEAPIS_CDN}/${notesPath}`, cdInfo);
+    });
+  }
+  await asyncmap(
+    infoParsers,
+    async (parseInfo) => {
+      await parseInfo();
+    },
+    {concurrency: MAX_PARALLEL_DOWNLOADS},
+  );
+  log.info(`The total count of entries in the mapping: ${Object.keys(mapping).length}`);
+  return mapping;
+}
+
+/**
+ * Downloads chromedriver release notes and updates the driver info dictionary
+ *
+ * Mutates `infoDict` by setting `minBrowserVersion` if found in notes
+ * @param driverKey - Driver version plus archive name
+ * @param notesUrl - The URL of chromedriver notes
+ * @param infoDict - The dictionary containing driver info (will be mutated)
+ * @param timeout - Request timeout in milliseconds
+ */
+async function retrieveAdditionalDriverInfo(
+  driverKey: string,
+  notesUrl: string,
+  infoDict: ChromedriverDetails,
+  timeout = STORAGE_REQ_TIMEOUT_MS,
+): Promise<void> {
+  const notes = await retrieveData(
+    notesUrl,
+    {
+      'user-agent': 'appium',
+      accept: '*/*',
+    },
+    {timeout},
+  );
+  const {minBrowserVersion} = parseNotes(notes);
+  if (!minBrowserVersion) {
+    log.debug(`The driver '${driverKey}' does not contain valid release notes at ${notesUrl}. Skipping it`);
+    return;
+  }
+  infoDict.minBrowserVersion = minBrowserVersion;
+}
+
+function extractNodeText(node: Node | null | undefined): string | null {
+  return !node?.firstChild || !util.hasValue(node.firstChild.nodeValue) ? null : node.firstChild.nodeValue;
+}