appium 2.0.0-beta.6 → 2.0.0-beta.61

package/build/lib/constants.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LONG_STACKTRACE_LIMIT = exports.CURRENT_SCHEMA_REV = exports.EXT_SUBCOMMAND_RUN = exports.EXT_SUBCOMMAND_UPDATE = exports.EXT_SUBCOMMAND_UNINSTALL = exports.EXT_SUBCOMMAND_INSTALL = exports.EXT_SUBCOMMAND_LIST = exports.PKG_HASHFILE_RELATIVE_PATH = exports.CACHE_DIR_RELATIVE_PATH = exports.KNOWN_DRIVERS = exports.KNOWN_PLUGINS = exports.USE_ALL_PLUGINS = exports.SERVER_SUBCOMMAND = exports.PLUGIN_TYPE = exports.DRIVER_TYPE = void 0;
+const path_1 = __importDefault(require("path"));
+/**
+ * The name of the extension type for drivers
+ */
+exports.DRIVER_TYPE = 'driver';
+/**
+ * The name of the extension type for plugins
+ */
+exports.PLUGIN_TYPE = 'plugin';
+/**
+ * The `server` command of the `appium` CLI
+ */
+exports.SERVER_SUBCOMMAND = 'server';
+/**
+ * The value of `--use-plugins` if _all_ plugins should be loaded
+ */
+exports.USE_ALL_PLUGINS = 'all';
+// This is a map of plugin names to npm packages representing those plugins.
+// The plugins in this list will be available to the CLI so users can just
+// type 'appium plugin install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized plugins.
+exports.KNOWN_PLUGINS = Object.freeze(
+/** @type {const} */ ({
+    images: '@appium/images-plugin',
+    'execute-driver': '@appium/execute-driver-plugin',
+    'relaxed-caps': '@appium/relaxed-caps-plugin',
+    'universal-xml': '@appium/universal-xml-plugin',
+}));
+// This is a map of driver names to npm packages representing those drivers.
+// The drivers in this list will be available to the CLI so users can just
+// type 'appium driver install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized drivers.
+exports.KNOWN_DRIVERS = Object.freeze(
+/** @type {const} */ ({
+    uiautomator2: 'appium-uiautomator2-driver',
+    xcuitest: 'appium-xcuitest-driver',
+    mac2: 'appium-mac2-driver',
+    espresso: 'appium-espresso-driver',
+    safari: 'appium-safari-driver',
+    gecko: 'appium-geckodriver',
+    chromium: 'appium-chromium-driver',
+}));
+/**
+ * Relative path to directory containing any Appium internal files
+ */
+exports.CACHE_DIR_RELATIVE_PATH = path_1.default.join('node_modules', '.cache', 'appium');
+/**
+ * Relative path to hashfile (from `APPIUM_HOME`) of consuming project's `package.json` (if it exists)
+ */
+exports.PKG_HASHFILE_RELATIVE_PATH = path_1.default.join(exports.CACHE_DIR_RELATIVE_PATH, 'package.hash');
+exports.EXT_SUBCOMMAND_LIST = 'list';
+exports.EXT_SUBCOMMAND_INSTALL = 'install';
+exports.EXT_SUBCOMMAND_UNINSTALL = 'uninstall';
+exports.EXT_SUBCOMMAND_UPDATE = 'update';
+exports.EXT_SUBCOMMAND_RUN = 'run';
+/**
+ * Current revision of the manifest (`extensions.yaml`) schema
+ */
+exports.CURRENT_SCHEMA_REV = 4;
+/**
+ * The default number of stack frames to show in a "long" stack trace, when enabled via `--long-stacktrace`
+ * @remarks This value may be increased in the future.
+ * @privateRemarks A value like `Infinity` may provide to have deleterious effects on
+ * memory usage, perf, and/or log output, and higher limits may be difficult to scan.
+ */
+exports.LONG_STACKTRACE_LIMIT = 100;
+//# sourceMappingURL=constants.js.map

