appium 3.2.2 → 3.3.1

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/config.js

@@ -1,389 +0,0 @@
-/* eslint-disable no-console */
-import _ from 'lodash';
-import {system, fs, npm} from '@appium/support';
-import axios from 'axios';
-import {exec} from 'teen_process';
-import * as semver from 'semver';
-import os from 'node:os';
-import {npmPackage} from './utils';
-import B from 'bluebird';
-import {getDefaultsForSchema, getAllArgSpecs} from './schema/schema';
-
-export const APPIUM_VER = npmPackage.version;
-const ENGINES = /** @type {Record<string,string>} */ (npmPackage.engines);
-const MIN_NODE_VERSION = ENGINES.node;
-export const rootDir = fs.findRoot(__dirname);
-
-const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
-const GITHUB_API = 'https://api.github.com/repos/appium/appium';
-
-/**
- * @type {import('appium/types').BuildInfo}
- */
-const BUILD_INFO = {
-  version: APPIUM_VER,
-};
-
-function getNodeVersion() {
-  return /** @type {import('semver').SemVer} */ (semver.coerce(process.version));
-}
-
-/**
- * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<void>}
- */
-export async function updateBuildInfo(useGithubApiFallback = false) {
-  const sha = await getGitRev(useGithubApiFallback);
-  if (!sha) {
-    return;
-  }
-  BUILD_INFO['git-sha'] = sha;
-  const buildTimestamp = await getGitTimestamp(sha, useGithubApiFallback);
-  if (buildTimestamp) {
-    BUILD_INFO.built = buildTimestamp;
-  }
-}
-
-/** @type {() => Promise<string?>} */
-const getFullGitPath = _.memoize(async function getFullGitPath() {
-  try {
-    return await fs.which(GIT_BINARY);
-  } catch {
-    return null;
-  }
-});
-
-/**
- * Prints server debug into into the console.
- *
- * @param {{
- * driverConfig: import('./extension/driver-config').DriverConfig,
- * pluginConfig: import('./extension/plugin-config').PluginConfig,
- * appiumHome: string
- * }} info
- * @returns {Promise<void>}
- */
-export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}) {
-  const getNpmVersion = async () => {
-    const {stdout} = await npm.exec('--version', [], {cwd: process.cwd()});
-    return _.trim(stdout);
-  };
-  const findNpmLocation = async () => await fs.which(system.isWindows() ? 'npm.cmd' : 'npm');
-  const [npmVersion, npmLocation] = await B.all([
-    ...([getNpmVersion, findNpmLocation].map((f) => getSafeResult(f, 'unknown'))),
-    /** @type {any} */ (updateBuildInfo()),
-  ]);
-  const debugInfo = {
-    os: {
-      platform: os.platform(),
-      release: os.release(),
-      arch: os.arch(),
-      homedir: os.homedir(),
-      username: os.userInfo().username,
-    },
-    node: {
-      version: process.version,
-      arch: process.arch,
-      cwd: process.cwd(),
-      argv: process.argv,
-      env: process.env,
-      npm: {
-        location: npmLocation,
-        version: npmVersion,
-      },
-    },
-    appium: {
-      location: rootDir,
-      homedir: appiumHome,
-      build: getBuildInfo(),
-      drivers: driverConfig.installedExtensions,
-      plugins: pluginConfig.installedExtensions,
-    },
-  };
-  console.log(JSON.stringify(debugInfo, null, 2));
-}
-
-/**
- * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<string?>}
- */
-export async function getGitRev(useGithubApiFallback = false) {
-  const fullGitPath = await getFullGitPath();
-  if (fullGitPath) {
-    try {
-      const {stdout} = await exec(fullGitPath, ['rev-parse', 'HEAD'], {
-        cwd: __dirname,
-      });
-      return stdout.trim();
-    } catch {}
-  }
-
-  if (!useGithubApiFallback) {
-    return null;
-  }
-
-  // If the package folder is not a valid git repository
-  // then fetch the corresponding tag info from GitHub
-  try {
-    return (
-      await axios.get(`${GITHUB_API}/git/refs/tags/appium@${APPIUM_VER}`, {
-        headers: {
-          'User-Agent': `Appium ${APPIUM_VER}`,
-        },
-      })
-    ).data?.object?.sha;
-  } catch {}
-  return null;
-}
-
-/**
- * @param {string} commitSha
- * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<string?>}
- */
-async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
-  const fullGitPath = await getFullGitPath();
-  if (fullGitPath) {
-    try {
-      const {stdout} = await exec(fullGitPath, ['show', '-s', '--format=%ci', commitSha], {
-        cwd: __dirname,
-      });
-      return stdout.trim();
-    } catch {}
-  }
-
-  if (!useGithubApiFallback) {
-    return null;
-  }
-
-  try {
-    return (
-      await axios.get(`${GITHUB_API}/git/tags/${commitSha}`, {
-        headers: {
-          'User-Agent': `Appium ${APPIUM_VER}`,
-        },
-      })
-    ).data?.tagger?.date;
-  } catch {}
-  return null;
-}
-
-/**
- * Mutable object containing Appium build information. By default it
- * only contains the Appium version, but is updated with the build timestamp
- * and git commit hash asynchronously as soon as `updateBuildInfo` is called
- * and succeeds.
- * @returns {import('appium/types').BuildInfo}
- */
-export function getBuildInfo() {
-  return BUILD_INFO;
-}
-
-/**
- * @returns {void}
- * @throws {Error} If Node version is outside of the supported range
- */
-export function checkNodeOk() {
-  const version = getNodeVersion();
-  if (!semver.satisfies(version, MIN_NODE_VERSION)) {
-    throw new Error(
-      `Node version must be at least ${MIN_NODE_VERSION}; current is ${version.version}`
-    );
-  }
-}
-
-export async function showBuildInfo() {
-  await updateBuildInfo(true);
-  console.log(JSON.stringify(getBuildInfo()));
-}
-
-/**
- * Returns k/v pairs of server arguments which are _not_ the defaults.
- * @param {Args} parsedArgs
- * @returns {Args}
- */
-export function getNonDefaultServerArgs(parsedArgs) {
-  /**
-   * Flattens parsed args into a single level object for comparison with
-   * flattened defaults across server args and extension args.
-   * @param {Args} args
-   * @returns {Record<string, { value: any, argSpec: ArgSpec }>}
-   */
-  const flatten = (args) => {
-    const argSpecs = getAllArgSpecs();
-    const flattened = _.reduce(
-      [...argSpecs.values()],
-      (acc, argSpec) => {
-        if (_.has(args, argSpec.dest)) {
-          acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
-        }
-        return acc;
-      },
-      /** @type {Record<string, { value: any, argSpec: ArgSpec }>} */ ({})
-    );
-
-    return flattened;
-  };
-
-  const args = flatten(parsedArgs);
-
-  // hopefully these function names are descriptive enough
-  const typesDiffer = /** @param {string} dest */ (dest) =>
-    typeof args[dest].value !== typeof defaultsFromSchema[dest];
-
-  const defaultValueIsArray = /** @param {string} dest */ (dest) =>
-    _.isArray(defaultsFromSchema[dest]);
-
-  const argsValueIsArray = /** @param {string} dest */ (dest) => _.isArray(args[dest].value);
-
-  const arraysDiffer = /** @param {string} dest */ (dest) =>
-    _.gt(_.size(_.difference(args[dest].value, defaultsFromSchema[dest])), 0);
-
-  const valuesDiffer = /** @param {string} dest */ (dest) =>
-    args[dest].value !== defaultsFromSchema[dest];
-
-  const defaultIsDefined = /** @param {string} dest */ (dest) =>
-    !_.isUndefined(defaultsFromSchema[dest]);
-
-  // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
-
-  const argValueNotArrayOrArraysDiffer = _.overSome([_.negate(argsValueIsArray), arraysDiffer]);
-
-  const defaultValueNotArrayAndValuesDiffer = _.overEvery([
-    _.negate(defaultValueIsArray),
-    valuesDiffer,
-  ]);
-
-  /**
-   * This used to be a hideous conditional, but it's broken up into a hideous function instead.
-   * hopefully this makes things a little more understandable.
-   * - checks if the default value is defined
-   * - if so, and the default is not an array:
-   *   - ensures the types are the same
-   *   - ensures the values are equal
-   * - if so, and the default is an array:
-   *   - ensures the args value is an array
-   *   - ensures the args values do not differ from the default values
-   * @type {(dest: string) => boolean}
-   */
-  const isNotDefault = _.overEvery([
-    defaultIsDefined,
-    _.overSome([
-      typesDiffer,
-      _.overEvery([defaultValueIsArray, argValueNotArrayOrArraysDiffer]),
-      defaultValueNotArrayAndValuesDiffer,
-    ]),
-  ]);
-
-  const defaultsFromSchema = getDefaultsForSchema(true);
-
-  return _.reduce(
-    _.pickBy(args, (__, key) => isNotDefault(key)),
-    // explodes the flattened object back into nested one
-    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value),
-    /** @type {Args} */ ({})
-  );
-}
-
-/**
- * Compacts an object for {@link showConfig}:
- * 1. Removes `subcommand` key/value
- * 2. Removes `undefined` values
- * 3. Removes empty objects (but not `false` values)
- * Does not operate recursively.
- */
-const compactConfig = _.partial(
-  _.omitBy,
-  _,
-  (value, key) =>
-    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
-);
-
-/**
- * Shows a breakdown of the current config after CLI params, config file loaded & defaults applied.
- *
- * The actual shape of `preConfigParsedArgs` and `defaults` does not matter for the purposes of this function,
- * but it's intended to be called with values of type {@link ParsedArgs} and `DefaultValues<true>`, respectively.
- *
- * @param {Partial<ParsedArgs>} nonDefaultPreConfigParsedArgs - Parsed CLI args (or param to `init()`) before config & defaults applied
- * @param {import('./config-file').ReadConfigFileResult} configResult - Result of attempting to load a config file.  _Must_ be normalized
- * @param {Partial<ParsedArgs>} defaults - Configuration defaults from schemas
- * @param {ParsedArgs} parsedArgs - Entire parsed args object
- */
-export function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parsedArgs) {
-  console.log('Appium Configuration\n');
-  console.log('from defaults:\n');
-  console.dir(compactConfig(defaults));
-  if (configResult.config) {
-    console.log(`\nfrom config file at ${configResult.filepath}:\n`);
-    console.dir(compactConfig(configResult.config));
-  } else {
-    console.log(`\n(no configuration file loaded)`);
-  }
-  const compactedNonDefaultPreConfigArgs = compactConfig(nonDefaultPreConfigParsedArgs);
-  if (_.isEmpty(compactedNonDefaultPreConfigArgs)) {
-    console.log(`\n(no CLI parameters provided)`);
-  } else {
-    console.log('\nvia CLI or function call:\n');
-    console.dir(compactedNonDefaultPreConfigArgs);
-  }
-  console.log('\nfinal configuration:\n');
-  console.dir(compactConfig(parsedArgs));
-}
-
-/**
- * @param {string} root
- * @param {boolean} [requireWriteable=true]
- * @param {string} [displayName='folder path']
- * @throws {Error}
- */
-export async function requireDir(root, requireWriteable = true, displayName = 'folder path') {
-  let stat;
-  try {
-    stat = await fs.stat(root);
-  } catch (e) {
-    if (e.code === 'ENOENT') {
-      try {
-        await fs.mkdir(root, {recursive: true});
-        return;
-      } catch {}
-    }
-    throw new Error(`The ${displayName} '${root}' must exist and be a valid directory`);
-  }
-  if (stat && !stat.isDirectory()) {
-    throw new Error(`The ${displayName} '${root}' must be a valid directory`);
-  }
-  if (requireWriteable) {
-    try {
-      await fs.access(root, fs.constants.W_OK);
-    } catch {
-      throw new Error(
-        `The ${displayName} '${root}' must be ` +
-        `writeable for the current user account '${os.userInfo().username}'`
-      );
-    }
-  }
-}
-
-/**
- * Calculates the result of the given function and return its value
- * or the default one if there was an exception.
- *
- * @template T
- * @param {() => Promise<T>} f
- * @param {T} defaultValue
- * @returns {Promise<T>}
- */
-async function getSafeResult(f, defaultValue) {
-  try {
-    return await f();
-  } catch {
-    return defaultValue;
-  }
-}
-
-/**
- * @typedef {import('appium/types').ParsedArgs} ParsedArgs
- * @typedef {import('appium/types').Args} Args
- * @typedef {import('./schema/arg-spec').ArgSpec} ArgSpec
- */