appium 2.0.0-beta.5 → 2.0.0-beta.53

package/build/lib/cli/extension-command.d.ts

@@ -0,0 +1,385 @@
+export default ExtensionCommand;
+/**
+ * Options for the {@linkcode ExtensionCommand } constructor
+ */
+export type ExtensionCommandOptions<ExtType extends import("@appium/types").ExtensionType> = {
+    /**
+     * - the `DriverConfig` or `PluginConfig` instance used for this command
+     */
+    config: ExtensionConfig<ExtType>;
+    /**
+     * - whether the output of this command should be JSON or text
+     */
+    json: boolean;
+};
+/**
+ * Extra stuff about extensions; used indirectly by {@linkcode ExtensionCommand.list }.
+ */
+export type ExtensionMetadata = {
+    /**
+     * - If `true`, the extension is installed
+     */
+    installed: boolean;
+    /**
+     * - If the extension is installed, the version it can be updated to
+     */
+    updateVersion: string | null;
+    /**
+     * - Same as above, but a major version bump
+     */
+    unsafeUpdateVersion: string | null;
+    /**
+     * - If the extension is installed and the latest
+     */
+    upToDate: boolean;
+    /**
+     * - Update check error message (if present)
+     */
+    updateError: string | null;
+};
+export type ExtensionType = import('@appium/types').ExtensionType;
+export type DriverType = import('@appium/types').DriverType;
+export type PluginType = import('@appium/types').PluginType;
+export type ExtRecord<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtRecord<ExtType>;
+export type ExtensionConfig<ExtType extends import("@appium/types").ExtensionType> = import('../extension/extension-config').ExtensionConfig<ExtType>;
+export type ExtMetadata<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtMetadata<ExtType>;
+export type ExtManifest<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtManifest<ExtType>;
+export type ExtPackageJson<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtPackageJson<ExtType>;
+export type ExtInstallReceipt<ExtType extends import("@appium/types").ExtensionType> = import('appium/types').ExtInstallReceipt<ExtType>;
+/**
+ * Possible return value for {@linkcode ExtensionCommand.list }
+ */
+export type UninstalledExtensionListData = Partial<InstalledExtensionListData> & {
+    pkgName: string;
+    installed: false;
+};
+/**
+ * Possible return value for {@linkcode ExtensionCommand.list }
+ */
+export type InstalledExtensionListData = import('appium/types').InternalMetadata & ExtensionMetadata;
+/**
+ * Return value of {@linkcode ExtensionCommand.list }.
+ */
+export type ExtensionListData = Record<string, InstalledExtensionListData | UninstalledExtensionListData>;
+/**
+ * Options for {@linkcode ExtensionCommand._run }.
+ */
+export type RunOptions = {
+    /**
+     * - name of the extension to run a script from
+     */
+    installSpec: string;
+    /**
+     * - name of the script to run
+     */
+    scriptName: string;
+    /**
+     * - arguments to pass to the script
+     */
+    extraArgs?: string[] | undefined;
+};
+/**
+ * Return value of {@linkcode ExtensionCommand._run }
+ */
+export type RunOutput = {
+    /**
+     * - error message if script ran unsuccessfully, otherwise undefined
+     */
+    error?: string | undefined;
+    /**
+     * - script output
+     */
+    output: string[];
+};
+/**
+ * Options for {@linkcode ExtensionCommand._update }.
+ */
+export type ExtensionUpdateOpts = {
+    /**
+     * - the name of the extension to update
+     */
+    installSpec: string;
+    /**
+     * - if true, will perform unsafe updates past major revision boundaries
+     */
+    unsafe: boolean;
+};
+/**
+ * Return value of {@linkcode ExtensionCommand._update }.
+ */
+export type ExtensionUpdateResult = {
+    /**
+     * - map of ext names to error objects
+     */
+    errors: Record<string, Error>;
+    /**
+     * - map of ext names to {@linkcode UpdateReport }s
+     */
+    updates: Record<string, UpdateReport>;
+};
+/**
+ * Part of result of {@linkcode ExtensionCommand._update }.
+ */
+export type UpdateReport = {
+    /**
+     * - version the extension was updated from
+     */
+    from: string;
+    /**
+     * - version the extension was updated to
+     */
+    to: string;
+};
+/**
+ * Options for {@linkcode ExtensionCommand._uninstall }.
+ */
+export type UninstallOpts = {
+    /**
+     * - the name or spec of an extension to uninstall
+     */
+    installSpec: string;
+};
+/**
+ * Used by {@linkcode ExtensionCommand.getPostInstallText }
+ */
+export type ExtensionArgs = {
+    /**
+     * - the name of an extension
+     */
+    extName: string;
+    /**
+     * - the data for an installed extension
+     */
+    extData: object;
+};
+/**
+ * Options for {@linkcode ExtensionCommand.installViaNpm }
+ */
+export type InstallViaNpmArgs = {
+    /**
+     * - the name or spec of an extension to install
+     */
+    installSpec: string;
+    /**
+     * - the NPM package name of the extension
+     */
+    pkgName: string;
+    /**
+     * - type of install
+     */
+    installType: import('appium/types').InstallType;
+    /**
+     * - the specific version of the NPM package
+     */
+    pkgVer?: string | undefined;
+};
+/**
+ * Object returned by {@linkcode ExtensionCommand.checkForExtensionUpdate }
+ */
+export type PossibleUpdates = {
+    /**
+     * - current version
+     */
+    current: string;
+    /**
+     * - version we can safely update to if it exists, or null
+     */
+    safeUpdate: string | null;
+    /**
+     * - version we can unsafely update to if it exists, or null
+     */
+    unsafeUpdate: string | null;
+};
+/**
+ * Options for {@linkcode ExtensionCommand._install }
+ */
+export type InstallOpts = {
+    /**
+     * - the name or spec of an extension to install
+     */
+    installSpec: string;
+    /**
+     * - how to install this extension. One of the INSTALL_TYPES
+     */
+    installType: InstallType;
+    /**
+     * - for git/github installs, the extension node package name
+     */
+    packageName?: string | undefined;
+};
+export type KnownExtensions<ExtType extends import("@appium/types").ExtensionType> = ExtType extends DriverType ? typeof import('../constants').KNOWN_DRIVERS : ExtType extends PluginType ? typeof import('../constants').KNOWN_PLUGINS : never;
+export type ListOptions = {
+    /**
+     * - whether should show only installed extensions
+     */
+    showInstalled: boolean;
+    /**
+     * - whether should show available updates
+     */
+    showUpdates: boolean;
+};
+/**
+ * Opts for {@linkcode ExtensionCommand.getInstallationReceipt }
+ */
+export type GetInstallationReceiptOpts<ExtType extends import("@appium/types").ExtensionType> = {
+    installPath: string;
+    installSpec: string;
+    pkg: ExtPackageJson<ExtType>;
+    installType: InstallType;
+};
+export type InstallType = import('appium/types').InstallType;
+/**
+ * @template {ExtensionType} ExtType
+ */
+export class ExtensionCommand<ExtType extends import("@appium/types").ExtensionType> {
+    /**
+     * Build an ExtensionCommand
+     * @param {ExtensionCommandOptions<ExtType>} opts
+     */
+    constructor({ config, json }: ExtensionCommandOptions<ExtType>);
+    /**
+     * This is the `DriverConfig` or `PluginConfig`, depending on `ExtType`.
+     * @type {ExtensionConfig<ExtType>}
+     */
+    config: ExtensionConfig<ExtType>;
+    /**
+     * {@linkcode Record} of official plugins or drivers.
+     * @type {KnownExtensions<ExtType>}
+     */
+    knownExtensions: KnownExtensions<ExtType>;
+    /**
+     * If `true`, command output has been requested as JSON.
+     * @type {boolean}
+     */
+    isJsonOutput: boolean;
+    log: console.CliConsole;
+    /**
+     * `driver` or `plugin`, depending on the `ExtensionConfig`.
+     */
+    get type(): ExtType;
+    /**
+     * Logs a message and returns an {@linkcode Error} to throw.
+     *
+     * For TS to understand that a function throws an exception, it must actually throw an exception--
+     * in other words, _calling_ a function which is guaranteed to throw an exception is not enough--
+     * nor is something like `@returns {never}` which does not imply a thrown exception.
+     * @param {string} message
+     * @protected
+     * @throws {Error}
+     */
+    protected _createFatalError(message: string): Error;
+    /**
+     * Take a CLI parse and run an extension command based on its type
+     *
+     * @param {object} args - a key/value object with CLI flags and values
+     * @return {Promise<object>} the result of the specific command which is executed
+     */
+    execute(args: object): Promise<object>;
+    /**
+     * List extensions
+     *
+     * @param {ListOptions} opts
+     * @return {Promise<ExtensionListData>} map of extension names to extension data
+     */
+    list({ showInstalled, showUpdates }: ListOptions): Promise<ExtensionListData>;
+    /**
+     * Install an extension
+     *
+     * @param {InstallOpts} opts
+     * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
+     */
+    _install({ installSpec, installType, packageName }: InstallOpts): Promise<ExtRecord<ExtType>>;
+    /**
+     * Install an extension via NPM
+     *
+     * @param {InstallViaNpmArgs} args
+     * @returns {Promise<ExtInstallReceipt<ExtType>>}
+     */
+    installViaNpm({ installSpec, pkgName, pkgVer, installType }: InstallViaNpmArgs): Promise<ExtInstallReceipt<ExtType>>;
+    /**
+     * Get the text which should be displayed to the user after an extension has been installed. This
+     * is designed to be overridden by drivers/plugins with their own particular text.
+     *
+     * @param {ExtensionArgs} args
+     * @returns {string}
+     */
+    getPostInstallText(args: ExtensionArgs): string;
+    /**
+     * Once a package is installed on-disk, this gathers some necessary metadata for validation.
+     *
+     * @param {GetInstallationReceiptOpts<ExtType>} opts
+     * @returns {ExtInstallReceipt<ExtType>}
+     */
+    getInstallationReceipt({ pkg, installPath, installType, installSpec }: GetInstallationReceiptOpts<ExtType>): ExtInstallReceipt<ExtType>;
+    /**
+     * Validates the _required_ root fields of an extension's `package.json` file.
+     *
+     * These required fields are:
+     * - `name`
+     * - `version`
+     * - `appium`
+     * @param {import('type-fest').PackageJson} pkg - `package.json` of extension
+     * @param {string} installSpec - Extension name/spec
+     * @throws {ReferenceError} If `package.json` has a missing or invalid field
+     * @returns {pkg is ExtPackageJson<ExtType>}
+     */
+    validatePackageJson(pkg: import('type-fest').PackageJson, installSpec: string): pkg is ExtPackageJson<ExtType>;
+    /**
+     * For any `package.json` fields which a particular type of extension requires, validate the
+     * presence and form of those fields on the `package.json` data, throwing an error if anything is
+     * amiss.
+     *
+     * @param {ExtMetadata<ExtType>} extMetadata - the data in the "appium" field of `package.json` for an extension
+     * @param {string} installSpec - Extension name/spec
+     */
+    validateExtensionFields(extMetadata: ExtMetadata<ExtType>, installSpec: string): void;
+    /**
+     * Uninstall an extension.
+     *
+     * First tries to do this via `npm uninstall`, but if that fails, just `rm -rf`'s the extension dir.
+     *
+     * Will only remove the extension from the manifest if it has been successfully removed.
+     *
+     * @param {UninstallOpts} opts
+     * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data (without the extension just uninstalled)
+     */
+    _uninstall({ installSpec }: UninstallOpts): Promise<ExtRecord<ExtType>>;
+    /**
+     * Attempt to update one or more drivers using NPM
+     *
+     * @param {ExtensionUpdateOpts} updateSpec
+     * @return {Promise<ExtensionUpdateResult>}
+     */
+    _update({ installSpec, unsafe }: ExtensionUpdateOpts): Promise<ExtensionUpdateResult>;
+    /**
+     * Given an extension name, figure out what its highest possible version upgrade is, and also the
+     * highest possible safe upgrade.
+     *
+     * @param {string} ext - name of extension
+     * @return {Promise<PossibleUpdates>}
+     */
+    checkForExtensionUpdate(ext: string): Promise<PossibleUpdates>;
+    /**
+     * Actually update an extension installed by NPM, using the NPM cli. And update the installation
+     * manifest.
+     *
+     * @param {string} installSpec - name of extension to update
+     * @param {string} version - version string identifier to update extension to
+     * @returns {Promise<void>}
+     */
+    updateExtension(installSpec: string, version: string): Promise<void>;
+    /**
+     * Runs a script cached inside the "scripts" field under "appium"
+     * inside of the driver/plugins "package.json" file. Will throw
+     * an error if the driver/plugin does not contain a "scripts" field
+     * underneath the "appium" field in its package.json, if the
+     * "scripts" field is not a plain object, or if the scriptName is
+     * not found within "scripts" object.
+     *
+     * @param {RunOptions} opts
+     * @return {Promise<RunOutput>}
+     */
+    _run({ installSpec, scriptName, extraArgs }: RunOptions): Promise<RunOutput>;
+}
+import { console } from "@appium/support";
+//# sourceMappingURL=extension-command.d.ts.map

package/build/lib/cli/extension-command.d.ts.map

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