appium 3.2.2 → 3.3.0

package/lib/cli/extension.js

@@ -1,74 +0,0 @@
-/* eslint-disable no-console */
-import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
-import {isExtensionCommandArgs} from '../utils';
-import DriverCliCommand from './driver-command';
-import PluginCliCommand from './plugin-command';
-import {errAndQuit, JSON_SPACES} from './utils';
-
-export const commandClasses = Object.freeze(
-  /** @type {const} */ ({
-    [DRIVER_TYPE]: DriverCliCommand,
-    [PLUGIN_TYPE]: PluginCliCommand,
-  })
-);
-
-/**
- * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
- * can be represented as a JS object.
- *
- * @template {import('appium/types').CliExtensionCommand} Cmd
- * @template {import('appium/types').CliExtensionSubcommand} SubCmd
- * @param {import('appium/types').Args<Cmd, SubCmd>} args - JS object where the key is the parameter name (as defined in
- * driver-parser.js)
- * @param {import('../extension/extension-config').ExtensionConfig<Cmd>} config - Extension config object
- */
-async function runExtensionCommand(args, config) {
-  // TODO driver config file should be locked while any of these commands are
-  // running to prevent weird situations
-  let jsonResult = null;
-  const {extensionType: type} = config; // NOTE this is the same as `args.subcommand`
-  if (!isExtensionCommandArgs(args)) {
-    throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
-  }
-  let {json, suppressOutput} = args;
-  json = Boolean(json);
-  if (suppressOutput) {
-    json = true;
-  }
-  const CommandClass = /** @type {ExtCommand<Cmd>} */ (commandClasses[type]);
-  const cmd = new CommandClass({config, json});
-  try {
-    jsonResult = await cmd.execute(args);
-  } catch (err) {
-    // in the suppress output case, we are calling this function internally and should
-    // just throw instead of printing an error and ending the process
-    if (suppressOutput) {
-      throw err;
-    }
-    errAndQuit(json, err);
-  }
-
-  if (json && !suppressOutput) {
-    console.log(JSON.stringify(jsonResult, null, JSON_SPACES));
-  }
-
-  return jsonResult;
-}
-
-export {runExtensionCommand};
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {ExtType extends DriverType ? Class<DriverCliCommand> : ExtType extends PluginType ? Class<PluginCliCommand> : never} ExtCommand
- */
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- * @typedef {import('@appium/types').DriverType} DriverType
- * @typedef {import('@appium/types').PluginType} PluginType
- */
-
-/**
- * @template T
- * @typedef {import('@appium/types').Class<T>} Class
- */

package/lib/cli/plugin-command.js

