appium 3.3.0 → 3.3.1

package/lib/config.ts

@@ -1,377 +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';
-import type {BuildInfo, Args} from 'appium/types';
-import type {ReadConfigFileResult} from './config-file';
-
-export const APPIUM_VER = npmPackage.version;
-const ENGINES = npmPackage.engines as Record<string, string>;
-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';
-
-const BUILD_INFO: BuildInfo = {
-  version: APPIUM_VER,
-};
-
-/**
- * Update mutable build info metadata from local git or GitHub fallback.
- */
-export async function updateBuildInfo(useGithubApiFallback = false): Promise<void> {
-  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;
-  }
-}
-
-/**
- * Prints server debug info to stdout.
- */
-export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}: DebugInfoInput): Promise<void> {
-  const getNpmVersion = async (): Promise<string> => {
-    const {stdout} = await npm.exec('--version', [], {cwd: process.cwd()});
-    return _.trim(stdout);
-  };
-  const findNpmLocation = async (): Promise<string> =>
-    await fs.which(system.isWindows() ? 'npm.cmd' : 'npm');
-
-  const [npmVersion, npmLocation] = await B.all([
-    ...[getNpmVersion, findNpmLocation].map((f) => getSafeResult(f, 'unknown')),
-    updateBuildInfo() as Promise<unknown>,
-  ]);
-
-  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));
-}
-
-/**
- * Returns the current git commit SHA for this Appium checkout.
- *
- * Attempts to read from local git first; when unavailable and fallback is enabled,
- * queries the GitHub API for the tag matching the current Appium version.
- */
-export async function getGitRev(useGithubApiFallback = false): Promise<string | null> {
-  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;
-}
-
-/**
- * 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.
- */
-export function getBuildInfo(): BuildInfo {
-  return BUILD_INFO;
-}
-
-/**
- * @throws {Error} If Node version is outside of the supported range
- */
-export function checkNodeOk(): void {
-  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}`);
-  }
-}
-
-/**
- * Prints the current build info JSON to stdout.
- *
- * This updates build metadata first (using GitHub fallback) and then logs the
- * resulting {@link BuildInfo} object.
- */
-export async function showBuildInfo(): Promise<void> {
-  await updateBuildInfo(true);
-  console.log(JSON.stringify(getBuildInfo()));
-}
-
-/**
- * Returns k/v pairs of server arguments which are _not_ the defaults.
- */
-export function getNonDefaultServerArgs(parsedArgs: Args): Args {
-  /**
-   * Flattens parsed args into a single level object for comparison with
-   * flattened defaults across server args and extension args.
-   */
-  const flatten = (args: Args): Record<string, FlattenedArg> => {
-    const argSpecs = getAllArgSpecs();
-    const flattened = _.reduce(
-      [...argSpecs.values()],
-      (acc: Record<string, FlattenedArg>, argSpec: {dest: string}) => {
-        if (_.has(args, argSpec.dest)) {
-          acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
-        }
-        return acc;
-      },
-      {}
-    );
-
-    return flattened;
-  };
-
-  const args = flatten(parsedArgs);
-
-  // hopefully these function names are descriptive enough
-  const typesDiffer = (dest: string): boolean =>
-    typeof args[dest].value !== typeof defaultsFromSchema[dest];
-
-  const defaultValueIsArray = (dest: string): boolean => _.isArray(defaultsFromSchema[dest]);
-
-  const argsValueIsArray = (dest: string): boolean => _.isArray(args[dest].value);
-
-  const arraysDiffer = (dest: string): boolean =>
-    _.gt(_.size(_.difference(args[dest].value as any[], defaultsFromSchema[dest] as any[])), 0);
-
-  const valuesDiffer = (dest: string): boolean => args[dest].value !== defaultsFromSchema[dest];
-
-  const defaultIsDefined = (dest: string): boolean => !_.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
-   */
-  const isNotDefault = _.overEvery([
-    defaultIsDefined,
-    _.overSome([
-      typesDiffer,
-      _.overEvery([defaultValueIsArray, argValueNotArrayOrArraysDiffer]),
-      defaultValueNotArrayAndValuesDiffer,
-    ]),
-  ]);
-
-  const defaultsFromSchema = getDefaultsForSchema(true) as Record<string, unknown>;
-
-  return _.reduce(
-    _.pickBy(args, (_v, key) => isNotDefault(key)),
-    // explodes the flattened object back into nested one
-    (acc: Args, {value, argSpec}: FlattenedArg) => _.set(acc, argSpec.dest, value),
-    {} as Args
-  );
-}
-
-/**
- * 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.
- */
-export function showConfig(
-  nonDefaultPreConfigParsedArgs: Partial<Args>,
-  configResult: ReadConfigFileResult,
-  defaults: Partial<Args>,
-  parsedArgs: Args
-): void {
-  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));
-}
-
-/**
- * Ensures a directory exists and (optionally) is writeable.
- *
- * If the directory does not exist, this attempts to create it recursively.
- *
- * @throws {Error}
- */
-export async function requireDir(
-  root: string,
-  requireWriteable = true,
-  displayName = 'folder path'
-): Promise<void> {
-  let stat;
-  try {
-    stat = await fs.stat(root);
-  } catch (e) {
-    if ((e as NodeJS.ErrnoException).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}'`
-      );
-    }
-  }
-}
-
-function getNodeVersion(): semver.SemVer {
-  return semver.coerce(process.version) as semver.SemVer;
-}
-
-const getFullGitPath = _.memoize(async function getFullGitPath(): Promise<string | null> {
-  try {
-    return await fs.which(GIT_BINARY);
-  } catch {
-    return null;
-  }
-});
-
-async function getGitTimestamp(commitSha: string, useGithubApiFallback = false): Promise<string | null> {
-  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;
-}
-
-/**
- * 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: unknown, key: string) =>
-    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
-);
-
-/**
- * Calculates the result of the given function and return its value
- * or the default one if there was an exception.
- */
-async function getSafeResult<T>(f: () => Promise<T>, defaultValue: T): Promise<T> {
-  try {
-    return await f();
-  } catch {
-    return defaultValue;
-  }
-}
-
-interface DebugInfoInput {
-  driverConfig: {installedExtensions: unknown};
-  pluginConfig: {installedExtensions: unknown};
-  appiumHome: string;
-}
-
-interface FlattenedArg {
-  value: unknown;
-  argSpec: {dest: string};
-}

