@appium/fake-driver 4.2.2 → 5.1.0

package/lib/commands/general.js

@@ -1,82 +1,119 @@
-import _ from 'lodash';
 import {errors} from 'appium/driver';
 
-let commands = {},
-  helpers = {},
-  extensions = {};
-
-commands.title = async function title() {
-  this.assertWebviewContext();
-  return this.appModel.title;
-};
-
-commands.keys = async function keys(value) {
-  if (!this.focusedElId) {
-    throw new errors.InvalidElementStateError();
-  }
-  await this.setValue(value, this.focusedElId);
-};
-
-commands.setGeoLocation = async function setGeoLocation(location) {
-  // TODO test this adequately once WD bug is fixed
-  this.appModel.lat = location.latitude;
-  this.appModel.long = location.longitude;
-};
-
-commands.getGeoLocation = async function getGeoLocation() {
-  return this.appModel.currentGeoLocation;
-};
-
-commands.getPageSource = async function getPageSource() {
-  return this.appModel.rawXml;
-};
-
-commands.getOrientation = async function getOrientation() {
-  return this.appModel.orientation;
-};
-
-commands.setOrientation = async function setOrientation(o) {
-  if (!_.includes(['LANDSCAPE', 'PORTRAIT'], o)) {
-    throw new errors.UnknownError('Orientation must be LANDSCAPE or PORTRAIT');
+const ORIENTATIONS = new Set(['LANDSCAPE', 'PORTRAIT']);
+
+/**
+ * @template {Class<import('../types').IContextsCommands & import('../types').IElementCommands>} T
+ * @param {T} Base
+ */
+export function GeneralMixin(Base) {
+  /**
+   * @implements {IGeneralCommands}
+   */
+  class GeneralCommands extends Base {
+    async title() {
+      this.assertWebviewContext();
+      return this.appModel.title;
+    }
+
+    async keys(value) {
+      if (!this.focusedElId) {
+        throw new errors.InvalidElementStateError();
+      }
+      await this.setValue(value, this.focusedElId);
+    }
+
+    async setGeoLocation(location) {
+      // TODO test this adequately once WD bug is fixed
+      this.appModel.lat = location.latitude;
+      this.appModel.long = location.longitude;
+    }
+
+    async getGeoLocation() {
+      return this.appModel.currentGeoLocation;
+    }
+
+    async getPageSource() {
+      return this.appModel.rawXml;
+    }
+
+    async getOrientation() {
+      return this.appModel.orientation;
+    }
+
+    /**
+     *
+     * @param {import('../types').FakeDriverCaps['orientation']} o
+     */
+    async setOrientation(o) {
+      if (!ORIENTATIONS.has(o)) {
+        throw new errors.UnknownError('Orientation must be LANDSCAPE or PORTRAIT');
+      }
+      this.appModel.orientation = o;
+    }
+
+    async getScreenshot() {
+      return this.appModel.getScreenshot();
+    }
+
+    async getWindowSize() {
+      return {width: this.appModel.width, height: this.appModel.height};
+    }
+
+    async getWindowRect() {
+      return {width: this.appModel.width, height: this.appModel.height, x: 0, y: 0};
+    }
+
+    async performActions(actions) {
+      this.appModel.actionLog.push(actions);
+    }
+
+    async releaseActions() {}
+
+    async getLog(type) {
+      switch (type) {
+        case 'actions':
+          return this.appModel.actionLog;
+        default:
+          throw new Error(`Don't understand log type '${type}'`);
+      }
+    }
+
+    async mobileShake() {
+      this.shook = true;
+    }
+
+    async doubleClick() {}
+
+    async execute(script, args) {
+      return await this.executeMethod(script, args);
+    }
+
+    /**
+     * Add two or maybe even three numbers
+     *
+     * @param {number} num1
+     * @param {number} num2
+     * @param {number} [num3]
+     * @returns {Promise<number>}
+     */
+    async fakeAddition(num1, num2, num3 = 0) {
+      return num1 + num2 + (num3 ?? 0);
+    }
   }
-  this.appModel.orientation = o;
-};
-
-commands.getScreenshot = async function getScreenshot() {
-  return this.appModel.getScreenshot();
-};
-
-commands.getWindowSize = async function getWindowSize() {
-  return {width: this.appModel.width, height: this.appModel.height};
-};
 
-commands.getWindowRect = async function getWindowRect() {
-  return {width: this.appModel.width, height: this.appModel.height, x: 0, y: 0};
-};
-
-commands.performActions = async function performActions(actions) {
-  this.appModel.actionLog.push(actions);
-};
-
-commands.releaseActions = async function releaseActions() {};
-
-commands.getLog = async function getLog(type) {
-  switch (type) {
-    case 'actions':
-      return this.appModel.actionLog;
-    default:
-      throw new Error(`Don't understand log type '${type}'`);
-  }
-};
+  return GeneralCommands;
+}
 
-commands.execute = async function execute(script, args) {
-  return await this.executeMethod(script, args);
-};
+/**
+ * @typedef {import('../driver').FakeDriverCore} FakeDriverCore
+ */
 
-commands.fakeAddition = async function fakeAddition(num1, num2, num3) {
-  return num1 + num2 + (num3 ?? 0);
-};
+/**
+ * @template T,[U={}],[V=Array<any>]
+ * @typedef {import('@appium/types').Class<T,U,V>} Class
+ */
 
-Object.assign(extensions, commands, helpers);
-export {commands, helpers};
-export default extensions;
+/**
+ * @typedef {import('../types').IGeneralCommands} IGeneralCommands
+ */

package/lib/commands/index.js

@@ -1,21 +1,16 @@
-import contextCommands from './contexts';
-import findCommands from './find';
-import elementCommands from './element';
-import generalCommands from './general';
-import alertCommands from './alert';
+import {AlertMixin} from './alert';
+import {ContextsMixin} from './contexts';
+import {ElementMixin} from './element';
+import {FindMixin} from './find';
+import {GeneralMixin} from './general';
 
-let commands = {};
-
-Object.assign(
-  commands,
-  contextCommands,
-  findCommands,
-  elementCommands,
-  generalCommands,
-  alertCommands
-);
-
-export default commands;
+/**
+ *
+ * @param {import('@appium/types').Class<import('../driver').FakeDriverCore>} Base
+ */
+export function FakeDriverMixin(Base) {
+  return GeneralMixin(FindMixin(ElementMixin(AlertMixin(ContextsMixin(Base)))));
+}
 
 /* // TODO:
   //rest.post('/wd/hub/session/:sessionId?/touch/click', controller.doClick);

package/lib/driver.js

@@ -1,28 +1,44 @@
 import B from 'bluebird';
-import _ from 'lodash';
 import {BaseDriver, errors} from 'appium/driver';
+import {deprecatedCommandsLogged} from '@appium/base-driver/build/lib/protocol/protocol';
 import {FakeApp} from './fake-app';
-import commands from './commands';
+import {FakeDriverMixin} from './commands';
+
+const FAKE_DRIVER_CONSTRAINTS = /** @type {const} */ ({
+  app: {
+    presence: true,
+    isString: true,
+  },
+  uniqueApp: {
+    isBoolean: true,
+  },
+});
+
+/**
+ * @typedef {typeof FAKE_DRIVER_CONSTRAINTS} FakeDriverConstraints
+ */
+
+/**
+ * @extends {BaseDriver<FakeDriverConstraints>}
+ * @implements {ExternalDriver<FakeDriverConstraints>}
+ */
+export class FakeDriverCore extends BaseDriver {
+  desiredCapConstraints = FAKE_DRIVER_CONSTRAINTS;
+
+  /** @type {string} */
+  curContext;
+
+  appModel = new FakeApp();
 
-class FakeDriver extends BaseDriver {
   constructor(opts = {}, shouldValidateCaps = true) {
     super(opts, shouldValidateCaps);
-    this.appModel = null;
     this.curContext = 'NATIVE_APP';
     this.elMap = {};
     this.focusedElId = null;
     this.maxElId = 0;
-    this.caps = {};
     this.fakeThing = null;
-    this.cliArgs = {};
     this._proxyActive = false;
-
-    this.desiredCapConstraints = {
-      app: {
-        presence: true,
-        isString: true,
-      },
-    };
+    this.shook = false;
   }
 
   proxyActive() {
@@ -42,22 +58,30 @@ class FakeDriver extends BaseDriver {
     res.status(200).send(JSON.stringify(resBodyObj));
   }
 
-  proxyCommand(/*url, method, body*/) {
-    return 'proxied via proxyCommand';
+  /**
+   * @template [T=any]
+   * @returns {Promise<T>}
+   */
+  async proxyCommand(/*url, method, body*/) {
+    return /** @type {T} */ (/** @type {unknown} */ ('proxied via proxyCommand'));
   }
 
-  async createSession(
-    jsonwpDesiredCapabilities,
-    jsonwpRequiredCaps,
-    w3cCapabilities,
-    otherSessionData = []
-  ) {
+  /**
+   * Comment for `createSession` in `FakeDriver`
+   * @param {W3CFakeDriverCaps} w3cCapabilities1 W3C Capabilities
+   * @param {W3CFakeDriverCaps} [w3cCapabilities2] W3C Capabilities
+   * @param {W3CFakeDriverCaps} [w3cCapabilities3] W3C Capabilities
+   * @param {import('@appium/types').DriverData[]} [driverData] Other session data
+   * @override
+   * @returns {Promise<[string,FakeDriverCaps]>} Session ID and normalized capabilities
+   */
+  async createSession(w3cCapabilities1, w3cCapabilities2, w3cCapabilities3, driverData = []) {
     // TODO add validation on caps.app that we will get for free from
     // BaseDriver
 
     // check to see if any other sessions have set uniqueApp. If so, emulate
     // not being able to start a session because of system resources
-    for (let d of otherSessionData) {
+    for (let d of driverData) {
       if (d.isUnique) {
         throw new errors.SessionNotCreatedError(
           'Cannot start session; another ' +
@@ -66,16 +90,9 @@ class FakeDriver extends BaseDriver {
       }
     }
 
-    let [sessionId, caps] = await super.createSession(
-      jsonwpDesiredCapabilities,
-      jsonwpRequiredCaps,
-      w3cCapabilities,
-      otherSessionData
+    let [sessionId, caps] = /** @type {[string, FakeDriverCaps]} */ (
+      await super.createSession(w3cCapabilities1, w3cCapabilities2, w3cCapabilities3, driverData)
     );
-    this.appModel = new FakeApp();
-    if (_.isArray(caps) === true && caps.length === 1) {
-      caps = caps[0];
-    }
     this.caps = caps;
     await this.appModel.loadApp(caps.app);
     return [sessionId, caps];
@@ -92,32 +109,75 @@ class FakeDriver extends BaseDriver {
     return this.fakeThing;
   }
 
+  /**
+   * Set the 'thing' value (so that it can be retrieved later)
+   *
+   * @param {any} thing
+   * @returns {Promise<null>}
+   */
   async setFakeThing(thing) {
     await B.delay(1);
     this.fakeThing = thing;
     return null;
   }
 
+  /**
+   * Get the driver args that were sent in via the CLI
+   *
+   * @returns {Promise<typeof this.cliArgs>}
+   */
   async getFakeDriverArgs() {
     await B.delay(1);
     return this.cliArgs;
   }
 
-  static newMethodMap = {
+  /**
+   * This is a command that will return a list of deprecated command names called
+   *
+   * @returns {Promise<string[]>}
+   */
+  async getDeprecatedCommandsCalled() {
+    await B.delay(1);
+    return Array.from(deprecatedCommandsLogged);
+  }
+
+  /**
+   * This is a command that exists just to be an example of a deprecated command
+   *
+   * @returns {Promise<void>}
+   */
+  async callDeprecatedCommand() {
+    await B.delay(1);
+  }
+
+  static newMethodMap = /** @type {const} */ ({
     '/session/:sessionId/fakedriver': {
       GET: {command: 'getFakeThing'},
+      /**
+       * Sets a fake thing
+       */
       POST: {command: 'setFakeThing', payloadParams: {required: ['thing']}},
     },
     '/session/:sessionId/fakedriverargs': {
       GET: {command: 'getFakeDriverArgs'},
     },
-  };
+    '/session/:sessionId/deprecated': {
+      POST: {command: 'callDeprecatedCommand', deprecated: true},
+    },
+    // this next one exists to override a deprecated method
+    '/session/:sessionId/doubleclick': {
+      POST: {command: 'doubleClick'},
+    },
+  });
 
-  static executeMethodMap = {
+  static executeMethodMap = /** @type {const} */ ({
     'fake: addition': {
       command: 'fakeAddition',
       params: {required: ['num1', 'num2'], optional: ['num3']},
     },
+    /**
+     * Gets a thing (a fake thing)
+     */
     'fake: getThing': {
       command: 'getFakeThing',
     },
@@ -125,7 +185,23 @@ class FakeDriver extends BaseDriver {
       command: 'setFakeThing',
       params: {required: ['thing']},
     },
-  };
+    'fake: getDeprecatedCommandsCalled': {
+      command: 'getDeprecatedCommandsCalled',
+    },
+  });
+
+  /**
+   * Add two or maybe even three numbers
+   *
+   * @param {number} num1
+   * @param {number} num2
+   * @param {number} [num3]
+   * @returns {Promise<number>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async fakeAddition(num1, num2, num3 = 0) {
+    throw new errors.NotImplementedError();
+  }
 
   static fakeRoute(req, res) {
     res.send(JSON.stringify({fakedriver: 'fakeResponse'}));
@@ -133,13 +209,30 @@ class FakeDriver extends BaseDriver {
 
   static async updateServer(expressApp, httpServer, cliArgs) {
     // eslint-disable-line require-await
-    expressApp.all('/fakedriver', FakeDriver.fakeRoute);
+    expressApp.all('/fakedriver', FakeDriverCore.fakeRoute);
     expressApp.all('/fakedriverCliArgs', (req, res) => {
       res.send(JSON.stringify(cliArgs));
     });
   }
 }
 
-Object.assign(FakeDriver.prototype, commands);
-
-export {FakeDriver};
+/**
+ * @extends FakeDriverCore
+ */
+export class FakeDriver extends FakeDriverMixin(FakeDriverCore) {}
+export default FakeDriver;
+
+/**
+ * @typedef {import('./types').FakeDriverCaps} FakeDriverCaps
+ * @typedef {import('./types').W3CFakeDriverCaps} W3CFakeDriverCaps
+ */
+
+/**
+ * @template {import('@appium/types').Driver} D
+ * @typedef {import('@appium/types').DriverClass<D>} DriverClass
+ */
+
+/**
+ * @template {import('@appium/types').Constraints} C
+ * @typedef {import('@appium/types').ExternalDriver<C>} ExternalDriver
+ */

package/lib/fake-app.js

@@ -29,9 +29,13 @@ class FakeApp {
     if (nodes.length < 1) {
       throw new Error('No title!');
     }
-    return nodes[0].firstChild.data;
+    const node = /** @type {Node} */ (nodes[0]);
+    return /** @type {ElementWithData} */ (node.firstChild).data;
   }
 
+  /**
+   * @type {import('@appium/types').Location}
+   */
   get currentGeoLocation() {
     return {
       latitude: this.lat,
@@ -47,18 +51,24 @@ class FakeApp {
     this.currentOrientation = o;
   }
 
+  /**
+   * @type {number}
+   */
   get width() {
     if (this._width === null) {
       this.setDims();
     }
-    return this._width;
+    return /** @type {number} */ (this._width);
   }
 
+  /**
+   * @type {number}
+   */
   get height() {
     if (this._width === null) {
       this.setDims();
     }
-    return this._width;
+    return /** @type {number} */ (this._width);
   }
 
   setDims() {
@@ -133,10 +143,10 @@ class FakeApp {
   }
 
   setAlertText(text) {
-    if (!this.activeAlert.hasPrompt()) {
+    if (!this.activeAlert?.hasPrompt()) {
       throw new Error('No prompt to set text of');
     }
-    this.activeAlert.setAttr('prompt', text);
+    this.activeAlert?.setAttr('prompt', text);
   }
 
   showAlert(alertId) {
@@ -148,7 +158,7 @@ class FakeApp {
   }
 
   alertText() {
-    return this.activeAlert.getAttr('prompt') || this.activeAlert.nodeAttrs.text;
+    return this.activeAlert?.getAttr('prompt') || this.activeAlert?.nodeAttrs.text;
   }
 
   handleAlert() {
@@ -167,3 +177,7 @@ class FakeWebView {
 }
 
 export {FakeApp};
+
+/**
+ * @typedef {Element & {data: any}} ElementWithData
+ */

package/lib/index.js

@@ -1,20 +1,22 @@
-import * as driver from './driver';
-import * as server from './server';
-
-const {FakeDriver} = driver;
-const {startServer} = server;
+import {FakeDriver} from './driver';
+import {startServer} from './server';
 
 const DEFAULT_HOST = 'localhost';
 const DEFAULT_PORT = 4774;
 
 async function main() {
-  const getArgValue = (argName) => {
+  const getArgValue = (/** @type {string} */ argName) => {
     const argIndex = process.argv.indexOf(argName);
     return argIndex > 0 ? process.argv[argIndex + 1] : null;
   };
-  const port = parseInt(getArgValue('--port'), 10) || DEFAULT_PORT;
+  const port = parseInt(String(getArgValue('--port')), 10) || DEFAULT_PORT;
   const host = getArgValue('--host') || DEFAULT_HOST;
   return await startServer(port, host);
 }
 
 export {FakeDriver, startServer, main};
+
+/**
+ * @typedef {import('./types').W3CFakeDriverCaps} W3CFakeDriverCaps
+ * @typedef {import('./types').FakeDriverCaps} FakeDriverCaps
+ */

package/lib/types.ts

@@ -0,0 +1,42 @@
+import type {DriverCaps, ExternalDriver, W3CDriverCaps} from '@appium/types';
+import type {FakeDriverConstraints} from './driver';
+import {FakeApp} from './fake-app';
+import {FakeElement} from './fake-element';
+
+/**
+ * W3C-style caps for {@link FakeDriver}
+ * @public
+ */
+export type W3CFakeDriverCaps = W3CDriverCaps<FakeDriverConstraints>;
+
+/**
+ * Capabilities for {@link FakeDriver}
+ * @public
+ */
+export type FakeDriverCaps = DriverCaps<FakeDriverConstraints>;
+
+export interface IFakeDriver extends ExternalDriver<FakeDriverConstraints> {
+  elMap: Record<string, FakeElement>;
+  maxElId: number;
+  appModel: FakeApp;
+  focusedElId: string;
+  curContext: string;
+}
+
+export interface IGeneralCommands extends IFakeDriver {
+  fakeAddition(num1: number, num2: number, num3?: number): Promise<number>;
+}
+
+export interface IContextsCommands extends IFakeDriver {
+  assertWebviewContext(): void;
+}
+
+export interface IElementCommands extends IFakeDriver {
+  getElement(id: string): FakeElement;
+  getElements(ids: string[]): FakeElement[];
+  setValue(text: string, id: string): Promise<void>;
+}
+
+export interface IAlertCommands extends IFakeDriver {
+  assertNoAlert(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/fake-driver",
-  "version": "4.2.2",
+  "version": "5.1.0",
   "description": "Mock driver used internally by Appium for testing. Ignore",
   "keywords": [
     "automation",
@@ -33,23 +33,21 @@
     "index.js",
     "lib",
     "build",
-    "test/fixtures"
+    "test/fixtures",
+    "tsconfig.json"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib --copy-files",
-    "dev": "npm run build -- --watch",
-    "fix": "npm run lint -- --fix",
-    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
-    "prepare": "npm run build",
+    "build": "cpy lib/screen.png build",
+    "clean": "npx rimraf build/lib/screen.png",
     "test": "npm run test:unit",
     "test:e2e": "mocha --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
     "test:smoke": "node ./build/lib/index.js",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@types/bluebird": "3.5.37",
-    "@xmldom/xmldom": "0.8.3",
-    "asyncbox": "2.9.2",
+    "@types/bluebird": "3.5.38",
+    "@xmldom/xmldom": "0.8.6",
+    "asyncbox": "2.9.4",
     "bluebird": "3.7.2",
     "lodash": "4.17.21",
     "source-map-support": "0.5.21",
@@ -59,7 +57,7 @@
     "appium": "^2.0.0-beta.35"
   },
   "engines": {
-    "node": ">=14",
+    "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
     "npm": ">=8"
   },
   "publishConfig": {
@@ -79,6 +77,9 @@
       "fake-success": "./build/lib/scripts/fake-success.js"
     }
   },
+  "typedoc": {
+    "entryPoint": "./lib/index.js"
+  },
   "types": "./build/lib/index.d.ts",
-  "gitHead": "f545a6cde58d83f3289072f8957468793947ba66"
+  "gitHead": "422142302f2f540a31c7eaf5178e2642b53a30d2"
 }