package/build/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../lib/constants.js"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AAExB;;GAEG;AACU,QAAA,WAAW,GAAG,QAAQ,CAAC;AAEpC;;GAEG;AACU,QAAA,WAAW,GAAG,QAAQ,CAAC;AAEpC;;GAEG;AACU,QAAA,iBAAiB,GAAG,QAAQ,CAAC;AAE1C;;GAEG;AACU,QAAA,eAAe,GAAG,KAAK,CAAC;AAErC,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,kEAAkE;AACrD,QAAA,aAAa,GAAG,MAAM,CAAC,MAAM;AACxC,oBAAoB,CAAC,CAAC;IACpB,MAAM,EAAE,uBAAuB;IAC/B,gBAAgB,EAAE,+BAA+B;IACjD,cAAc,EAAE,6BAA6B;IAC7C,eAAe,EAAE,8BAA8B;CAChD,CAAC,CACH,CAAC;AAEF,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,kEAAkE;AACrD,QAAA,aAAa,GAAG,MAAM,CAAC,MAAM;AACxC,oBAAoB,CAAC,CAAC;IACpB,YAAY,EAAE,4BAA4B;IAC1C,QAAQ,EAAE,wBAAwB;IAClC,IAAI,EAAE,oBAAoB;IAC1B,QAAQ,EAAE,wBAAwB;IAClC,MAAM,EAAE,sBAAsB;IAC9B,KAAK,EAAE,oBAAoB;IAC3B,QAAQ,EAAE,wBAAwB;CACnC,CAAC,CACH,CAAC;AAEF;;GAEG;AACU,QAAA,uBAAuB,GAAG,cAAI,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErF;;GAEG;AACU,QAAA,0BAA0B,GAAG,cAAI,CAAC,IAAI,CAAC,+BAAuB,EAAE,cAAc,CAAC,CAAC;AAEhF,QAAA,mBAAmB,GAAG,MAAM,CAAC;AAC7B,QAAA,sBAAsB,GAAG,SAAS,CAAC;AACnC,QAAA,wBAAwB,GAAG,WAAW,CAAC;AACvC,QAAA,qBAAqB,GAAG,QAAQ,CAAC;AACjC,QAAA,kBAAkB,GAAG,KAAK,CAAC;AAExC;;GAEG;AACU,QAAA,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG,GAAG,CAAC"}