@@ -1,164 +0,0 @@
-import _ from 'lodash';
-import ExtensionCliCommand from './extension-command';
-import {KNOWN_PLUGINS} from '../constants';
-
-const REQ_PLUGIN_FIELDS = ['pluginName', 'mainClass'];
-
-/**
- * @extends {ExtensionCliCommand<PluginType>}
- */
-export default class PluginCliCommand extends ExtensionCliCommand {
-  /**
-   *
-   * @param {import('./extension-command').ExtensionCommandOptions<PluginType>} opts
-   */
-  constructor({config, json}) {
-    super({config, json});
-    this.knownExtensions = KNOWN_PLUGINS;
-  }
-
-  /**
-   * Install a plugin
-   *
-   * @param {PluginInstallOpts} opts
-   * @returns {Promise<ExtRecord<PluginType>>}
-   */
-  async install({plugin, installType, packageName}) {
-    return await super._install({
-      installSpec: plugin,
-      installType,
-      packageName,
-    });
-  }
-
-  /**
-   * Uninstall a plugin
-   *
-   * @param {PluginUninstallOpts} opts
-   * @returns {Promise<ExtRecord<PluginType>>}
-   */
-  async uninstall({plugin}) {
-    return await super._uninstall({installSpec: plugin});
-  }
-
-  /**
-   * Update a plugin
-   *
-   * @param {PluginUpdateOpts} opts
-   * @returns {Promise<import('./extension-command').ExtensionUpdateResult>}
-   */
-  async update({plugin, unsafe}) {
-    return await super._update({installSpec: plugin, unsafe});
-  }
-
-  /**
-   * Run a script from a plugin
-   *
-   * @param {PluginRunOptions} opts
-   * @returns {Promise<import('./extension-command').RunOutput>}
-   * @throws {Error} if the script fails to run
-   */
-  async run({plugin, scriptName, extraArgs}) {
-    return await super._run({
-      installSpec: plugin,
-      scriptName,
-      extraArgs,
-      bufferOutput: this.isJsonOutput,
-    });
-  }
-
-  /**
-   * Runs doctor checks for the given plugin
-   *
-   * @param {PluginDoctorOptions} opts
-   * @returns {Promise<number>} The amount of executed doctor checks.
-   * @throws {Error} If any of the mandatory Doctor checks fails.
-   */
-  async doctor({plugin}) {
-    return await super._doctor({
-      installSpec: plugin,
-    });
-  }
-
-  /**
-   *
-   * @param {import('./extension-command').ExtensionArgs} opts
-   * @returns {string}
-   */
-  getPostInstallText({extName, extData}) {
-    return `Plugin ${extName}@${extData.version} successfully installed`.green;
-  }
-
-  /**
-   * Validates fields in `appium` field of `pluginMetadata`
-   *
-   * For any `package.json` fields which a plugin requires, validate the type of
-   * those fields on the `package.json` data, throwing an error if anything is
-   * amiss.
-   * @param {import('appium/types').ExtMetadata<PluginType>} pluginMetadata
-   * @param {string} installSpec
-   * @returns {void}
-   */
-  validateExtensionFields(pluginMetadata, installSpec) {
-    const missingFields = REQ_PLUGIN_FIELDS.reduce(
-      (acc, field) => (pluginMetadata[field] ? acc : [...acc, field]),
-      []
-    );
-
-    if (!_.isEmpty(missingFields)) {
-      throw new Error(
-        `Installed plugin "${installSpec}" did not expose correct fields for compatibility ` +
-          `with Appium. Missing fields: ${JSON.stringify(missingFields)}`
-      );
-    }
-  }
-}
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- * @typedef {import('@appium/types').PluginType} PluginType
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
- */
-
-/**
- * Options for {@linkcode PluginCliCommand.install}
- * @typedef PluginInstallOpts
- * @property {string} plugin - the name or spec of a plugin to install
- * @property {InstallType} installType - how to install this plugin. One of the INSTALL_TYPES
- * @property {string} [packageName] - for git/github installs, the plugin node package name
- */
-
-/**
- * @typedef {import('appium/types').InstallType} InstallType
- */
-
-/**
- * Options for {@linkcode PluginCliCommand.uninstall}
- * @typedef PluginUninstallOpts
- * @property {string} plugin - the name or spec of a plugin to uninstall
- */
-
-/**
- * Options for {@linkcode PluginCliCommand.update}
- * @typedef PluginUpdateOpts
- * @property {string} plugin - the name of the plugin to update
- * @property {boolean} unsafe - if true, will perform unsafe updates past major revision boundaries
- */
-
-/**
- * Options for {@linkcode PluginCliCommand.run}.
- * @typedef PluginRunOptions
- * @property {string} plugin - name of the plugin to run a script from
- * @property {string} scriptName - name of the script to run
- * @property {string[]} [extraArgs] - arguments to pass to the script
- */
-
-/**
- * Options for {@linkcode PluginCliCommand.doctor}.
- * @typedef PluginDoctorOptions
- * @property {string} plugin - name of the plugin to run doctor checks for
- */

package/lib/cli/utils.js

@@ -1,91 +0,0 @@
-/* eslint-disable no-console */
-
-import ora from 'ora';
-
-export const JSON_SPACES = 4;
-
-/***
- * Log an error to the console and exit the process.
- * @param {boolean} json - whether we should log json or text
- * @param {any} msg - error message, object, Error instance, etc.
- */
-export function errAndQuit(json, msg) {
-  if (json) {
-    console.log(JSON.stringify({error: `${msg}`}, null, JSON_SPACES));
-  } else {
-    console.error(`${msg}`.red);
-    if (msg.stderr) {
-      console.error(`${msg.stderr}`.red);
-    }
-  }
-  process.exit(1);
-}
-
-/**
- * Conditionally log something to the console
- * @param {boolean} json - whether we are in json mode (and should therefore not log)
- * @param {string} msg - string to log
- */
-export function log(json, msg) {
-  if (!json) {
-    console.log(msg);
-  }
-}
-
-/**
- * Start a spinner, execute an async function, and then stop the spinner
- * @param {boolean} json - whether we are in json mode (and should therefore not log)
- * @param {string} msg - string to log
- * @param {function} fn - function to wrap with spinning
- */
-export async function spinWith(json, msg, fn) {
-  if (json) {
-    return await fn();
-  }
-  const spinner = ora(msg).start();
-  let res;
-  try {
-    res = await fn();
-    spinner.succeed();
-    return res;
-  } catch (err) {
-    spinner.fail();
-    throw err;
-  }
-}
-
-export class RingBuffer {
-  constructor(size = 50) {
-    this.size = size;
-    this.buffer = [];
-  }
-
-  /**
-   * Get the current buffer contents
-   *
-   * @returns {any[]}
-   */
-  getBuff() {
-    return this.buffer;
-  }
-
-  /**
-   * Remove the oldest item from the buffer
-   *
-   * @returns {void}
-   */
-  dequeue() {
-    this.buffer.shift();
-  }
-  /**
-   * Add an item to the buffer
-   *
-   * @param {any} item
-   */
-  enqueue(item) {
-    if (this.buffer.length >= this.size) {
-      this.dequeue();
-    }
-    this.buffer.push(item);
-  }
-}

