appium 3.2.2 → 3.3.0

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[]}
+   * 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 issuesRequiredToFix() {
+  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;
+  }
+
+  private get issuesRequiredToFix(): DoctorIssue[] {
     return this.foundIssues.filter((f) => !f.check.isOptional());
   }
 
-  /**
-   * @returns {DoctorIssue[]}
-   */
-  get issuesOptionalToFix() {
+  private get issuesOptionalToFix(): DoctorIssue[] {
     return this.foundIssues.filter((f) => f.check.isOptional());
   }
 
   /**
    * 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/grid-register.ts

@@ -0,0 +1,250 @@
+import axios from 'axios';
+import {fs} from '@appium/support';
+import type {StringRecord} from '@appium/types';
+import _ from 'lodash';
+import logger from './logger';
+
+/**
+ * Selenium **Grid 3** (legacy hub) node integration.
+ *
+ * Registers this Appium process as a node with a Selenium Grid 3 hub using the classic
+ * `/grid/register` endpoint and `/grid/api/proxy` for re-registration checks.
+ * This does **not** apply to Selenium Grid 4 (which uses a different topology and APIs).
+ *
+ * @see https://www.selenium.dev/documentation/legacy/grid_3/
+ */
+
+/** REST paths exposed by a Selenium Grid 3 hub. */
+const GRID_V3_REGISTER_PATH = '/grid/register';
+const GRID_V3_PROXY_API_PATH = '/grid/api/proxy';
+
+/**
+ * Registers this server as a node with a **Selenium Grid 3** hub.
+ *
+ * When `data` is a path to a JSON config file, `addr`, `port`, and `basePath` are required (they define
+ * how the hub reaches this Appium server). When `data` is an inline config object, those parameters are
+ * optional and only used to fill missing node URL fields in the config.
+ *
+ * @deprecated Selenium Grid 3 registration is legacy and slated for removal.
+ * Use Selenium Grid 4 integration (node relay) instead.
+ *
+ * @param data - Path to a JSON file or an inline parsed config object
+ * @param addr - Bind to this address
+ * @param port - Bind to this port
+ * @param basePath - Base path for the Appium server (used in the node URL sent to the hub; may be `''`)
+ */
+export default async function registerNode(
+  data: string,
+  addr: string,
+  port: number,
+  basePath: string
+): Promise<void>;
+export default async function registerNode(
+  data: Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): Promise<void>;
+export default async function registerNode(
+  data: string | Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): Promise<void> {
+  if (typeof data === 'string') {
+    if (addr === undefined || port === undefined || basePath === undefined) {
+      throw logger.errorWithException(
+        'When the first argument is a Selenium Grid 3 node config file path, address, port, and basePath ' +
+          'are required (e.g. match your Appium `--address`, `--port`, and base path).'
+      );
+    }
+    if (typeof port !== 'number' || !Number.isFinite(port)) {
+      throw logger.errorWithException(
+        'When registering from a node config file path, port must be a finite number.'
+      );
+    }
+  }
+
+  let configHolder: Grid3NodeConfig;
+  if (_.isString(data)) {
+    const configFilePath = data;
+    let fileContent: string;
+    try {
+      fileContent = await fs.readFile(data, 'utf-8');
+    } catch (err) {
+      logger.error(
+        `Unable to load Selenium Grid 3 node configuration file ${configFilePath} to ` +
+        `register with the hub: ${(err as Error).message}`
+      );
+      return;
+    }
+    try {
+      configHolder = JSON.parse(fileContent) as Grid3NodeConfig;
+    } catch (err) {
+      throw logger.errorWithException(
+        `Syntax error in Selenium Grid 3 node configuration file ${configFilePath}: ` +
+        (err as Error).message
+      );
+    }
+  } else {
+    configHolder = data;
+  }
+
+  postRequest(configHolder, addr, port, basePath);
+}
+
+/** Base URL for the Selenium Grid 3 hub (protocol + host + port). */
+function hubUri(config: Grid3HubConfiguration): string {
+  const protocol = config.hubProtocol || 'http';
+  return `${protocol}://${config.hubHost}:${config.hubPort}`;
+}
+
+/** POST registration payload to the Selenium Grid 3 hub. */
+async function registerToGrid(
+  postOptions: {url: string; method: string; data: Grid3NodeConfig},
+  configHolder: Grid3NodeConfig
+): Promise<void> {
+  const hubCfg = configHolder.configuration;
+  if (!hubCfg) {
+    return;
+  }
+  try {
+    const {status} = await axios(postOptions);
+    if (status !== 200) {
+      throw new Error(`Request failed with code ${status}`);
+    }
+    logger.debug(
+      `Appium successfully registered with the Selenium Grid 3 hub at ` + hubUri(hubCfg)
+    );
+  } catch (err) {
+    logger.error(
+      `An attempt to register with the Selenium Grid 3 hub was unsuccessful: ` +
+      (err as Error).message
+    );
+  }
+}
+
+function postRequest(
+  configHolder: Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): void {
+  // Move Selenium Grid 3 (flat) configuration properties into `configuration`
+  if (!_.has(configHolder, 'configuration')) {
+    const configuration: StringRecord = {};
+    const holder = configHolder as StringRecord;
+    for (const property in holder) {
+      if (_.has(holder, property) && property !== 'capabilities') {
+        configuration[property] = holder[property];
+        delete holder[property];
+      }
+    }
+    holder.configuration = configuration as Grid3HubConfiguration;
+  }
+
+  const cfg = configHolder.configuration;
+  if (!cfg) {
+    return;
+  }
+
+  // if the node config does not have the appium/webdriver url, host, and port,
+  // automatically add it based on how appium was initialized
+  // otherwise, we will take whatever the user setup
+  // because we will always set localhost/127.0.0.1. this won't work if your
+  // node and hub aren't in the same place
+  if (!cfg.url || !cfg.host || !cfg.port) {
+    cfg.url = `http://${addr}:${port}${basePath}`;
+    cfg.host = addr;
+    cfg.port = port;
+  }
+  // if the node config does not have id automatically add it
+  if (!cfg.id) {
+    cfg.id = `http://${cfg.host}:${cfg.port}`;
+  }
+
+  // the post options
+  const regRequest = {
+    url: `${hubUri(cfg)}${GRID_V3_REGISTER_PATH}`,
+    method: 'POST',
+    data: configHolder,
+  };
+
+  if (cfg.register !== true) {
+    logger.debug(`No Selenium Grid 3 hub registration sent (${cfg.register} = false)`);
+    return;
+  }
+
+  const registerCycleInterval = cfg.registerCycle;
+  if (registerCycleInterval === undefined || isNaN(registerCycleInterval) || registerCycleInterval <= 0) {
+    logger.warn(
+      `'registerCycle' is not a valid positive number. ` +
+        `No registration request will be sent to the Selenium Grid 3 hub.`
+    );
+    return;
+  }
+  // initiate a new Thread
+  let first = true;
+  logger.debug(
+    `Starting auto-register thread for Selenium Grid 3. ` +
+      `Will try to register every ${registerCycleInterval} ms.`
+  );
+  setInterval(async function registerRetry() {
+    if (first) {
+      first = false;
+      await registerToGrid(regRequest, configHolder);
+    } else if (!(await isAlreadyRegistered(configHolder))) {
+      // make the http POST to the Selenium Grid 3 hub for registration
+      await registerToGrid(regRequest, configHolder);
+    }
+  }, registerCycleInterval);
+}
+
+/** Query the Selenium Grid 3 hub to see if this node id is already registered. */
+async function isAlreadyRegistered(configHolder: Grid3NodeConfig): Promise<boolean | undefined> {
+  //check if node is already registered
+  const hubCfg = configHolder.configuration;
+  if (!hubCfg?.id) {
+    return;
+  }
+  const id = hubCfg.id;
+  try {
+    const {data, status} = await axios<Grid3ProxyApiResponse>({
+      url: `${hubUri(hubCfg)}${GRID_V3_PROXY_API_PATH}`,
+      params: {id},
+      timeout: 10000,
+    });
+    if (status !== 200) {
+      throw new Error(`Request failed with code ${status}`);
+    }
+    if (!data.success) {
+      // if register fail, print the debug msg
+      logger.debug(`Selenium Grid 3 hub registration check: ${data.msg}`);
+    }
+    return data.success;
+  } catch (err) {
+    logger.debug(`Selenium Grid 3 hub down or not responding: ${(err as Error).message}`);
+  }
+}
+
+interface Grid3HubConfiguration {
+  hubProtocol?: string;
+  hubHost?: string;
+  hubPort?: number;
+  url?: string;
+  host?: string;
+  port?: number;
+  id?: string;
+  register?: boolean;
+  registerCycle?: number;
+}
+
+interface Grid3NodeConfig extends StringRecord {
+  configuration?: Grid3HubConfiguration;
+  capabilities?: unknown;
+}
+
+interface Grid3ProxyApiResponse {
+  success: boolean;
+  msg?: string;
+}