appium 3.2.1 → 3.3.0

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;

package/lib/schema/arg-spec.js

@@ -1,229 +0,0 @@
-import _ from 'lodash';
-
-/**
- * The original ID of the Appium config schema.
- * We use this in the CLI to convert it to `argparse` options.
- */
-export const APPIUM_CONFIG_SCHEMA_ID = 'appium.json';
-
-/**
- * The schema prop containing server-related options. Everything in here
- * is "native" to Appium.
- * Used by {@link flattenSchema} for transforming the schema into CLI args.
- */
-export const SERVER_PROP_NAME = 'server';
-
-/**
- * Used to parse extension info from a schema ID.
- */
-const SCHEMA_ID_REGEXP = /^(?<extType>.+?)-(?<normalizedExtName>.+)\.json$/;
-
-/**
- * Avoid typos by using constants!
- */
-const PROPERTIES = 'properties';
-
-/**
- * An `ArgSpec` is a class representing metadata about an argument (or config
- * option) used for cross-referencing.
- *
- * This class has no instance methods, and is basically just a read-only "struct".
- * @template D
- */
-export class ArgSpec {
-  /**
-   * The canonical name of the argument. Corresponds to key in schema's `properties` prop.
-   * @type {string}
-   */
-  name;
-
-  /**
-   * The `ExtensionType` of the argument. This will be set if the arg came from an extension;
-   * otherwise it will be `undefined`.
-   * @type {ExtensionType|undefined}
-   */
-  extType;
-
-  /**
-   * The name of the extension, if this argument came from an extension.
-   *
-   * Otherwise `undefined`.
-   * @type {string|undefined}
-   */
-  extName;
-
-  /**
-   * The schema ID (`$id`) for the argument.  This is automatically determined, and any user-provided `$id`s will be overwritten.
-   *
-   * @type {string}
-   */
-  ref;
-
-  /**
-   * The CLI argument, sans leading dashes.
-   * @type {string}
-   */
-  arg;
-
-  /**
-   * The desired keypath for the argument after arguments have been parsed.
-   *
-   * Typically this is camelCased.  If the arg came from an extension, it will be prefixed with
-   * `<extType>.<extName>.`
-   * @type {string}
-   */
-  dest;
-
-  /**
-   * The same as {@link ArgSpec.dest} but without the leading `<extType>.<extName>.` prefix.
-   */
-  rawDest;
-
-  /**
-   * Whatever the default value of this argument is, as specified by the
-   * `default` property of the schema.
-   * @type {D|undefined}
-   */
-  defaultValue;
-
-  /**
-   * Builds some computed fields and assigns them to the instance.
-   *
-   * Undefined properties are not assigned.
-   *
-   * The _constructor_ is private. Use {@link ArgSpec.create} instead.
-   * @private
-   * @param {string} name
-   * @param {ArgSpecOptions<D>} opts
-   */
-  constructor(name, {extType, extName, dest, defaultValue} = {}) {
-    // we must normalize the extension name to fit into our convention for CLI
-    // args.
-    const arg = ArgSpec.toArg(name, extType, extName);
-
-    const ref = ArgSpec.toSchemaRef(name, extType, extName);
-
-    // if no explicit `dest` provided, just camelCase the name to avoid needing
-    // to use bracket syntax when accessing props on the parsed args object.
-    const rawDest = _.camelCase(dest ?? name);
-
-    const destKeypath = extType && extName ? [extType, extName, rawDest].join('.') : rawDest;
-
-    this.defaultValue = defaultValue;
-    this.name = name;
-    this.extType = extType;
-    this.extName = extName;
-    this.arg = arg;
-    this.dest = destKeypath;
-    this.ref = ref;
-    this.rawDest = rawDest;
-  }
-
-  /**
-   * Return the schema ID (`$id`) for the **argument** given the parameters.
-   *
-   * If you need the "root" or "base" schema ID, use {@link ArgSpec.toSchemaBaseRef} instead.
-   * @param {string} name - Argument name
-   * @param {ExtensionType} [extType] - Extension type
-   * @param {string} [extName] - Extension name
-   * @returns {string} Schema ID
-   */
-  static toSchemaRef(name, extType, extName) {
-    const baseRef = ArgSpec.toSchemaBaseRef(extType, extName);
-    if (extType && extName) {
-      return [`${baseRef}#`, PROPERTIES, name].join('/');
-    }
-    return [`${baseRef}#`, PROPERTIES, SERVER_PROP_NAME, PROPERTIES, name].join('/');
-  }
-
-  /**
-   * Return the schema ID for an extension or the base schema ID.
-   * @param {ExtensionType} [extType] - Extension type
-   * @param {string} [extName] - Extension name
-   */
-  static toSchemaBaseRef(extType, extName) {
-    if (extType && extName) {
-      return `${extType}-${ArgSpec.toNormalizedExtName(extName)}.json`;
-    }
-    return APPIUM_CONFIG_SCHEMA_ID;
-  }
-
-  /**
-   * Return the unique ID for the argument given the parameters.
-   * @param {string} name - Argument name
-   * @param {ExtensionType} [extType] - Extension type
-   * @param {string} [extName] - Extension name
-   * @returns {string} Unique ID
-   */
-  static toArg(name, extType, extName) {
-    const properName = _.kebabCase(name.replace(/^--?/, ''));
-    if (extType && extName) {
-      return [extType, _.kebabCase(extName), properName].join('-');
-    }
-    return properName;
-  }
-
-  /**
-   * Normalizes a raw extension name (not including the type).
-   * @param {string} extName - Extension name
-   * @returns {string} Normalized extension name
-   */
-  static toNormalizedExtName(extName) {
-    return _.kebabCase(extName);
-  }
-
-  /**
-   * When given the root ID of a schema for an extension (`<extType>-<normalizedExtName>.json`) Returns an object containing the extension type and the _normalized_ extension name.
-   * @param {string} schemaId - Root schema ID
-   * @returns { {extType?: ExtensionType, normalizedExtName?: string} }
-   */
-  static extensionInfoFromRootSchemaId(schemaId) {
-    const matches = schemaId.match(SCHEMA_ID_REGEXP);
-    if (matches?.groups) {
-      const {extType, normalizedExtName} =
-        /** @type { {extType: ExtensionType, normalizedExtName: string} } */ (matches.groups);
-      return {extType, normalizedExtName};
-    }
-    return {};
-  }
-
-  /**
-   * Creates an `ArgSpec`
-   *
-   * @param {string} name - The canonical name of the argument. Corresponds to a key in a schema's
-   * `properties` property.
-   * @template D
-   * @param {ArgSpecOptions<D>} [opts] - Options
-   * @returns {Readonly<ArgSpec>}
-   */
-  static create(name, opts) {
-    return Object.freeze(new ArgSpec(name, opts));
-  }
-
-  /**
-   * String representation, useful for debugging
-   * @returns {string}
-   */
-  /* istanbul ignore next */
-  toString() {
-    let str = `[ArgSpec] ${this.name} (${this.ref})`;
-    if (this.extType && this.extName) {
-      str += ` (ext: ${this.extType}/${this.extName})`;
-    }
-    return str;
-  }
-}
-
-/**
- * Options for {@link ArgSpec.create}
- * @template D
- * @typedef ArgSpecOptions
- * @property {string} [extName]
- * @property {ExtensionType} [extType]
- * @property {string} [dest]
- * @property {D} [defaultValue]
- */
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- */