package/lib/config-file.js

@@ -1,228 +0,0 @@
-import betterAjvErrors from '@sidvind/better-ajv-errors';
-import {lilconfig} from 'lilconfig';
-import _ from 'lodash';
-import * as yaml from 'yaml';
-import {getSchema, validate} from './schema/schema';
-
-/**
- * lilconfig loader to handle `.yaml` files
- * @type {import('lilconfig').LoaderSync}
- */
-function yamlLoader(filepath, content) {
-  try {
-    return yaml.parse(content);
-  } catch (e) {
-    throw new Error(`The YAML config at '${filepath}' cannot be loaded. Original error: ${e.message}`);
-  }
-}
-
-/**
- * A cache of the raw config file (a JSON string) at a filepath.
- * This is used for better error reporting.
- * Note that config files needn't be JSON, but it helps if they are.
- * @type {Map<string,RawJson>}
- */
-const rawConfig = new Map();
-
-/**
- * Custom JSON loader that caches the raw config file (for use with `better-ajv-errors`).
- * If it weren't for this cache, this would be unnecessary.
- * @type {import('lilconfig').LoaderSync}
- */
-function jsonLoader(filepath, content) {
-  rawConfig.set(filepath, content);
-  try {
-    return JSON.parse(content);
-  } catch (e) {
-    throw new Error(`The JSON config at '${filepath}' cannot be loaded. Original error: ${e.message}`);
-  }
-}
-
-/**
- * Loads a config file from an explicit path
- * @param {LilconfigAsyncSearcher} lc - lilconfig instance
- * @param {string} filepath - Path to config file
- * @returns {Promise<import('lilconfig').LilconfigResult>}
- */
-async function loadConfigFile(lc, filepath) {
-  try {
-    // removing "await" will cause any rejection to _not_ be caught in this block!
-    return await lc.load(filepath);
-  } catch (/** @type {unknown} */ err) {
-    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
-      /** @type {NodeJS.ErrnoException} */ (
-        err
-      ).message = `Config file not found at user-provided path: ${filepath}`;
-      throw err;
-    } else if (err instanceof SyntaxError) {
-      // generally invalid JSON
-      err.message = `Config file at user-provided path ${filepath} is invalid:\n${err.message}`;
-      throw err;
-    }
-    throw err;
-  }
-}
-
-/**
- * Searches for a config file
- * @param {LilconfigAsyncSearcher} lc - lilconfig instance
- * @returns {Promise<import('lilconfig').LilconfigResult>}
- */
-async function searchConfigFile(lc) {
-  return await lc.search();
-}
-
-/**
- * Given an array of errors and the result of loading a config file, generate a
- * helpful string for the user.
- *
- * - If `opts` contains a `json` property, this should be the original JSON
- *   _string_ of the config file.  This is only applicable if the config file
- *   was in JSON format. If present, it will associate line numbers with errors.
- * - If `errors` happens to be empty, this will throw.
- * @param {import('ajv').ErrorObject[]} errors - Non-empty array of errors. Required.
- * @param {ReadConfigFileResult['config']|any} [config] -
- * Configuration & metadata
- * @param {FormatConfigErrorsOptions} [opts]
- * @throws {TypeError} If `errors` is empty
- * @returns {string}
- */
-export function formatErrors(errors = [], config = {}, opts = {}) {
-  if (errors && !errors.length) {
-    throw new TypeError('Array of errors must be non-empty');
-  }
-  return betterAjvErrors(getSchema(opts.schemaId), config, errors, {
-    json: opts.json,
-    format: 'cli',
-  });
-}
-
-/**
- * Given an optional path, read a config file. Validates the config file.
- *
- * Call {@link validate} if you already have a config object.
- * @param {string} [filepath] - Path to config file, if we have one
- * @param {ReadConfigFileOptions} [opts] - Options
- * @public
- * @returns {Promise<ReadConfigFileResult>} Contains config and filepath, if found, and any errors
- */
-export async function readConfigFile(filepath, opts = {}) {
-  const lc = lilconfig('appium', {
-    loaders: {
-      '.yaml': yamlLoader,
-      '.yml': yamlLoader,
-      '.json': jsonLoader,
-      noExt: jsonLoader,
-    },
-    packageProp: 'appiumConfig',
-  });
-
-  const result = filepath ? await loadConfigFile(lc, filepath) : await searchConfigFile(lc);
-
-  if (result?.filepath && !result?.isEmpty) {
-    const {pretty = true} = opts;
-    try {
-      let configResult;
-      const errors = validate(result.config);
-      if (_.isEmpty(errors)) {
-        configResult = {...result, errors};
-      } else {
-        const reason = formatErrors(errors, result.config, {
-          json: rawConfig.get(result.filepath),
-          pretty,
-        });
-        configResult = reason ? {...result, errors, reason} : {...result, errors};
-      }
-
-      // normalize (to camel case) all top-level property names of the config file
-      configResult.config = normalizeConfig(/** @type {AppiumConfig} */ (configResult.config));
-
-      return configResult;
-    } finally {
-      // clean up the raw config file cache, which is only kept to better report errors.
-      rawConfig.delete(result.filepath);
-    }
-  }
-  return result ?? {};
-}
-
-/**
- * Convert schema property names to either a) the value of the `appiumCliDest` property, if any; or b) camel-case
- * @param {AppiumConfig} config - Configuration object
- * @returns {NormalizedAppiumConfig} New object with camel-cased keys (or `dest` keys).
- */
-export function normalizeConfig(config) {
-  const schema = getSchema();
-  /**
-   * @param {AppiumConfig} config
-   * @param {string} [section] - Keypath (lodash `_.get()` style) to section of config. If omitted, assume root Appium config schema
-   * @todo Rewrite as a loop
-   * @returns Normalized section of config
-   */
-  const normalize = (config, section) => {
-    const obj = _.isUndefined(section) ? config : _.get(config, section, config);
-
-    const mappedObj = _.mapKeys(obj, (__, prop) =>
-      _.get(schema, `properties.server.properties[${prop}].appiumCliDest`, _.camelCase(prop))
-    );
-
-    return _.mapValues(mappedObj, (value, property) => {
-      const nextSection = section ? `${section}.${property}` : property;
-      return isSchemaTypeObject(schema.properties?.[property])
-        ? normalize(config, nextSection)
-        : value;
-    });
-  };
-
-  /**
-   * Returns `true` if the schema prop references an object, or if it's an object itself
-   * @param {import('ajv').SchemaObject|object} schema - Referencing schema object
-   */
-  const isSchemaTypeObject = (schema) => Boolean(schema?.properties || schema?.type === 'object');
-
-  return normalize(config);
-}
-
-/**
- * Result of calling {@link readConfigFile}.
- * @typedef ReadConfigFileResult
- * @property {import('ajv').ErrorObject[]} [errors] - Validation errors
- * @property {string} [filepath] - The path to the config file, if found
- * @property {boolean} [isEmpty] - If `true`, the config file exists but is empty
- * @property {NormalizedAppiumConfig} [config] - The parsed configuration
- * @property {string|import('@sidvind/better-ajv-errors').IOutputError[]} [reason] - Human-readable error messages and suggestions. If the `pretty` option is `true`, this will be a nice string to print.
- */
-
-/**
- * Options for {@link readConfigFile}.
- * @typedef ReadConfigFileOptions
- * @property {boolean} [pretty=true] If `false`, do not use color and fancy formatting in the `reason` property of the {@link ReadConfigFileResult}. The value of `reason` is then suitable for machine-reading.
- */
-
-/**
- * This is an `AsyncSearcher` which is inexplicably _not_ exported by the `lilconfig` type definition.
- * @typedef {ReturnType<import('lilconfig')["lilconfig"]>} LilconfigAsyncSearcher
- */
-
-/**
- * The contents of an Appium config file. Generated from schema
- * @typedef {import('@appium/types').AppiumConfig} AppiumConfig
- */
-
-/**
- * The contents of an Appium config file with camelcased property names (and using `appiumCliDest` value if present). Generated from {@link AppiumConfig}
- * @typedef {import('@appium/types').NormalizedAppiumConfig} NormalizedAppiumConfig
- */
-
-/**
- * The string should be a raw JSON string.
- * @typedef {string} RawJson
- */
-
-/**
- * Options for {@link formatErrors}.
- * @typedef FormatConfigErrorsOptions
- * @property {import('./config-file').RawJson} [json] - Raw JSON config (as string)
- * @property {boolean} [pretty=true] - Whether to format errors as a CLI-friendly string
- * @property {string}  [schemaId] - Specific ID of a prop; otherwise entire schema
- */

