@appium/test-support 1.3.22 → 1.5.0

package/lib/helpers.js

@@ -0,0 +1,68 @@
+import getPort from 'get-port';
+import {curry} from 'lodash';
+
+/**
+ * Default test host
+ */
+const TEST_HOST = '127.0.0.1';
+
+let testPort;
+
+/**
+ * Returns a free port; one per process
+ * @param {boolean} [force] - If true, do not reuse the port (if it already exists)
+ * @returns {Promise<number>} a free port
+ */
+async function getTestPort(force = false) {
+  if (force || !testPort) {
+    let port = await getPort();
+    if (!testPort) {
+      testPort = port;
+    }
+    return port;
+  }
+  return testPort;
+}
+
+/**
+ * Build an Appium URL from components.
+ *
+ * **All** parameters are required.  Provide an empty string (`''`) if you don't need one.
+ * To rearrange arguments (if needed), use the placeholder from Lodash (`_`).
+ *
+ */
+const createAppiumURL = curry(
+  /**
+   * @param {string} address - Base address (w/ optional protocol)
+   * @param {string|number} port - Port number
+   * @param {string?} session - Session ID
+   * @param {string} pathname - Extra path
+   * @returns {string} New URL
+   * @example
+   *
+   * import _ from 'lodash';
+   *
+   * // http://127.0.0.1:31337/session
+   * createAppiumURL('127.0.0.1', 31337, '', 'session')
+   *
+   * // http://127.0.0.1:31337/session/asdfgjkl
+   * const createSessionURL = createAppiumURL('127.0.0.1', 31337, _, 'session')
+   * createSessionURL('asdfgjkl')
+   *
+   * // http://127.0.0.1:31337/session/asdfgjkl/appium/execute
+   * const createURLWithPath = createAppiumURL('127.0.0.1', 31337, 'asdfgjkl');
+   * createURLWithPath('appium/execute')
+   */
+  (address, port, session, pathname) => {
+    if (!/^https?:\/\//.test(address)) {
+      address = `http://${address}`;
+    }
+    let path = session ? `session/${session}` : '';
+    if (pathname) {
+      path = `${path}/${pathname}`;
+    }
+    return new URL(path, `${address}:${port}`).href;
+  }
+);
+
+export {TEST_HOST, getTestPort, createAppiumURL};

package/lib/index.js

@@ -1,10 +1,20 @@
-import {stubEnv} from './env-utils';
-import {stubLog} from './log-utils';
-import {fakeTime} from './time-utils';
-import {withMocks, verifyMocks} from './mock-utils';
-import {withSandbox, verifySandbox} from './sandbox-utils';
-
 // this just needs to be imported, for the functionality to be injected
 import './unhandled-rejection';
 
-export {stubEnv, stubLog, fakeTime, withSandbox, verifySandbox, withMocks, verifyMocks};
+export {stubEnv} from './env-utils';
+export {stubLog} from './log-utils';
+export {fakeTime} from './time-utils';
+export {withMocks, verifyMocks} from './mock-utils';
+export {withSandbox, verifySandbox} from './sandbox-utils';
+export {pluginE2EHarness} from './plugin-e2e-harness';
+export {driverUnitTestSuite} from './driver-unit-suite';
+export {driverE2ETestSuite, createSessionHelpers} from './driver-e2e-suite';
+
+export * from './helpers';
+
+/**
+ * @typedef {import('./driver-e2e-suite').SessionHelpers} SessionHelpers
+ */
+/**
+ * @typedef {import('./plugin-e2e-harness').E2ESetupOpts} E2ESetupOpts
+ */

package/lib/log-utils.js