package/build/lib/extension/driver-config.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @extends {ExtensionConfig<DriverType>}
+ */
+export class DriverConfig extends ExtensionConfig<"driver"> {
+    /**
+     * 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
+     */
+    private static _instances;
+    /**
+     * 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: Manifest): DriverConfig;
+    /**
+     * Returns a DriverConfig associated with a Manifest
+     * @param {Manifest} manifest
+     * @returns {DriverConfig|undefined}
+     */
+    static getInstance(manifest: Manifest): DriverConfig | undefined;
+    /**
+     * Call {@link DriverConfig.create} instead.
+     * @private
+     * @param {import('./manifest').Manifest} manifest - Manifest instance
+     */
+    private constructor();
+    /**
+     * A set of unique automation names used by drivers.
+     * @type {Set<string>}
+     */
+    knownAutomationNames: Set<string>;
+    /**
+     * Checks extensions for problems
+     */
+    validate(): Promise<import("./extension-config").ExtRecord<"driver">>;
+    /**
+     * @param {ExtManifest<DriverType>} extData
+     * @returns {import('./extension-config').ExtManifestProblem[]}
+     */
+    getConfigProblems(extData: ExtManifest<DriverType>): import('./extension-config').ExtManifestProblem[];
+    /**
+     * 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 {MatchedDriver}
+     */
+    findMatchingDriver<C extends import("@appium/types").StringRecord<any>>({ automationName, platformName }: C): MatchedDriver;
+    /**
+     * 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: string, matchPlatformName: string): ExtMetadata<DriverType> & import('appium/types').InternalMetadata & import('appium/types').CommonExtMetadata;
+}
+export type ExtMetadata<T extends import("@appium/types").ExtensionType> = import('appium/types').ExtMetadata<T>;
+export type ExtManifest<T extends import("@appium/types").ExtensionType> = import('appium/types').ExtManifest<T>;
+export type ExtensionType = import('@appium/types').ExtensionType;
+export type ManifestData = import('appium/types').ManifestData;
+export type DriverType = import('@appium/types').DriverType;
+export type Manifest = import('./manifest').Manifest;
+export type ExtRecord<T extends import("@appium/types").ExtensionType> = import('appium/types').ExtRecord<T>;
+export type ExtName<T extends import("@appium/types").ExtensionType> = import('appium/types').ExtName<T>;
+/**
+ * Return value of {@linkcode DriverConfig.findMatchingDriver }
+ */
+export type MatchedDriver = {
+    driver: import('@appium/types').DriverClass;
+    version: string;
+    driverName: string;
+};
+import { ExtensionConfig } from "./extension-config";
+//# sourceMappingURL=driver-config.d.ts.map

package/build/lib/extension/driver-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-config.d.ts","sourceRoot":"","sources":["../../../lib/extension/driver-config.js"],"names":[],"mappings":"AAKA;;GAEG;AACH;IAOE;;;;;;;;;OASG;IACH,0BAAkC;IAalC;;;;;;OAMG;IACH,wBAJW,QAAQ,GAEN,YAAY,CAWxB;IAED;;;;OAIG;IACH,6BAHW,QAAQ,GACN,YAAY,GAAC,SAAS,CAIlC;IApCD;;;;OAIG;IACH,sBAIC;IA3BD;;;OAGG;IACH,sBAFU,IAAI,MAAM,CAAC,CAEA;IAoDrB;;OAEG;IACH,sEAGC;IAED;;;OAGG;IACH,2BAHW,YAAY,UAAU,CAAC,GACrB,OAAO,oBAAoB,EAAE,kBAAkB,EAAE,CA+C7D;IAWD;;;;;OAKG;IACH,8GAFa,aAAa,CAuCzB;IAED;;;;;OAKG;IACH,yCAJW,MAAM,qBACN,MAAM,GACJ,YAAY,UAAU,CAAC,GAAG,OAAO,cAAc,EAAE,gBAAgB,GAAG,OAAO,cAAc,EAAE,iBAAiB,CA4BxH;CACF;2EAIY,OAAO,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;2EAKrC,OAAO,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;4BAIrC,OAAO,eAAe,EAAE,aAAa;2BACrC,OAAO,cAAc,EAAE,YAAY;yBACnC,OAAO,eAAe,EAAE,UAAU;uBAClC,OAAO,YAAY,EAAE,QAAQ;yEAK7B,OAAO,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;uEAKnC,OAAO,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC;;;;;YAMhC,OAAO,eAAe,EAAE,WAAW;aACnC,MAAM;gBACN,MAAM"}

package/build/lib/extension/driver-config.js

@@ -0,0 +1,210 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriverConfig = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const constants_1 = require("../constants");
+const logger_1 = __importDefault(require("../logger"));
+const extension_config_1 = require("./extension-config");
+/**
+ * @extends {ExtensionConfig<DriverType>}
+ */
+class DriverConfig extends extension_config_1.ExtensionConfig {
+    /**
+     * Call {@link DriverConfig.create} instead.
+     * @private
+     * @param {import('./manifest').Manifest} manifest - Manifest instance
+     */
+    constructor(manifest) {
+        super(constants_1.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(constants_1.DRIVER_TYPE));
+    }
+    /**
+     * @param {ExtManifest<DriverType>} extData
+     * @returns {import('./extension-config').ExtManifestProblem[]}
+     */
+    getConfigProblems(extData) {
+        const problems = [];
+        const { platformNames, automationName } = extData;
+        if (!lodash_1.default.isArray(platformNames)) {
+            problems.push({
+                err: 'Missing or incorrect supported platformNames list.',
+                val: platformNames,
+            });
+        }
+        else {
+            if (lodash_1.default.isEmpty(platformNames)) {
+                problems.push({
+                    err: 'Empty platformNames list.',
+                    val: platformNames,
+                });
+            }
+            else {
+                for (const pName of platformNames) {
+                    if (!lodash_1.default.isString(pName)) {
+                        problems.push({
+                            err: 'Incorrectly formatted platformName.',
+                            val: pName,
+                        });
+                    }
+                }
+            }
+        }
+        if (!lodash_1.default.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 {MatchedDriver}
+     */
+    findMatchingDriver({ automationName, platformName }) {
+        if (!lodash_1.default.isString(platformName)) {
+            throw new Error('You must include a platformName capability');
+        }
+        if (!lodash_1.default.isString(automationName)) {
+            throw new Error('You must include an automationName capability');
+        }
+        logger_1.default.info(`Attempting to find matching driver for automationName ` +
+            `'${automationName}' and platformName '${platformName}'`);
+        try {
+            const { driverName, mainClass, version } = this._getDriverBySupport(automationName, platformName);
+            logger_1.default.info(`The '${driverName}' driver was installed and matched caps.`);
+            logger_1.default.info(`Will require it at ${this.getInstallPath(driverName)}`);
+            const driver = this.require(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 lodash_1.default.toPairs(drivers)) {
+            const { automationName, platformNames } = driverData;
+            const aNameMatches = automationName.toLowerCase() === matchAutomationName.toLowerCase();
+            const pNameMatches = lodash_1.default.includes(platformNames.map(lodash_1.default.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`);
+    }
+}
+exports.DriverConfig = DriverConfig;
+/**
+ * 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
+ */
+DriverConfig._instances = new WeakMap();
+/**
+ * @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
+ */
+//# sourceMappingURL=driver-config.js.map

package/build/lib/extension/driver-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-config.js","sourceRoot":"","sources":["../../../lib/extension/driver-config.js"],"names":[],"mappings":"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"}

package/build/lib/extension/extension-config.d.ts

@@ -0,0 +1,270 @@
+/**
+ * "npm" install type
+ * Used when extension was installed by npm package name
+ * @remarks _All_ extensions are installed _by_ `npm`, but only this one means the package name was
+ * used to specify it
+ */
+export const INSTALL_TYPE_NPM: "npm";
+/**
+ * "local" install type
+ * Used when extension was installed from a local path
+ */
+export const INSTALL_TYPE_LOCAL: "local";
+/**
+ * "github" install type
+ * Used when extension was installed via GitHub URL
+ */
+export const INSTALL_TYPE_GITHUB: "github";
+/**
+ * "git" install type
+ * Used when extensions was installed via Git URL
+ */
+export const INSTALL_TYPE_GIT: "git";
+/**
+ * "dev" install type
+ * Used when automatically detected as a working copy
+ */
+export const INSTALL_TYPE_DEV: "dev";
+/** @type {Set<InstallType>} */
+export const INSTALL_TYPES: Set<InstallType>;
+/**
+ * This class is abstract. It should not be instantiated directly.
+ *
+ * Subclasses should provide the generic parameter to implement.
+ * @template {ExtensionType} ExtType
+ */
+export class ExtensionConfig<ExtType extends import("@appium/types").ExtensionType> {
+    /**
+     * Intended to be called by corresponding instance methods of subclass.
+     * @private
+     * @template {ExtensionType} ExtType
+     * @param {string} appiumHome
+     * @param {ExtType} extType
+     * @param {ExtName<ExtType>} extName - Extension name (unique to its type)
+     * @param {ExtManifestWithSchema<ExtType>} extManifest - Extension config
+     * @returns {import('ajv').SchemaObject|undefined}
+     */
+    private static _readExtensionSchema;
+    /**
+     * Returns `true` if a specific {@link ExtManifest} object has a `schema` prop.
+     * The {@link ExtManifest} object becomes a {@link ExtManifestWithSchema} object.
+     * @template {ExtensionType} ExtType
+     * @param {ExtManifest<ExtType>} extManifest
+     * @returns {extManifest is ExtManifestWithSchema<ExtType>}
+     */
+    static extDataHasSchema<ExtType_1 extends import("@appium/types").ExtensionType>(extManifest: ExtManifest<ExtType_1>): extManifest is ExtManifestWithSchema<ExtType_1>;
+    /**
+     * @protected
+     * @param {ExtType} extensionType - Type of extension
+     * @param {Manifest} manifest - `Manifest` instance
+     */
+    protected constructor();
+    /**
+     * The type of extension this class is responsible for.
+     * @type {ExtType}
+     */
+    extensionType: ExtType;
+    /**
+     * Manifest data for the extensions of this type.
+     *
+     * This data should _not_ be written to by anything but {@linkcode Manifest}.
+     * @type {Readonly<ExtRecord<ExtType>>}
+     */
+    installedExtensions: Readonly<ExtRecord<ExtType>>;
+    /** @type {import('@appium/types').AppiumLogger} */
+    log: import('@appium/types').AppiumLogger;
+    /** @type {Manifest} */
+    manifest: Manifest;
+    get manifestPath(): string;
+    get appiumHome(): string;
+    /**
+     * Returns a list of errors for a given extension.
+     *
+     * @param {ExtName<ExtType>} extName
+     * @param {ExtManifest<ExtType>} extManifest
+     * @returns {ExtManifestProblem[]}
+     */
+    getProblems(extName: ExtName<ExtType>, extManifest: ExtManifest<ExtType>): ExtManifestProblem[];
+    /**
+     * Returns a list of warnings for a given extension.
+     *
+     * @param {ExtName<ExtType>} extName
+     * @param {ExtManifest<ExtType>} extManifest
+     * @returns {Promise<string[]>}
+     */
+    getWarnings(extName: ExtName<ExtType>, extManifest: ExtManifest<ExtType>): Promise<string[]>;
+    /**
+     * Returns a list of extension-type-specific issues. To be implemented by subclasses.
+     * @abstract
+     * @param {ExtManifest<ExtType>} extManifest
+     * @param {ExtName<ExtType>} extName
+     * @returns {Promise<string[]>}
+     */
+    getConfigWarnings(extManifest: ExtManifest<ExtType>, extName: ExtName<ExtType>): Promise<string[]>;
+    /**
+     *
+     * @param {Map<ExtName<ExtType>,ExtManifestProblem[]>} [errorMap]
+     * @param {Map<ExtName<ExtType>,string[]>} [warningMap]
+     */
+    getValidationResultSummaries(errorMap?: Map<string, ExtManifestProblem[]> | undefined, warningMap?: Map<string, string[]> | undefined): {
+        errorSummaries: string[];
+        warningSummaries: string[];
+    };
+    /**
+     * Checks extensions for problems.  To be called by subclasses' `validate` method.
+     *
+     * Errors and warnings will be displayed to the user.
+     *
+     * This method mutates `exts`.
+     *
+     * @protected
+     * @param {ExtRecord<ExtType>} exts - Lookup of extension names to {@linkcode ExtManifest} objects
+     * @returns {Promise<ExtRecord<ExtType>>} The same lookup, but picking only error-free extensions
+     */
+    protected _validate(exts: ExtRecord<ExtType>): Promise<ExtRecord<ExtType>>;
+    /**
+     * Retrieves listing data for extensions via command class.
+     *
+     * This is an expensive operation, so the result is cached.  Currently, there is no
+     * use case for invalidating the cache.
+     * @protected
+     * @returns {Promise<import('../cli/extension-command').ExtensionList<ExtType>>}
+     */
+    protected getListData(): Promise<import('../cli/extension-command').ExtensionList<ExtType>>;
+    /**
+     * Returns a list of warnings for a particular extension.
+     *
+     * By definition, a non-empty list of warnings does _not_ imply the extension cannot be loaded,
+     * but it may not work as expected or otherwise throw an exception at runtime.
+     *
+     * @param {ExtManifest<ExtType>} extManifest
+     * @param {ExtName<ExtType>} extName
+     * @returns {Promise<string[]>}
+     */
+    getGenericConfigWarnings(extManifest: ExtManifest<ExtType>, extName: ExtName<ExtType>): Promise<string[]>;
+    /**
+     * Returns list of unrecoverable errors (if any) for the given extension _if_ it has a `schema` property.
+     *
+     * @param {ExtManifest<ExtType>} extManifest - Extension data (from manifest)
+     * @param {ExtName<ExtType>} extName - Extension name (from manifest)
+     * @returns {ExtManifestProblem[]}
+     */
+    getSchemaProblems(extManifest: ExtManifest<ExtType>, extName: ExtName<ExtType>): ExtManifestProblem[];
+    /**
+     * Return a list of generic unrecoverable errors for the given extension
+     * @param {ExtManifest<ExtType>} extManifest - Extension data (from manifest)
+     * @param {ExtName<ExtType>} extName - Extension name (from manifest)
+     * @returns {ExtManifestProblem[]}
+     */
+    getGenericConfigProblems(extManifest: ExtManifest<ExtType>, extName: ExtName<ExtType>): ExtManifestProblem[];
+    /**
+     * @abstract
+     * @param {ExtManifest<ExtType>} extManifest
+     * @param {ExtName<ExtType>} extName
+     * @returns {ExtManifestProblem[]}
+     */
+    getConfigProblems(extManifest: ExtManifest<ExtType>, extName: ExtName<ExtType>): ExtManifestProblem[];
+    /**
+     * @param {string} extName
+     * @param {ExtManifest<ExtType>} extManifest
+     * @param {ExtensionConfigMutationOpts} opts
+     * @returns {Promise<void>}
+     */
+    addExtension(extName: string, extManifest: ExtManifest<ExtType>, { write }?: ExtensionConfigMutationOpts): Promise<void>;
+    /**
+     * @param {ExtName<ExtType>} extName
+     * @param {ExtManifest<ExtType>} extManifest
+     * @param {ExtensionConfigMutationOpts} opts
+     * @returns {Promise<void>}
+     */
+    updateExtension(extName: ExtName<ExtType>, extManifest: ExtManifest<ExtType>, { write }?: ExtensionConfigMutationOpts): Promise<void>;
+    /**
+     * Remove an extension from the list of installed extensions, and optionally avoid a write to the manifest file.
+     *
+     * @param {ExtName<ExtType>} extName
+     * @param {ExtensionConfigMutationOpts} opts
+     * @returns {Promise<void>}
+     */
+    removeExtension(extName: ExtName<ExtType>, { write }?: ExtensionConfigMutationOpts): Promise<void>;
+    /**
+     * @param {ExtName<ExtType>[]} [activeNames]
+     * @returns {void}
+     */
+    print(activeNames?: string[] | undefined): void;
+    /**
+     * Returns a string describing the extension. Subclasses must implement.
+     * @param {ExtName<ExtType>} extName - Extension name
+     * @param {ExtManifest<ExtType>} extManifest - Extension data
+     * @returns {string}
+     * @abstract
+     */
+    extensionDesc(extName: ExtName<ExtType>, extManifest: ExtManifest<ExtType>): string;
+    /**
+     * Returns--with reasonable accuracy--the path on disk to the extension.
+     *
+     * If `installPath` is present in the manifest, then it is used; otherwise we just guess.
+     * @param {keyof typeof this.installedExtensions} extName
+     * @returns {string}
+     */
+    getInstallPath(extName: keyof typeof this.installedExtensions): string;
+    /**
+     * Loads extension and returns its main class (constructor)
+     * @param {ExtName<ExtType>} extName
+     * @returns {ExtClass<ExtType>}
+     */
+    require(extName: ExtName<ExtType>): ExtClass<ExtType>;
+    /**
+     * @param {string} extName
+     * @returns {boolean}
+     */
+    isInstalled(extName: string): boolean;
+    /**
+     * If an extension provides a schema, this will load the schema and attempt to
+     * register it with the schema registrar.
+     * @param {ExtName<ExtType>} extName - Name of extension
+     * @param {ExtManifestWithSchema<ExtType>} extManifest - Extension data
+     * @returns {import('ajv').SchemaObject|undefined}
+     */
+    readExtensionSchema(extName: ExtName<ExtType>, extManifest: ExtManifestWithSchema<ExtType>): import('ajv').SchemaObject | undefined;
+    #private;
+}
+/**
+ * An issue with the {@linkcode ExtManifest } for a particular extension.
+ *
+ * The existance of such an object implies that the extension cannot be loaded.
+ */
+export type ExtManifestProblem = {
+    /**
+     * - Error message
+     */
+    err: string;
+    /**
+     * - Associated value
+     */
+    val: any;
+};
+/**
+ * An optional logging function provided to an {@link ExtensionConfig } subclass.
+ */
+export type ExtensionLogFn = (...args: any[]) => void;
+export type ExtensionType = import('@appium/types').ExtensionType;
+export type Manifest = import('./manifest').Manifest;
+export type InstallType = import('appium/types').InstallType;
+export type ExtManifest<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtManifest<ExtType>;
+export type ExtManifestWithSchema<ExtType extends import("@appium/types").ExtensionType> = ExtManifest<ExtType> & {
+    schema: NonNullable<ExtManifest<ExtType>['schema']>;
+};
+export type ExtName<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtName<ExtType>;
+export type ExtClass<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtClass<ExtType>;
+export type ExtRecord<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtRecord<ExtType>;
+export type ExtCommand<ExtType extends import("@appium/types").ExtensionType> = import('../cli/extension').ExtCommand<ExtType>;
+/**
+ * Options for various methods in {@link ExtensionConfig }
+ */
+export type ExtensionConfigMutationOpts = {
+    /**
+     * Whether or not to write the manifest to disk after a mutation operation
+     */
+    write?: boolean | undefined;
+};
+//# sourceMappingURL=extension-config.d.ts.map

package/build/lib/extension/extension-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-config.d.ts","sourceRoot":"","sources":["../../../lib/extension/extension-config.js"],"names":[],"mappings":"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"}