package/lib/grid-register.js

@@ -1,146 +0,0 @@
-import axios from 'axios';
-import {fs} from '@appium/support';
-import logger from './logger';
-import _ from 'lodash';
-
-const hubUri = (config) => {
-  const protocol = config.hubProtocol || 'http';
-  return `${protocol}://${config.hubHost}:${config.hubPort}`;
-};
-
-/**
- * Registers a new node with a selenium grid
- * @param {string|object} data - Path or object representing selenium grid node config file. If a `string`, all subsequent arguments are required!
- * @param {string} [addr] - Bind to this address
- * @param {number} [port] - Bind to this port
- * @param {string} [basePath] - Base path for the grid
- */
-async function registerNode(data, addr, port, basePath) {
-  let configFilePath;
-  if (_.isString(data)) {
-    configFilePath = data;
-    try {
-      data = await fs.readFile(data, 'utf-8');
-    } catch (err) {
-      logger.error(
-        `Unable to load node configuration file ${configFilePath} to register with grid: ${err.message}`
-      );
-      return;
-    }
-    try {
-      data = JSON.parse(data);
-    } catch (err) {
-      throw logger.errorWithException(
-        `Syntax error in node configuration file ${configFilePath}: ${err.message}`
-      );
-    }
-  }
-
-  postRequest(data, addr, port, basePath);
-}
-
-async function registerToGrid(postOptions, configHolder) {
-  try {
-    const {status} = await axios(postOptions);
-    if (status !== 200) {
-      throw new Error(`Request failed with code ${status}`);
-    }
-    logger.debug(
-      `Appium successfully registered with the the grid on ` + hubUri(configHolder.configuration)
-    );
-  } catch (err) {
-    logger.error(`An attempt to register with the grid was unsuccessful: ${err.message}`);
-  }
-}
-
-function postRequest(configHolder, addr, port, basePath) {
-  // Move Selenium 3 configuration properties to configuration object
-  if (!_.has(configHolder, 'configuration')) {
-    let configuration = {};
-    for (const property in /** @type {import('@appium/types').StringRecord} */ (configHolder)) {
-      if (_.has(configHolder, property) && property !== 'capabilities') {
-        configuration[property] = configHolder[property];
-        delete configHolder[property];
-      }
-    }
-    /** @type {import('@appium/types').StringRecord} */ (configHolder).configuration = configuration;
-  }
-
-  // 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 grid aren't in the same place
-  if (
-    !configHolder.configuration.url ||
-    !configHolder.configuration.host ||
-    !configHolder.configuration.port
-  ) {
-    configHolder.configuration.url = `http://${addr}:${port}${basePath}`;
-    configHolder.configuration.host = addr;
-    configHolder.configuration.port = port;
-  }
-  // if the node config does not have id automatically add it
-  if (!configHolder.configuration.id) {
-    configHolder.configuration.id = `http://${configHolder.configuration.host}:${configHolder.configuration.port}`;
-  }
-
-  // the post options
-  const regRequest = {
-    url: `${hubUri(configHolder.configuration)}/grid/register`,
-    method: 'POST',
-    data: configHolder,
-  };
-
-  if (configHolder.configuration.register !== true) {
-    logger.debug(`No registration sent (${configHolder.configuration.register} = false)`);
-    return;
-  }
-
-  const registerCycleInterval = configHolder.configuration.registerCycle;
-  if (isNaN(registerCycleInterval) || registerCycleInterval <= 0) {
-    logger.warn(
-      `'registerCycle' is not a valid positive number. ` +
-        `No registration request will be sent to the grid.`
-    );
-    return;
-  }
-  // initiate a new Thread
-  let first = true;
-  logger.debug(
-    `Starting auto register thread for the grid. ` +
-      `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 grid for registration
-      await registerToGrid(regRequest, configHolder);
-    }
-  }, registerCycleInterval);
-}
-
-async function isAlreadyRegistered(configHolder) {
-  //check if node is already registered
-  const id = configHolder.configuration.id;
-  try {
-    const {data, status} = await axios({
-      url: `${hubUri(configHolder.configuration)}/grid/api/proxy?id=${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(`Grid registration error: ${data.msg}`);
-    }
-    return data.success;
-  } catch (err) {
-    logger.debug(`Hub down or not responding: ${err.message}`);
-  }
-}
-
-export default registerNode;