@@ -1,18 +1,22 @@
-// TODO move that to @appium/support
-function stripColors(msg) {
-  let code = /\u001b\[(\d+(;\d+)*)?m/g; // eslint-disable-line no-control-regex
-  msg = ('' + msg).replace(code, '');
-  return msg;
-}
+import '@colors/colors';
 
 class LogStub {
+  /**
+   *
+   * @param {LogStubOptions} [opts]
+   */
   constructor(opts = {}) {
     this.output = '';
-    this.stripColors = opts.stripColors;
+    this.stripColors = Boolean(opts.stripColors);
   }
+  /**
+   *
+   * @param {string} level
+   * @param {any} message
+   */
   log(level, message) {
     if (this.stripColors) {
-      message = stripColors(message);
+      message = message.stripColors;
     }
     if (this.output.length > 0) {
       this.output += '\n';
@@ -21,6 +25,13 @@ class LogStub {
   }
 }
 
+/**
+ * Instantiates a {@linkcode LogStub} object
+ * @param {import('sinon').SinonSandbox} sandbox
+ * @param {import('@appium/types').AppiumLogger} log
+ * @param {LogStubOptions} [opts]
+ * @returns {LogStub}
+ */
 function stubLog(sandbox, log, opts = {}) {
   let logStub = new LogStub(opts);
   for (let l of log.levels) {
@@ -32,3 +43,9 @@ function stubLog(sandbox, log, opts = {}) {
 }
 
 export {stubLog};
+
+/**
+ * Options for {@linkcode LogStub} constructor
+ * @typedef LogStubOptions
+ * @property {boolean} [stripColors] - If `true`, strip ANSI colors from output
+ */

package/lib/logger.js

@@ -1,4 +1,4 @@
-import {logger} from '@appium/support';
+import {logger} from 'appium/support';
 
 const log = logger.getLogger('AppiumTestSupport');
 

package/lib/mock-utils.js

@@ -1,36 +1,100 @@
+import B from 'bluebird';
 import sinon from 'sinon';
-import _ from 'lodash';
 
-let SANDBOX = Symbol();
-
-function withMocks(libs, fn) {
+/**
+ * Creates a function which creates Mocha "before each" and "after each" hooks to
+ * automatically mock (and un-mock) the mocks provided by `libs`.
+ *
+ * The values of `libs` are provided directly to {@linkcode SinonSandbox.mock}.
+ *
+ * _Synchronously_ calls `fn` with the {@linkcode MockStore} after hooks have been created, but not before they have been run.
+ *
+ * @param {Record<string|symbol,any>} mockDefs
+ * @param {(mocks: MockStore) => void} fn
+ * @returns {() => void}
+ */
+export function withMocks(mockDefs, fn) {
   return () => {
-    const mocks = {
-      verify() {
-        this.sandbox.verify();
-      },
-      get sandbox() {
-        return this[SANDBOX];
-      },
-      set sandbox(sandbox) {
-        this[SANDBOX] = sandbox;
-      },
-    };
-    beforeEach(function beforeEach() {
-      mocks[SANDBOX] = sinon.createSandbox();
-      for (let [key, value] of _.toPairs(libs)) {
-        mocks[key] = mocks.sandbox.mock(value);
-      }
+    const mocks = new MockStore();
+    beforeEach(function withMocksBeforeEach() {
+      mocks.createMocks(mockDefs);
     });
-    afterEach(function afterEach() {
-      mocks.sandbox.restore();
+    afterEach(function withMocksAfterEach() {
+      mocks.reset();
     });
     fn(mocks);
   };
 }
 
-function verifyMocks(mocks) {
-  mocks.sandbox.verify();
+/**
+ * Convenience function for calling `mocks.verify()`.
+ * @param {MockStore} mocks - Returned by callback from {@linkcode withMocks}
+ */
+export function verifyMocks(mocks) {
+  mocks.verify();
+}
+
+/**
+ * @template {Record<string,any>} Mocks
+ * @extends {Mocks}
+ */
+export class MockStore {
+  /**
+   * Temporary sandbox; will be `undefined` until `beforeEach` is called
+   * @type {SinonSandbox|undefined}
+   */
+  sandbox;
+
+  /**
+   * Original k/v pair provided to `createMocks`
+   * @type {Mocks|undefined}
+   */
+  #mocks;
+
+  /**
+   * Uses a sandbox if one is provided
+   * @param {SinonSandbox} [sandbox]
+   */
+  constructor(sandbox) {
+    this.sandbox = sandbox;
+  }
+
+  /**
+   * @param {Mocks} mockDefs
+   */
+  createMocks(mockDefs) {
+    if (this.#mocks) {
+      throw new ReferenceError('Cannot create mocks twice; call `reset()` first.');
+    }
+    this.sandbox = this.sandbox ?? sinon.createSandbox().usingPromise(B);
+    for (const [key, value] of Object.entries(mockDefs)) {
+      this[key] = this.sandbox.mock(value);
+    }
+    this.#mocks = mockDefs;
+    return this;
+  }
+
+  /**
+   * Calls {@linkcode SinonSandbox.verify} on the `sandbox` prop, if it exists
+   */
+  verify() {
+    if (!this.sandbox) {
+      throw new ReferenceError(
+        'Cannot verify mocks before they are created; call `createMocks()` first'
+      );
+    }
+    this.sandbox.verify();
+  }
+
+  reset() {
+    for (const key of Object.keys(this.#mocks ?? {})) {
+      delete this[key];
+    }
+    this.sandbox?.restore();
+    this.#mocks = undefined;
+  }
 }
 
-export {withMocks, verifyMocks};
+/**
+ * @typedef {import('sinon').SinonSandbox} SinonSandbox
+ */

package/lib/plugin-e2e-harness.js

@@ -0,0 +1,163 @@
+/* eslint-disable no-console */
+import {fs} from 'appium/support';
+import {main as appiumServer} from 'appium';
+import getPort from 'get-port';
+import {info, success, warning} from 'log-symbols';
+import {exec} from 'teen_process';
+
+const APPIUM_BIN = require.resolve('appium');
+
+/**
+ * Creates hooks to install a driver and a plugin and starts an Appium server w/ the given extensions.
+ * @param {E2ESetupOpts} opts
+ * @returns {void}
+ */
+export function pluginE2EHarness(opts) {
+  let {
+    appiumHome,
+    before,
+    after,
+    serverArgs = {},
+    driverSource,
+    driverPackage,
+    driverName,
+    driverSpec,
+    pluginSource,
+    pluginPackage,
+    pluginSpec,
+    pluginName,
+    port,
+    host,
+  } = opts;
+
+  /**
+   * @type {AppiumServer}
+   */
+  let server;
+
+  before(async function () {
+    const setupAppiumHome = async () => {
+      /**
+       * @type {AppiumEnv}
+       */
+      const env = {...process.env};
+
+      if (appiumHome) {
+        env.APPIUM_HOME = appiumHome;
+        await fs.mkdirp(appiumHome);
+        console.log(`${info} Set \`APPIUM_HOME\` to ${appiumHome}`);
+      }
+
+      return env;
+    };
+
+    /**
+     *
+     * @param {AppiumEnv} env
+     */
+    const installDriver = async (env) => {
+      console.log(`${info} Checking if driver "${driverName}" is installed...`);
+      const driverListArgs = [APPIUM_BIN, 'driver', 'list', '--json'];
+      console.log(`${info} Running: ${process.execPath} ${driverListArgs.join(' ')}`);
+      const {stdout: driverListJson} = await exec(process.execPath, driverListArgs, {
+        env,
+      });
+      const installedDrivers = JSON.parse(driverListJson);
+
+      if (!installedDrivers[driverName]?.installed) {
+        console.log(`${warning} Driver "${driverName}" not installed; installing...`);
+        const driverArgs = [APPIUM_BIN, 'driver', 'install', '--source', driverSource, driverSpec];
+        if (driverPackage) {
+          driverArgs.push('--package', driverPackage);
+        }
+        console.log(`${info} Running: ${process.execPath} ${driverArgs.join(' ')}`);
+        await exec(process.execPath, driverArgs, {
+          env,
+        });
+      }
+      console.log(`${success} Installed driver "${driverName}"`);
+    };
+
+    /**
+     *
+     * @param {AppiumEnv} env
+     */
+    const installPlugin = async (env) => {
+      console.log(`${info} Checking if plugin "${pluginName}" is installed...`);
+      const pluginListArgs = [APPIUM_BIN, 'plugin', 'list', '--json'];
+      const {stdout: pluginListJson} = await exec(process.execPath, pluginListArgs, {
+        env,
+      });
+      const installedPlugins = JSON.parse(pluginListJson);
+
+      if (!installedPlugins[pluginName]?.installed) {
+        console.log(`${warning} Plugin "${pluginName}" not installed; installing...`);
+        const pluginArgs = [APPIUM_BIN, 'plugin', 'install', '--source', pluginSource, pluginSpec];
+        if (pluginPackage) {
+          pluginArgs.push('--package', pluginPackage);
+        }
+        console.log(`${info} Running: ${process.execPath} ${pluginArgs.join(' ')}`);
+        await exec(process.execPath, pluginArgs, {
+          env,
+        });
+      }
+      console.log(`${success} Installed plugin "${pluginName}"`);
+    };
+
+    const createServer = async () => {
+      if (!port) {
+        port = await getPort();
+      }
+      console.log(`${info} Will use port ${port} for Appium server`);
+      this.port = port;
+
+      /** @type {import('appium').Args} */
+      const args = {
+        port,
+        address: host,
+        usePlugins: [pluginName],
+        useDrivers: [driverName],
+        appiumHome,
+        ...serverArgs,
+      };
+      server = /** @type {AppiumServer} */ (await appiumServer(args));
+    };
+
+    const env = await setupAppiumHome();
+    await installDriver(env);
+    await installPlugin(env);
+    await createServer();
+  });
+
+  after(async function () {
+    if (server) {
+      await server.close();
+    }
+  });
+}
+
+/**
+ * @typedef E2ESetupOpts
+ * @property {string} [appiumHome] - Path to Appium home directory
+ * @property {Mocha.before} before - Mocha "before all" hook function
+ * @property {Mocha.after} after - Mocha "after all" hook function
+ * @property {Partial<import('appium').Args>} [serverArgs] - Arguments to pass to Appium server
+ * @property {import('appium/types').InstallType & string} driverSource - Source of driver to install
+ * @property {string} [driverPackage] - Package name of driver to install
+ * @property {string} driverName - Name of driver to install
+ * @property {string} driverSpec - Spec of driver to install
+ * @property {import('appium/types').InstallType & string} pluginSource - Source of plugin to install
+ * @property {string} [pluginPackage] - Package name of plugin to install
+ * @property {string} pluginSpec - Spec of plugin to install
+ * @property {string} pluginName - Name of plugin to install
+ * @property {number} [port] - Port to use for Appium server
+ * @property {string} [host] - Host to use for Appium server
+ */
+
+/**
+ * @typedef {import('@appium/types').AppiumServer} AppiumServer
+ */
+
+/**
+ * @typedef {import('appium/types').AppiumEnv} AppiumEnv
+ */

package/lib/sandbox-utils.js

@@ -1,40 +1,84 @@
 import sinon from 'sinon';
 import _ from 'lodash';
 import B from 'bluebird';
+import {MockStore} from './mock-utils';
 
-let SANDBOX = Symbol();
-
-// use this one if using a mix of mocks/stub/spies
-function withSandbox(config, fn) {
+/**
+ * @template {Record<string,any>|{mocks: Record<string,any>}} Mocks
+ * @param {Mocks} mockDefs
+ * @param {(sandboxStore: SandboxStore) => void} fn
+ * @returns {() => void}
+ */
+export function withSandbox(mockDefs, fn) {
+  // backwards-compat
+  if (!_.isEmpty(mockDefs.mocks)) {
+    mockDefs = mockDefs.mocks;
+  }
   return () => {
-    const S = {
-      mocks: {},
-      verify() {
-        return this.sandbox.verify();
-      },
-    };
+    /** @type {SandboxStore} */
+    const sbx = new SandboxStore();
     beforeEach(function beforeEach() {
-      S.sandbox = sinon.createSandbox();
-      S.sandbox.usingPromise(B);
-      S.mocks[SANDBOX] = S.sandbox;
-      for (let [key, value] of _.toPairs(config.mocks)) {
-        S.mocks[key] = S.sandbox.mock(value);
-      }
+      sbx.createSandbox(mockDefs);
     });
     afterEach(function afterEach() {
-      S.sandbox.restore();
-      for (let k of _.keys(S.mocks)) {
-        delete S.mocks[k];
-      }
-      delete S.mocks[SANDBOX];
+      sbx.reset();
     });
-    fn(S);
+    fn(sbx);
   };
 }
 
-function verifySandbox(obj) {
-  let sandbox = obj.sandbox ? obj.sandbox : obj[SANDBOX];
-  sandbox.verify();
+/**
+ * Convenience function for calling {@linkcode SandboxStore.verify}.
+ * @param {SandboxStore|MockStore} sbxOrMocks
+ */
+export function verifySandbox(sbxOrMocks) {
+  sbxOrMocks.verify();
+}
+
+/**
+ * @template {Record<string,any>} Mocks
+ */
+export class SandboxStore {
+  /** @type {MockStore<Record<string,any>>} */
+  mocks;
+
+  /** @type {SinonSandbox|undefined} */
+  sandbox;
+
+  /**
+   * Uses a sandbox if one is provided
+   * @param {SinonSandbox} [sandbox]
+   */
+  constructor(sandbox) {
+    this.sandbox = sandbox;
+  }
+
+  /**
+   * @param {Mocks} mocks
+   */
+  createSandbox(mocks = /** @type {Mocks} */ ({})) {
+    this.sandbox = this.sandbox ?? sinon.createSandbox().usingPromise(B);
+    this.mocks = new MockStore(this.sandbox).createMocks(mocks);
+  }
+
+  /**
+   * Calls {@linkcode SinonSandbox.verify} on the `sandbox` prop, if it exists
+   */
+  verify() {
+    if (!this.sandbox) {
+      throw new ReferenceError(
+        'Cannot verify mocks before they are created; call `createMocks()` first'
+      );
+    }
+    this.sandbox.verify();
+  }
+
+  reset() {
+    this.mocks?.reset();
+    delete this.sandbox;
+  }
 }
 
-export {withSandbox, verifySandbox};
+/**
+ * @typedef {import('sinon').SinonSandbox} SinonSandbox
+ */

package/lib/time-utils.js

@@ -1,3 +1,4 @@
+/** @deprecated */
 function fakeTime(sandbox) {
   let clock = sandbox.useFakeTimers();
   return new TimeLord(clock);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/test-support",
-  "version": "1.3.22",
+  "version": "1.5.0",
   "description": "A collection of test utilities used across Appium packages",
   "keywords": [
     "automation",
@@ -23,6 +23,7 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
+  "types": "./build/lib/index.d.ts",
   "bin": {
     "android-emu-travis-post": "./bin/android-emu-travis-post.sh",
     "android-emu-travis-pre": "./bin/android-emu-travis-pre.sh"
@@ -43,23 +44,31 @@
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
     "prepare": "npm run build",
     "test": "npm run test:unit",
+    "test:smoke": "node ./index.js",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/support": "^2.59.2",
-    "@babel/runtime": "7.18.3",
+    "@babel/runtime": "7.18.9",
+    "@colors/colors": "1.5.0",
     "bluebird": "3.7.2",
+    "chai": "4.3.6",
+    "get-port": "5.1.1",
     "lodash": "4.17.21",
+    "log-symbols": "4.1.0",
     "loud-rejection": "2.2.0",
     "sinon": "14.0.0",
-    "source-map-support": "0.5.21"
+    "source-map-support": "0.5.21",
+    "teen_process": "1.16.0"
+  },
+  "peerDependencies": {
+    "appium": "^2.0.0-beta.35"
   },
   "engines": {
     "node": ">=14",
-    "npm": ">=6"
+    "npm": ">=8"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "4cf2cc92d066ed32adda27e0439547290a4b71ce"
+  "gitHead": "c58f32441daba3aae9768a57d0a412fe92f4b587"
 }