appium 3.2.2 → 3.3.1

package/lib/doctor/{doctor.js → doctor.ts}

@@ -1,45 +1,79 @@
 import '@colors/colors';
 import _ from 'lodash';
-import { util, doctor, logger } from '@appium/support';
+import {util, doctor, logger} from '@appium/support';
+import type {AppiumLogger, DoctorCheckResult, IDoctorCheck} from '@appium/types';
 
-export const EXIT_CODE = /** @type {const} */ Object.freeze({
+/**
+ * Process exit codes returned by {@link Doctor.run}.
+ */
+export const EXIT_CODE = Object.freeze({
   SUCCESS: 0,
   HAS_MAJOR_ISSUES: 127,
-});
+} as const);
+
+/** Exit code values produced by {@link Doctor.run}. */
+export type DoctorExitCode = (typeof EXIT_CODE)[keyof typeof EXIT_CODE];
+
+/**
+ * A failed check reported during {@link Doctor} diagnostics.
+ */
+export interface DoctorIssue {
+  /** The check that produced this issue. */
+  check: IDoctorCheck;
+  /** Colored message string as logged during diagnosis. */
+  error: string;
+  /** Set after a successful automatic fix attempt. */
+  fixed?: boolean;
+}
 
 export class Doctor {
-  /**
-   * @param {DoctorCheck[]} [checks=[]]
-   */
-  constructor(checks = []) {
+  private readonly log: AppiumLogger;
+  private readonly checks: IDoctorCheck[];
+  private foundIssues: DoctorIssue[];
+
+  constructor(checks: IDoctorCheck[] = []) {
     this.log = logger.getLogger('Doctor');
-    /** @type {DoctorCheck[]} */
     this.checks = checks;
     this.checks
       .filter((c) => _.isNil(c.log))
-      .forEach((c) => { c.log = this.log; });
-    /** @type {DoctorIssue[]} */
+      .forEach((c) => {
+        c.log = this.log;
+      });
     this.foundIssues = [];
   }
 
-  /**
-   * @returns {DoctorIssue[]}
-   */
-  get issuesRequiredToFix() {
+  private get issuesRequiredToFix(): DoctorIssue[] {
     return this.foundIssues.filter((f) => !f.check.isOptional());
   }
 
+  private get issuesOptionalToFix(): DoctorIssue[] {
+    return this.foundIssues.filter((f) => f.check.isOptional());
+  }
+
   /**
-   * @returns {DoctorIssue[]}
+   * Runs diagnostics, reports issues, attempts automatic fixes where supported, and returns an exit code.
+   *
+   * @returns {@link EXIT_CODE.SUCCESS} when there are no issues or all issues were resolved;
+   *   {@link EXIT_CODE.HAS_MAJOR_ISSUES} when manual intervention is still required or fixes failed.
    */
-  get issuesOptionalToFix() {
-    return this.foundIssues.filter((f) => f.check.isOptional());
+  async run(): Promise<DoctorExitCode> {
+    await this.diagnose();
+    if (this.reportSuccess()) {
+      return EXIT_CODE.SUCCESS;
+    }
+    if (await this.reportManualIssues()) {
+      return EXIT_CODE.HAS_MAJOR_ISSUES;
+    }
+    if (!(await this.runAutoFixes())) {
+      return EXIT_CODE.HAS_MAJOR_ISSUES;
+    }
+    return EXIT_CODE.SUCCESS;
   }
 
   /**
    * The doctor shows the report
    */
-  async diagnose() {
+  private async diagnose(): Promise<void> {
     this.log.info(`### Starting doctor diagnostics  ###`);
     this.foundIssues = [];
     for (const check of this.checks) {
@@ -49,20 +83,15 @@ export class Doctor {
         this.foundIssues.push(issue);
       }
     }
-    this.log.info(
-      `### Diagnostic completed, ${this.buildFixMessage()}. ###`
-    );
+    this.log.info(`### Diagnostic completed, ${this.buildFixMessage()}. ###`);
     this.log.info('');
   }
 
-  /**
-   * @returns {Promise<boolean>}
-   */
-  async reportManualIssues() {
+  private async reportManualIssues(): Promise<boolean> {
     const manualIssues = _.filter(this.issuesRequiredToFix, (f) => !f.check.hasAutofix());
     const manualIssuesOptional = _.filter(this.issuesOptionalToFix, (f) => !f.check.hasAutofix());
 
-    const handleIssues = async (headerLogs, issues) => {
+    const handleIssues = async (headerLogs: string[], issues: DoctorIssue[]): Promise<void> => {
       if (_.isEmpty(issues)) {
         return;
       }
@@ -70,14 +99,13 @@ export class Doctor {
       for (const logMsg of headerLogs) {
         this.log.info(logMsg);
       }
-      /** @type {string[]} */
-      const fixMessages = [];
+      const fixMessages: string[] = [];
       for (const issue of issues) {
-        let message;
+        let message: string | null;
         try {
           message = await issue.check.fix();
         } catch (e) {
-          message = e.message;
+          message = (e as Error).message;
         }
         if (message) {
           fixMessages.push(message);
@@ -89,14 +117,20 @@ export class Doctor {
       this.log.info('');
     };
 
-    await handleIssues([
-      '### Manual Fixes Needed ###',
-      'The configuration cannot be automatically fixed, please do the following first:',
-    ], manualIssues);
-    await handleIssues([
-      '### Optional Manual Fixes ###',
-      'To fix these optional issues, please do the following manually:',
-    ], manualIssuesOptional);
+    await handleIssues(
+      [
+        '### Manual Fixes Needed ###',
+        'The configuration cannot be automatically fixed, please do the following first:',
+      ],
+      manualIssues
+    );
+    await handleIssues(
+      [
+        '### Optional Manual Fixes ###',
+        'To fix these optional issues, please do the following manually:',
+      ],
+      manualIssuesOptional
+    );
 
     if (manualIssues.length > 0) {
       this.log.info('###');
@@ -108,15 +142,12 @@ export class Doctor {
     return false;
   }
 
-  /**
-   * @param {DoctorIssue} f
-   */
-  async runAutoFix(f) {
+  private async runAutoFix(f: DoctorIssue): Promise<void> {
     this.log.info(`### Fixing: ${f.error} ###`);
     try {
       await f.check.fix();
     } catch (err) {
-      if (err.constructor.name === doctor.FixSkippedError.name) {
+      if (err instanceof doctor.FixSkippedError) {
         this.log.info(`### Skipped fix ###`);
         return;
       } else {
@@ -137,10 +168,7 @@ export class Doctor {
     }
   }
 
-  /**
-   * @returns {Promise<boolean>}
-   */
-  async runAutoFixes() {
+  private async runAutoFixes(): Promise<boolean> {
     const autoFixes = _.filter(this.foundIssues, (f) => f.check.hasAutofix());
     for (const f of autoFixes) {
       await this.runAutoFix(f);
@@ -158,29 +186,7 @@ export class Doctor {
     return true;
   }
 
-  /**
-   * @returns {Promise<EXIT_CODE[keyof EXIT_CODE]>}
-   */
-  async run() {
-    await this.diagnose();
-    if (this.reportSuccess()) {
-      return EXIT_CODE.SUCCESS;
-    }
-    if (await this.reportManualIssues()) {
-      return EXIT_CODE.HAS_MAJOR_ISSUES;
-    }
-    if (!await this.runAutoFixes()) {
-      return EXIT_CODE.HAS_MAJOR_ISSUES;
-    }
-    return EXIT_CODE.SUCCESS;
-  }
-
-  /**
-   * @param {DoctorCheckResult} result
-   * @param {DoctorCheck} check
-   * @returns {DoctorIssue?}
-   */
-  toIssue(result, check) {
+  private toIssue(result: DoctorCheckResult, check: IDoctorCheck): DoctorIssue | null {
     if (result.ok) {
       this.log.info(` ${'\u2714'.green} ${result.message}`);
       return null;
@@ -196,18 +202,14 @@ export class Doctor {
     };
   }
 
-  /**
-   * @returns {string}
-   */
-  buildFixMessage() {
-    return `${util.pluralize('required fix', this.issuesRequiredToFix.length, true)} needed, ` +
-      `${util.pluralize('optional fix', this.issuesOptionalToFix.length, true)} possible`;
+  private buildFixMessage(): string {
+    return (
+      `${util.pluralize('required fix', this.issuesRequiredToFix.length, true)} needed, ` +
+      `${util.pluralize('optional fix', this.issuesOptionalToFix.length, true)} possible`
+    );
   }
 
-  /**
-   * @returns {boolean}
-   */
-  reportSuccess() {
+  private reportSuccess(): boolean {
     if (this.issuesRequiredToFix.length === 0 && this.issuesOptionalToFix.length === 0) {
       this.log.info('Everything looks good, bye!');
       this.log.info('');
@@ -216,15 +218,3 @@ export class Doctor {
     return false;
   }
 }
-
-/**
- * @typedef DoctorIssue
- * @property {DoctorCheck} check
- * @property {string} error
- * @property {boolean} [fixed]
- */
-
-/**
- * @typedef {import('@appium/types').IDoctorCheck} DoctorCheck
- * @typedef {import('@appium/types').DoctorCheckResult} DoctorCheckResult
- */

package/lib/extension/driver-config.ts

@@ -0,0 +1,165 @@
+import _ from 'lodash';
+import type {DriverClass, DriverType, StringRecord} from '@appium/types';
+import type {ExtManifest, ExtName, ExtRecord} from 'appium/types';
+import {DRIVER_TYPE} from '../constants';
+import {log} from '../logger';
+import type {ExtManifestProblem} from './extension-config';
+import {ExtensionConfig} from './extension-config';
+import type {Manifest} from './manifest';
+
+export type MatchedDriver = {
+  driver: DriverClass;
+  version: string;
+  driverName: string;
+};
+
+export class DriverConfig extends ExtensionConfig<DriverType> {
+  private static readonly _instances = new WeakMap<Manifest, DriverConfig>();
+  private knownAutomationNames = new Set<string>();
+
+  private constructor(manifest: Manifest) {
+    super(DRIVER_TYPE, manifest);
+  }
+
+  static create(manifest: Manifest): DriverConfig {
+    const instance = new DriverConfig(manifest);
+    if (DriverConfig.getInstance(manifest)) {
+      throw new Error(
+        `Manifest with APPIUM_HOME ${manifest.appiumHome} already has a DriverConfig; use DriverConfig.getInstance() to retrieve it.`
+      );
+    }
+    DriverConfig._instances.set(manifest, instance);
+    return instance;
+  }
+
+  static getInstance(manifest: Manifest): DriverConfig | undefined {
+    return DriverConfig._instances.get(manifest);
+  }
+
+  async validate(): Promise<ExtRecord<DriverType>> {
+    this.knownAutomationNames.clear();
+    return await super._validate(this.manifest.getExtensionData(DRIVER_TYPE));
+  }
+
+  public override extensionDesc(
+    driverName: ExtName<DriverType>,
+    {version, automationName}: ExtManifest<DriverType>
+  ): string {
+    return `${String(driverName)}@${version} (automationName '${automationName}')`;
+  }
+
+  async findMatchingDriver<C extends StringRecord>({
+    automationName,
+    platformName,
+  }: C): Promise<MatchedDriver> {
+    if (!_.isString(platformName)) {
+      throw new Error('You must include a platformName capability');
+    }
+
+    if (!_.isString(automationName)) {
+      throw new Error('You must include an automationName capability');
+    }
+
+    log.info(
+      `Attempting to find matching driver for automationName ` +
+        `'${automationName}' and platformName '${platformName}'`
+    );
+
+    try {
+      const {driverName, mainClass, version} = this._getDriverBySupport(automationName, platformName);
+      log.info(`The '${driverName}' driver was installed and matched caps.`);
+      log.info(`Will require it at ${this.getInstallPath(driverName)}`);
+      const driver = await this.requireAsync(driverName as ExtName<DriverType>);
+      if (!driver) {
+        throw new Error(
+          `Driver '${driverName}' did not export a class with name '${mainClass}'. Contact the author of the driver!`
+        );
+      }
+      return {driver, version, driverName};
+    } catch (err: any) {
+      const msg =
+        `Could not find a driver for automationName ` +
+        `'${automationName}' and platformName '${platformName}'. ` +
+        `Have you installed a driver that supports those ` +
+        `capabilities? Run 'appium driver list --installed' to see. ` +
+        `(Lower-level error: ${err.message})`;
+      throw new Error(msg);
+    }
+  }
+
+  protected override getConfigProblems(
+    extManifest: ExtManifest<DriverType>,
+    extName: string
+  ): ExtManifestProblem[] {
+    void extName;
+    const problems: ExtManifestProblem[] = [];
+    const {platformNames, automationName} = extManifest;
+
+    if (!_.isArray(platformNames)) {
+      problems.push({
+        err: 'Missing or incorrect supported platformNames list.',
+        val: platformNames,
+      });
+    } else if (_.isEmpty(platformNames)) {
+      problems.push({
+        err: 'Empty platformNames list.',
+        val: platformNames,
+      });
+    } else {
+      for (const pName of platformNames) {
+        if (!_.isString(pName)) {
+          problems.push({
+            err: 'Incorrectly formatted platformName.',
+            val: pName,
+          });
+        }
+      }
+    }
+
+    if (!_.isString(automationName)) {
+      problems.push({
+        err: 'Missing or incorrect automationName',
+        val: automationName,
+      });
+    }
+
+    if (this.knownAutomationNames.has(automationName as string)) {
+      problems.push({
+        err: 'Multiple drivers claim support for the same automationName',
+        val: automationName,
+      });
+    }
+
+    this.knownAutomationNames.add(automationName as string);
+
+    return problems;
+  }
+
+  private _getDriverBySupport(
+    matchAutomationName: string,
+    matchPlatformName: string
+  ): ExtManifest<DriverType> & {driverName: string} {
+    const drivers = this.installedExtensions;
+    for (const [driverName, driverData] of _.toPairs(drivers)) {
+      const {automationName, platformNames} = driverData;
+      const aNameMatches = automationName.toLowerCase() === matchAutomationName.toLowerCase();
+      const pNameMatches = _.includes(platformNames.map((p) => _.toLower(p)), matchPlatformName.toLowerCase());
+
+      if (aNameMatches && pNameMatches) {
+        return {driverName, ...driverData};
+      }
+
+      if (aNameMatches) {
+        throw new Error(
+          `Driver '${driverName}' supports automationName ` +
+            `'${automationName}', but Appium could not find ` +
+            `support for platformName '${matchPlatformName}'. Supported ` +
+            `platformNames are: ` +
+            JSON.stringify(platformNames)
+        );
+      }
+    }
+
+    throw new Error(`Could not find installed driver to support given caps`);
+  }
+}