package/lib/extension/driver-config.js

@@ -1,245 +0,0 @@
-import _ from 'lodash';
-import {DRIVER_TYPE} from '../constants';
-import log from '../logger';
-import {ExtensionConfig} from './extension-config';
-
-/**
- * @extends {ExtensionConfig<DriverType>}
- */
-export class DriverConfig extends ExtensionConfig {
-  /**
-   * A set of unique automation names used by drivers.
-   * @type {Set<string>}
-   */
-  knownAutomationNames;
-
-  /**
-   * A mapping of {@link Manifest} instances to {@link DriverConfig} instances.
-   *
-   * `Manifest` and `ExtensionConfig` have a one-to-many relationship; each `Manifest` should be associated with a `DriverConfig` and a `PluginConfig`; no more, no less.
-   *
-   * This variable tracks the `Manifest`-to-`DriverConfig` portion.
-   *
-   * @type {WeakMap<Manifest,DriverConfig>}
-   * @private
-   */
-  static _instances = new WeakMap();
-
-  /**
-   * Call {@link DriverConfig.create} instead.
-   * @private
-   * @param {import('./manifest').Manifest} manifest - Manifest instance
-   */
-  constructor(manifest) {
-    super(DRIVER_TYPE, manifest);
-
-    this.knownAutomationNames = new Set();
-  }
-
-  /**
-   * Creates a new {@link DriverConfig} instance for a {@link Manifest} instance.
-   *
-   * @param {Manifest} manifest
-   * @throws If `manifest` already associated with a `DriverConfig`
-   * @returns {DriverConfig}
-   */
-  static create(manifest) {
-    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;
-  }
-
-  /**
-   * Returns a DriverConfig associated with a Manifest
-   * @param {Manifest} manifest
-   * @returns {DriverConfig|undefined}
-   */
-  static getInstance(manifest) {
-    return DriverConfig._instances.get(manifest);
-  }
-
-  /**
-   * Checks extensions for problems
-   */
-  async validate() {
-    this.knownAutomationNames.clear();
-    return await super._validate(this.manifest.getExtensionData(DRIVER_TYPE));
-  }
-
-  /**
-   * @param {ExtManifest<DriverType>} extData
-   * @returns {import('./extension-config').ExtManifestProblem[]}
-   */
-  getConfigProblems(extData) {
-    const problems = [];
-    const {platformNames, automationName} = extData;
-
-    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)) {
-      problems.push({
-        err: 'Multiple drivers claim support for the same automationName',
-        val: automationName,
-      });
-    }
-
-    // should we retain the name at the end of this function, once we've checked there are no problems?
-    this.knownAutomationNames.add(automationName);
-
-    return problems;
-  }
-
-  /**
-   * @param {ExtName<DriverType>} driverName
-   * @param {ExtManifest<DriverType>} extData
-   * @returns {string}
-   */
-  extensionDesc(driverName, {version, automationName}) {
-    return `${driverName}@${version} (automationName '${automationName}')`;
-  }
-
-  /**
-   * Given capabilities, find a matching driver within the config. Load its class and return it along with version and driver name.
-   * @template {import('@appium/types').StringRecord} C
-   * @param {C} caps
-   * @returns {Promise<MatchedDriver>}
-   */
-  async findMatchingDriver({automationName, platformName}) {
-    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);
-      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) {
-      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);
-    }
-  }
-
-  /**
-   * Given an automation name and platform name, find a suitable driver and return its extension data.
-   * @param {string} matchAutomationName
-   * @param {string} matchPlatformName
-   * @returns {ExtMetadata<DriverType> & import('appium/types').InternalMetadata & import('appium/types').CommonExtMetadata}
-   */
-  _getDriverBySupport(matchAutomationName, matchPlatformName) {
-    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(_.toLower),
-        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`);
-  }
-}
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtMetadata<T>} ExtMetadata
- */
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtManifest<T>} ExtManifest
- */
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- * @typedef {import('appium/types').ManifestData} ManifestData
- * @typedef {import('@appium/types').DriverType} DriverType
- * @typedef {import('./manifest').Manifest} Manifest
- */
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtRecord<T>} ExtRecord
- */
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtName<T>} ExtName
- */
-
-/**
- * Return value of {@linkcode DriverConfig.findMatchingDriver}
- * @typedef MatchedDriver
- * @property {import('@appium/types').DriverClass} driver
- * @property {string} version
- * @property {string} driverName
- */