@appium/driver-test-support 1.0.5 → 1.1.0

package/lib/{e2e-suite.js → e2e-suite.ts}

@@ -1,68 +1,45 @@
 import _ from 'lodash';
 import {server, routeConfiguringFunction, DeviceSettings} from 'appium/driver';
-import axios from 'axios';
-import B from 'bluebird';
+import axios, {type RawAxiosRequestConfig} from 'axios';
+import {sleep} from 'asyncbox';
 import {TEST_HOST, getTestPort, createAppiumURL} from './helpers';
 import sinon from 'sinon';
 import {Agent} from 'node:http';
+import type {BaseNSCapabilities, Driver, DriverClass, SingularSessionData} from '@appium/types';
+import type {NewSessionResponse, SessionHelpers} from './types';
 
 /**
  * Creates some helper functions for E2E tests to manage sessions.
- * @template [CommandData=unknown]
- * @template [ResponseData=any]
- * @param {number} port - Port on which the server is running. Typically this will be retrieved via `get-port` beforehand
- * @param {string} [address] - Address/host on which the server is running. Defaults to {@linkcode TEST_HOST}
- * @returns {SessionHelpers<CommandData, ResponseData>}
  */
-export function createSessionHelpers(port, address = TEST_HOST) {
-  const createAppiumTestURL =
-    /** @type {import('lodash').CurriedFunction2<string,string,string>} */ (
-      createAppiumURL(address, port)
-    );
-
-  const createSessionURL = createAppiumTestURL(_, '');
+export function createSessionHelpers<CommandData = unknown, ResponseData = any>(
+  port: number,
+  address: string = TEST_HOST
+): SessionHelpers<CommandData, ResponseData> {
+  const createAppiumTestURL = createAppiumURL(address, port);
+  const createSessionURL = (sessionId: string) => createAppiumTestURL(sessionId, '');
   const newSessionURL = createAppiumTestURL('', 'session');
-  return /** @type {SessionHelpers<CommandData, ResponseData>} */ ({
+
+  return {
     newSessionURL,
     createAppiumTestURL,
-    /**
-     *
-     * @param {string} sessionId
-     * @param {string} cmdName
-     * @param {any} [data]
-     * @param {RawAxiosRequestConfig} [config]
-     * @returns {Promise<any>}
-     */
-    postCommand: async (sessionId, cmdName, data = {}, config = {}) => {
+    postCommand: async (sessionId, cmdName, data = {} as CommandData, config = {}) => {
       const url = createAppiumTestURL(sessionId, cmdName);
       const response = await axios.post(url, data, config);
       return response.data?.value;
     },
-    /**
-     *
-     * @param {string} sessionIdOrCmdName
-     * @param {string|RawAxiosRequestConfig} cmdNameOrConfig
-     * @param {RawAxiosRequestConfig} [config]
-     * @returns {Promise<any>}
-     */
     getCommand: async (sessionIdOrCmdName, cmdNameOrConfig, config = {}) => {
       if (!_.isString(cmdNameOrConfig)) {
-        config = cmdNameOrConfig;
+        config = cmdNameOrConfig as RawAxiosRequestConfig;
         cmdNameOrConfig = sessionIdOrCmdName;
         sessionIdOrCmdName = '';
       }
       const response = await axios({
-        url: createAppiumTestURL(sessionIdOrCmdName, cmdNameOrConfig),
+        url: createAppiumTestURL(sessionIdOrCmdName, cmdNameOrConfig as string),
         validateStatus: null,
         ...config,
       });
       return response.data?.value;
     },
-    /**
-     *
-     * @param {NewSessionData} data
-     * @param {RawAxiosRequestConfig} [config]
-     */
     startSession: async (data, config = {}) => {
       data = _.defaultsDeep(data, {
         capabilities: {
@@ -73,18 +50,10 @@ export function createSessionHelpers(port, address = TEST_HOST) {
       const response = await axios.post(newSessionURL, data, config);
       return response.data?.value;
     },
-    /**
-     *
-     * @param {string} sessionId
-     */
     endSession: async (sessionId) =>
       await axios.delete(createSessionURL(sessionId), {
         validateStatus: null,
       }),
-    /**
-     * @param {string} sessionId
-     * @returns {Promise<any>}
-     */
     getSession: async (sessionId) => {
       const response = await axios({
         url: createSessionURL(sessionId),
@@ -92,59 +61,53 @@ export function createSessionHelpers(port, address = TEST_HOST) {
       });
       return response.data?.value;
     },
-  });
+  };
 }
 
 /**
  * Creates E2E test suites for a driver.
- * @param {DriverClass} DriverClass
- * @param {Partial<BaseNSCapabilities>} [defaultCaps]
  */
-export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
-  let address = defaultCaps['appium:address'] ?? TEST_HOST;
-  let port = defaultCaps['appium:port'];
+export function driverE2ETestSuite(
+  DriverClass: DriverClass<Driver>,
+  defaultCaps: Partial<BaseNSCapabilities> = {}
+): void {
+  const address = (defaultCaps as BaseNSCapabilities)['appium:address'] ?? TEST_HOST;
+  let port: number | undefined = (defaultCaps as BaseNSCapabilities)['appium:port'];
   const className = DriverClass.name || '(unknown driver)';
 
   describe(`BaseDriver E2E (as ${className})`, function () {
-    let baseServer;
-    /** @type {Driver} */
-    let d;
-    /**
-     * This URL creates a new session
-     * @type {string}
-     **/
-    let newSessionURL;
-
-    /** @type {SessionHelpers['startSession']} */
-    let startSession;
-    /** @type {SessionHelpers['getSession']} */
-    let getSession;
-    /** @type {SessionHelpers['endSession']} */
-    let endSession;
-    /** @type {SessionHelpers['getCommand']} */
-    let getCommand;
-    /** @type {SessionHelpers['postCommand']} */
-    let postCommand;
-    let expect;
+    let baseServer: Awaited<ReturnType<typeof server>>;
+    let d: InstanceType<typeof DriverClass>;
+    let newSessionURL: string;
+    let startSession: SessionHelpers['startSession'];
+    let getSession: SessionHelpers['getSession'];
+    let endSession: SessionHelpers['endSession'];
+    let getCommand: SessionHelpers['getCommand'];
+    let postCommand: SessionHelpers['postCommand'];
+    let expect: Chai.ExpectStatic;
 
     before(async function () {
       const chai = await import('chai');
       const chaiAsPromised = await import('chai-as-promised');
-      chai.use(chaiAsPromised.default);
-      expect = chai.expect;
+      (chai as any).use((chaiAsPromised as any).default);
+      expect = (chai as any).expect;
 
       port = port ?? (await getTestPort());
       defaultCaps = {...defaultCaps};
-      d = new DriverClass({port, address});
+      d = new DriverClass({port, address}) as InstanceType<typeof DriverClass>;
       baseServer = await server({
         routeConfiguringFunction: routeConfiguringFunction(d),
-        port,
+        port: port!,
         hostname: address,
-        // @ts-expect-error
-        cliArgs: {},
+        cliArgs: {} as any,
       });
-      ({startSession, getSession, endSession, newSessionURL, getCommand, postCommand} =
-        createSessionHelpers(port, address));
+      const helpers = createSessionHelpers(port, address);
+      startSession = helpers.startSession;
+      getSession = helpers.getSession;
+      endSession = helpers.endSession;
+      getCommand = helpers.getCommand;
+      postCommand = helpers.postCommand;
+      newSessionURL = helpers.newSessionURL;
     });
     after(async function () {
       await baseServer?.close();
@@ -160,7 +123,7 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
         // workaround for https://github.com/node-fetch/node-fetch/issues/1735
         const httpAgent = new Agent({keepAlive: true});
 
-        const sessionIds = [];
+        const sessionIds: string[] = [];
         let times = 0;
         do {
           const {sessionId} = await startSession(
@@ -194,7 +157,7 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
         // workaround for https://github.com/node-fetch/node-fetch/issues/1735
         const httpAgent = new Agent({keepAlive: true});
 
-        const reqs = [];
+        const reqs: Promise<NewSessionResponse>[] = [];
         let times = 0;
         do {
           reqs.push(
@@ -214,7 +177,7 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
           );
           times++;
         } while (times < 2);
-        const sessionIds = _.map(await B.all(reqs), 'sessionId');
+        const sessionIds = _.map(await Promise.all(reqs), 'sessionId');
         expect(_.uniq(sessionIds)).to.have.lengthOf(1);
 
         const {status, data} = await endSession(sessionIds[0]);
@@ -232,9 +195,11 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
         expect(status).to.equal(200);
         expect(data.value.sessionId).to.exist;
         expect(data.value.capabilities.platformName).to.equal(defaultCaps.platformName);
-        expect(data.value.capabilities.deviceName).to.equal(defaultCaps['appium:deviceName']);
+        expect(data.value.capabilities.deviceName).to.equal(
+          (defaultCaps as BaseNSCapabilities)['appium:deviceName']
+        );
 
-        ({status, data} = await endSession(/** @type {string} */ (d.sessionId)));
+        ({status, data} = await endSession(d.sessionId!));
 
         expect(status).to.equal(200);
         expect(data.value).to.be.null;
@@ -243,26 +208,24 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
     });
 
     describe('command timeouts', function () {
-      let originalFindElement, originalFindElements;
+      let originalFindElement: typeof d.findElement;
+      let originalFindElements: typeof d.findElements;
 
-      /**
-       * @param {number} [timeout]
-       */
-      async function startTimeoutSession(timeout) {
+      async function startTimeoutSession(timeout?: number) {
         const caps = _.cloneDeep(defaultCaps);
-        caps['appium:newCommandTimeout'] = timeout;
+        (caps as any)['appium:newCommandTimeout'] = timeout;
         return await startSession({capabilities: {alwaysMatch: caps}});
       }
 
       before(function () {
         originalFindElement = d.findElement;
         d.findElement = function () {
-          return 'foo';
+          return 'foo' as any;
         }.bind(d);
 
         originalFindElements = d.findElements;
         d.findElements = async function () {
-          await B.delay(200);
+          await sleep(200);
           return ['foo'];
         }.bind(d);
       });
@@ -273,19 +236,19 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
       });
 
       it('should set a default commandTimeout', async function () {
-        let newSession = await startTimeoutSession();
+        const newSession = await startTimeoutSession();
         expect(d.newCommandTimeoutMs).to.be.above(0);
         await endSession(newSession.sessionId);
       });
 
       it('should timeout on commands using commandTimeout cap', async function () {
-        let newSession = await startTimeoutSession(0.25);
-        const sessionId = /** @type {string} */ (d.sessionId);
+        const newSession = await startTimeoutSession(0.25);
+        const sessionId = d.sessionId!;
         await postCommand(sessionId, 'element', {
           using: 'name',
           value: 'foo',
         });
-        await B.delay(400);
+        await sleep(400);
         const value = await getSession(sessionId);
         expect(value.error).to.equal('invalid session id');
         expect(d.sessionId).to.be.null;
@@ -294,9 +257,9 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
       });
 
       it('should not timeout with commandTimeout of false', async function () {
-        let newSession = await startTimeoutSession(0.1);
-        let start = Date.now();
-        const value = await postCommand(/** @type {string} */ (d.sessionId), 'elements', {
+        const newSession = await startTimeoutSession(0.1);
+        const start = Date.now();
+        const value = await postCommand(d.sessionId!, 'elements', {
           using: 'name',
           value: 'foo',
         });
@@ -307,14 +270,14 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
 
       it('should not timeout with commandTimeout of 0', async function () {
         d.newCommandTimeoutMs = 2;
-        let newSession = await startTimeoutSession(0);
+        const newSession = await startTimeoutSession(0);
 
-        await postCommand(/** @type {string} */ (d.sessionId), 'element', {
+        await postCommand(d.sessionId!, 'element', {
           using: 'name',
           value: 'foo',
         });
-        await B.delay(400);
-        const value = await getSession(/** @type {string} */ (d.sessionId));
+        await sleep(400);
+        const value = await getSession(d.sessionId!);
         expect(value.platformName).to.equal(defaultCaps.platformName);
         const resp = (await endSession(newSession.sessionId)).data.value;
         expect(resp).to.be.null;
@@ -323,35 +286,28 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
       });
 
       it('should not timeout if its just the command taking awhile', async function () {
-        let newSession = await startTimeoutSession(0.25);
-        // XXX: race condition: we must build this URL before ...something happens...
-        // which causes `d.sessionId` to be missing
+        const newSession = await startTimeoutSession(0.25);
         const {sessionId} = d;
 
-        await postCommand(/** @type {string} */ (d.sessionId), 'element', {
+        await postCommand(d.sessionId!, 'element', {
           using: 'name',
           value: 'foo',
         });
-        await B.delay(400);
-        const value = await getSession(/** @type {string} */ (sessionId));
-        expect(/** @type {string} */ (value.error)).to.equal('invalid session id');
+        await sleep(400);
+        const value = await getSession(sessionId!);
+        expect((value as any).error).to.equal('invalid session id');
         expect(d.sessionId).to.be.null;
-        const resp = (await endSession(newSession.sessionId)).data.value;
-        expect(/** @type {string} */ (/** @type { {error: string} } */ (resp).error)).to.equal(
-          'invalid session id'
-        );
+        const resp = (await endSession(newSession.sessionId)).data.value as {error?: string};
+        expect(resp?.error).to.equal('invalid session id');
       });
 
       it('should not have a timer running before or after a session', async function () {
-        // @ts-expect-error
-        expect(d.noCommandTimer).to.be.null;
-        let newSession = await startTimeoutSession(0.25);
+        expect((d as any).noCommandTimer).to.be.null;
+        const newSession = await startTimeoutSession(0.25);
         expect(newSession.sessionId).to.equal(d.sessionId);
-        // @ts-expect-error
-        expect(d.noCommandTimer).to.exist;
+        expect((d as any).noCommandTimer).to.exist;
         await endSession(newSession.sessionId);
-        // @ts-expect-error
-        expect(d.noCommandTimer).to.be.null;
+        expect((d as any).noCommandTimer).to.be.null;
       });
     });
 
@@ -367,15 +323,13 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
       });
       it('should reject for invalid update object', async function () {
         await expect(
-          // @ts-expect-error
-          d.settings.update('invalid json')
+          (d.settings as any).update('invalid json')
         ).to.be.rejectedWith('JSON');
       });
     });
 
     describe('unexpected exits', function () {
-      /** @type {import('sinon').SinonSandbox} */
-      let sandbox;
+      let sandbox: ReturnType<typeof sinon.createSandbox>;
       beforeEach(function () {
         sandbox = sinon.createSandbox();
       });
@@ -386,12 +340,11 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
 
       it('should reject a current command when the driver crashes', async function () {
         sandbox.stub(d, 'getStatus').callsFake(async function () {
-          await B.delay(5000);
+          await sleep(5000);
         });
         const reqPromise = getCommand('status', {validateStatus: null});
-        // make sure that the request gets to the server before our shutdown
-        await B.delay(100);
-        const shutdownEventPromise = new B((resolve, reject) => {
+        await sleep(100);
+        const shutdownEventPromise = new Promise<void>((resolve, reject) => {
           setTimeout(
             () =>
               reject(
@@ -405,16 +358,14 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
         });
         d.startUnexpectedShutdown(new Error('Crashytimes'));
         const value = await reqPromise;
-        expect(value.message).to.contain('Crashytimes');
+        expect((value as any).message).to.contain('Crashytimes');
         await shutdownEventPromise;
       });
     });
 
     describe('event timings', function () {
-      /** @type {NewSessionResponse} */
-      let session;
-      /** @type {SingularSessionData} */
-      let res;
+      let session: NewSessionResponse | undefined;
+      let res: SingularSessionData;
 
       describe('when not provided the eventTimings cap', function () {
         before(async function () {
@@ -458,53 +409,3 @@ export function driverE2ETestSuite(DriverClass, defaultCaps = {}) {
     });
   });
 }
-
-/**
- * @typedef {import('@appium/types').DriverClass} DriverClass
- * @typedef {import('@appium/types').Driver} Driver
- * @typedef {import('@appium/types').Constraints} Constraints
- * @typedef {import('@appium/types').StringRecord} StringRecord
- * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints
- * @typedef {import('@appium/types').BaseNSCapabilities} BaseNSCapabilities
- * @typedef {import('axios').RawAxiosRequestConfig} RawAxiosRequestConfig
- */
-
-/**
- * `Constraints` is purposefully loose here
- * @template {Constraints} [C=Constraints]
- * @typedef {import('@appium/types').SingularSessionData<C>} SingularSessionData
- */
-
-/**
- * @template T,D
- * @typedef {import('axios').AxiosResponse<T, D>} AxiosResponse
- */
-
-/**
- * `Constraints` is purposefully loose here
- * @template {Constraints} [C=Constraints]
- * @typedef NewSessionData
- * @property {import('type-fest').RequireAtLeastOne<import('@appium/types').W3CCapabilities<C>, 'firstMatch'|'alwaysMatch'>} capabilities
- */
-
-/**
- * `Constraints` is purposefully loose here
- * @template {Constraints} [C=Constraints]
- * @typedef NewSessionResponse
- * @property {string} sessionId,
- * @property {import('@appium/types').Capabilities<C>} capabilities
- */
-
-/**
- * Some E2E helpers for making requests and managing sessions
- * See {@linkcode createSessionHelpers}
- * @template [CommandData=unknown]
- * @template [ResponseData=any]
- * @typedef SessionHelpers
- * @property {string} newSessionURL - URL to create a new session. Can be used with raw `axios` requests to fully inspect raw response.  Mostly, this will not be used.
- * @property {(data: NewSessionData, config?: RawAxiosRequestConfig) => Promise<NewSessionResponse>} startSession - Begin a session
- * @property {(sessionId: string) => Promise<AxiosResponse<{value: {error?: string}?}, {validateStatus: null}>>} endSession - End a session. _Note: resolves with raw response object_
- * @property {(sessionId: string) => Promise<SingularSessionData>} getSession - Get info about a session
- * @property {(sessionId: string, cmdName: string, data?: CommandData, config?: RawAxiosRequestConfig) => Promise<ResponseData>} postCommand - Send an arbitrary command via `POST`.
- * @property {(sessionIdOrCmdName: string, cmdNameOrConfig: string|RawAxiosRequestConfig, config?: RawAxiosRequestConfig) => Promise<ResponseData>} getCommand - Send an arbitrary command via `GET`. Optional `sessionId`.
- */

package/lib/helpers.ts

@@ -0,0 +1,44 @@
+import getPort from 'get-port';
+import _ from 'lodash';
+
+/**
+ * Default test host
+ */
+export const TEST_HOST = '127.0.0.1';
+
+let testPort: number | undefined;
+
+/**
+ * Returns a free port; one per process
+ * @param force - If true, do not reuse the port (if it already exists)
+ * @returns a free port
+ */
+export async function getTestPort(force = false): Promise<number> {
+  if (force || !testPort) {
+    const 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 (`_`).
+ */
+export const createAppiumURL = _.curry(
+  (address: string, port: string | number, session: string | null, pathname: string): string => {
+    if (!/^https?:\/\//.test(address)) {
+      address = `http://${address}`;
+    }
+    let path = session ? `session/${session}` : '';
+    if (pathname) {
+      path = `${path}/${pathname}`;
+    }
+    return new URL(path, `${address}:${port}`).href;
+  }
+);

package/lib/index.ts

@@ -0,0 +1,4 @@
+export {createSessionHelpers, driverE2ETestSuite} from './e2e-suite';
+export * from './unit-suite';
+export * from './helpers';
+export type {NewSessionData, NewSessionResponse, SessionHelpers} from './types';

package/lib/types.ts

@@ -0,0 +1,36 @@
+import type {AxiosResponse, RawAxiosRequestConfig} from 'axios';
+import type {Capabilities, Constraints, SingularSessionData, W3CCapabilities} from '@appium/types';
+import type {RequireAtLeastOne} from 'type-fest';
+
+export interface NewSessionData<C extends Constraints = Constraints> {
+  capabilities: RequireAtLeastOne<W3CCapabilities<C>, 'firstMatch' | 'alwaysMatch'>;
+}
+
+export interface NewSessionResponse<C extends Constraints = Constraints> {
+  sessionId: string;
+  capabilities: Capabilities<C>;
+}
+
+export interface SessionHelpers<CommandData = unknown, ResponseData = any> {
+  newSessionURL: string;
+  createAppiumTestURL: (session: string, pathname: string) => string;
+  postCommand: (
+    sessionId: string,
+    cmdName: string,
+    data?: CommandData,
+    config?: RawAxiosRequestConfig
+  ) => Promise<ResponseData>;
+  getCommand: (
+    sessionIdOrCmdName: string,
+    cmdNameOrConfig: string | RawAxiosRequestConfig,
+    config?: RawAxiosRequestConfig
+  ) => Promise<ResponseData>;
+  startSession: (
+    data: NewSessionData,
+    config?: RawAxiosRequestConfig
+  ) => Promise<NewSessionResponse>;
+  endSession: (
+    sessionId: string
+  ) => Promise<AxiosResponse<{value: {error?: string} | null}, {validateStatus: null}>>;
+  getSession: (sessionId: string) => Promise<SingularSessionData>;
+}