@appium/fake-driver 5.1.5 → 5.2.1

package/lib/commands/find.ts

@@ -0,0 +1,137 @@
+import _ from 'lodash';
+import {Element} from '@appium/types';
+import {errors} from 'appium/driver';
+import {FakeElement} from '../fake-element';
+import {FakeDriver} from '../driver';
+import {util} from '@appium/support';
+import {mixin} from './mixin';
+
+const {W3C_WEB_ELEMENT_IDENTIFIER} = util;
+interface FakeDriverFindMixin {
+  getExistingElementForNode(node: FakeElement): string | null;
+  wrapNewEl(obj: FakeElement): Element;
+
+  findElOrEls<Many extends boolean, Ctx = any>(
+    this: FakeDriver,
+    strategy: string,
+    selector: string,
+    many: Many,
+    context?: Ctx
+  ): Promise<Many extends true ? Element[] : Element>;
+  findElement(strategy: string, selector: string): Promise<Element>;
+  findElements(strategy: string, selector: string): Promise<Element[]>;
+  findElementFromElement(elementId: string, strategy: string, selector: string): Promise<Element>;
+  findElementsFromElement(
+    elementId: string,
+    strategy: string,
+    selector: string
+  ): Promise<Element[]>;
+}
+
+declare module '../driver' {
+  interface FakeDriver extends FakeDriverFindMixin {}
+}
+
+const FindMixin: FakeDriverFindMixin = {
+  getExistingElementForNode(this: FakeDriver, node) {
+    for (const [id, el] of _.toPairs(this.elMap)) {
+      if (el.node === node) {
+        return id;
+      }
+    }
+    return null;
+  },
+
+  wrapNewEl(this: FakeDriver, obj: FakeElement): Element {
+    // first check and see if we already have a ref to this element
+    const existingElId = this.getExistingElementForNode(obj);
+    if (existingElId) {
+      return {ELEMENT: existingElId, [W3C_WEB_ELEMENT_IDENTIFIER]: existingElId};
+    }
+
+    // otherwise add the element to the map
+    this.maxElId++;
+    const maxElId = this.maxElId.toString();
+    this.elMap[maxElId] = new FakeElement(obj, this.appModel);
+    return {ELEMENT: maxElId, [W3C_WEB_ELEMENT_IDENTIFIER]: maxElId};
+  },
+
+  async findElOrEls<Many extends boolean, Ctx = any>(
+    this: FakeDriver,
+    strategy: string,
+    selector: string,
+    many: Many,
+    context: Ctx
+  ): Promise<Many extends true ? Element[] : Element> {
+    const qMap = {
+      xpath: 'xpathQuery',
+      id: 'idQuery',
+      'accessibility id': 'idQuery',
+      'class name': 'classQuery',
+      'tag name': 'classQuery',
+      'css selector': 'cssQuery',
+    } as Record<string, keyof FakeDriver['appModel']>;
+    // TODO this error checking should probably be part of MJSONWP?
+    if (!_.includes(_.keys(qMap), strategy)) {
+      throw new errors.UnknownCommandError();
+    }
+    if (selector === 'badsel') {
+      throw new errors.InvalidSelectorError();
+    }
+    const els = this.appModel[qMap[strategy]](selector, context);
+
+    let retval: Element | Element[];
+    if (els.length) {
+      if (many) {
+        const allEls: Element[] = [];
+        for (const el of els) {
+          allEls.push(this.wrapNewEl(el));
+        }
+        retval = allEls;
+      } else {
+        retval = this.wrapNewEl(els[0]);
+      }
+    } else if (many) {
+      retval = [];
+    } else {
+      throw new errors.NoSuchElementError();
+    }
+    return retval as Many extends true ? Element[] : Element;
+  },
+
+  /**
+   * This should override whatever's in ExternalDriver
+   * @param {string} strategy Strategy
+   * @param {string} selector Selector
+   * @this {FakeDriver}
+   */
+  async findElement(this: FakeDriver, strategy: string, selector: string) {
+    return this.findElOrEls(strategy, selector, false);
+  },
+
+  async findElements(this: FakeDriver, strategy: string, selector: string) {
+    return this.findElOrEls(strategy, selector, true);
+  },
+
+  async findElementFromElement(
+    this: FakeDriver,
+    strategy: string,
+    selector: string,
+    elementId: string
+  ) {
+    const el = this.getElement(elementId);
+    return this.findElOrEls(strategy, selector, false, el.xmlFragment);
+  },
+
+  async findElementsFromElement(
+    this: FakeDriver,
+    strategy: string,
+    selector: string,
+    elementId: string
+  ) {
+    const el = this.getElement(elementId);
+    return this.findElOrEls(strategy, selector, true, el.xmlFragment);
+  },
+};
+
+mixin(FindMixin);

package/lib/commands/general.ts

@@ -0,0 +1,115 @@
+import {ActionSequence, Location, Rect, Size} from '@appium/types';
+import {errors} from 'appium/driver';
+import {FakeDriver, Orientation} from '../driver';
+import {mixin} from './mixin';
+
+const ORIENTATIONS = new Set(['LANDSCAPE', 'PORTRAIT']);
+
+interface FakeDriverGeneralMixin {
+  title(): Promise<string>;
+  keys(value: string | string[]): Promise<void>;
+  setGeoLocation(location: Location): Promise<void>;
+  getGeoLocation(): Promise<Location>;
+  getPageSource(): Promise<string>;
+  getOrientation(): Promise<string>;
+  setOrientation(orientation: Orientation): Promise<void>;
+  getScreenshot(): Promise<string>;
+  getWindowSize(): Promise<Size>;
+  getWindowRect(): Promise<Rect>;
+  performActions(actions: ActionSequence[]): Promise<void>;
+  releaseActions(): Promise<void>;
+  mobileShake(): Promise<void>;
+  doubleClick(): Promise<void>;
+  execute(script: string, args: any[]): Promise<any>;
+  fakeAddition(a: number, b: number, c?: number): Promise<number>;
+  getLog(type: string): Promise<any[]>;
+}
+
+declare module '../driver' {
+  interface FakeDriver extends FakeDriverGeneralMixin {}
+}
+
+const GeneralMixin: FakeDriverGeneralMixin = {
+  async title(this: FakeDriver) {
+    this.assertWebviewContext();
+    return this.appModel.title;
+  },
+
+  async keys(this: FakeDriver, value: string | string[]) {
+    if (!this.focusedElId) {
+      throw new errors.InvalidElementStateError();
+    }
+    await this.setValue(value, this.focusedElId);
+  },
+
+  async setGeoLocation(this: FakeDriver, location: Location) {
+    // TODO test this adequately once WD bug is fixed
+    this.appModel.lat = location.latitude;
+    this.appModel.long = location.longitude;
+  },
+
+  async getGeoLocation(this: FakeDriver) {
+    return this.appModel.currentGeoLocation;
+  },
+
+  async getPageSource(this: FakeDriver) {
+    return this.appModel.rawXml;
+  },
+
+  async getOrientation(this: FakeDriver) {
+    return this.appModel.orientation;
+  },
+
+  async setOrientation(this: FakeDriver, o: Orientation) {
+    if (!ORIENTATIONS.has(o)) {
+      throw new errors.UnknownError('Orientation must be LANDSCAPE or PORTRAIT');
+    }
+    this.appModel.orientation = o;
+  },
+
+  async getScreenshot(this: FakeDriver) {
+    return this.appModel.getScreenshot();
+  },
+
+  async getWindowSize(this: FakeDriver) {
+    return {width: this.appModel.width, height: this.appModel.height};
+  },
+
+  async getWindowRect(this: FakeDriver) {
+    return {width: this.appModel.width, height: this.appModel.height, x: 0, y: 0};
+  },
+
+  async performActions(this: FakeDriver, actions: ActionSequence[]) {
+    this.appModel.actionLog.push(actions);
+  },
+
+  async releaseActions(this: FakeDriver) {},
+
+  async getLog(this: FakeDriver, type: string): Promise<ActionSequence[][]> {
+    switch (type) {
+      case 'actions':
+        return this.appModel.actionLog;
+      default:
+        throw new Error(`Don't understand log type '${type}'`);
+    }
+  },
+
+  async mobileShake(this: FakeDriver) {
+    this.shook = true;
+  },
+
+  async doubleClick(this: FakeDriver) {},
+
+  async execute(this: FakeDriver, script: string, args: any[]) {
+    return await this.executeMethod(script, args);
+  },
+
+  /**
+   * Add two or maybe even three numbers
+   */
+  async fakeAddition(this: FakeDriver, num1: number, num2: number, num3 = 0) {
+    return num1 + num2 + (num3 ?? 0);
+  },
+};
+
+mixin(GeneralMixin);

package/lib/commands/{index.js → index.ts}

@@ -1,8 +1,17 @@
-export {default as alert} from './alert';
-export {default as contexts} from './contexts';
-export {default as element} from './element';
-export {default as find} from './find';
-export {default as general} from './general';
+/**
+ * Export all of the "stuff" from these mixin files.  The mixins themselves are not exported,
+ * but any types/interfaces that they export (e.g., options objects for some command) are exported.
+ *
+ * Mixins must not use `Object.assign()` and are expected to use the `mixin` function in the sibling
+ * `mixin` module.
+ * @module
+ */
+
+export * from './alert';
+export * from './contexts';
+export * from './element';
+export * from './find';
+export * from './general';
 
 /* // TODO:
   //rest.post('/wd/hub/session/:sessionId?/touch/click', controller.doClick);

package/lib/commands/mixin.ts

@@ -0,0 +1,13 @@
+import {FakeDriver} from '../driver';
+
+/**
+ * This function assigns a mixin `T` to the `FakeDriver` class' prototype.
+ * While each mixin has its own interface which is (in isolation) unrelated to `FakeDriver`, the constraint
+ * on this generic type `T` is that it must be a partial of `FakeDriver`'s interface. This enforces
+ * that it does not conflict with the existing interface of `FakeDriver`.  In that way, you can
+ * think of it as a type guard.
+ * @param mixin Mixin implementation
+ */
+export function mixin<T extends Partial<FakeDriver>>(mixin: T): void {
+  Object.assign(FakeDriver.prototype, mixin);
+}

package/lib/driver.js

@@ -2,7 +2,6 @@ import B from 'bluebird';
 import {BaseDriver, errors} from 'appium/driver';
 import {deprecatedCommandsLogged} from '@appium/base-driver/build/lib/protocol/protocol';
 import {FakeApp} from './fake-app';
-import {alert, contexts, element, find, general} from './commands';
 
 const FAKE_DRIVER_CONSTRAINTS = /** @type {const} */ ({
   app: {
@@ -15,22 +14,50 @@ const FAKE_DRIVER_CONSTRAINTS = /** @type {const} */ ({
 });
 
 /**
+ * Constraints for {@linkcode FakeDriver}'s capabilites
  * @typedef {typeof FAKE_DRIVER_CONSTRAINTS} FakeDriverConstraints
  */
 
 /**
+ * @template [Thing=any]
  * @extends {BaseDriver<FakeDriverConstraints>}
  * @implements {ExternalDriver<FakeDriverConstraints>}
  */
 export class FakeDriver extends BaseDriver {
-  desiredCapConstraints = FAKE_DRIVER_CONSTRAINTS;
+  /**
+   * @type {FakeDriverConstraints}
+   * @readonly
+   */
+  desiredCapConstraints;
 
   /** @type {string} */
   curContext;
 
-  appModel = new FakeApp();
+  /** @type {FakeApp} */
+  appModel;
+
+  /** @type {boolean} */
+  _proxyActive;
+
+  /** @type {boolean} */
+  shook;
+
+  /** @type {string?} */
+  focusedElId;
+
+  /** @type {Thing?} */
+  fakeThing;
+
+  /** @type {number} */
+  maxElId;
 
-  constructor(opts = {}, shouldValidateCaps = true) {
+  /** @type {Record<string,import('./fake-element').FakeElement>} */
+  elMap;
+
+  constructor(
+    opts = /** @type {import('@appium/types').DriverOpts<FakeDriverConstraints>} */ ({}),
+    shouldValidateCaps = true
+  ) {
     super(opts, shouldValidateCaps);
     this.curContext = 'NATIVE_APP';
     this.elMap = {};
@@ -39,6 +66,8 @@ export class FakeDriver extends BaseDriver {
     this.fakeThing = null;
     this._proxyActive = false;
     this.shook = false;
+    this.appModel = new FakeApp();
+    this.desiredCapConstraints = FAKE_DRIVER_CONSTRAINTS;
   }
 
   proxyActive() {
@@ -73,7 +102,7 @@ export class FakeDriver extends BaseDriver {
    * @param {W3CFakeDriverCaps} [w3cCapabilities3] W3C Capabilities
    * @param {import('@appium/types').DriverData[]} [driverData] Other session data
    * @override
-   * @returns {Promise<[string,FakeDriverCaps]>} Session ID and normalized capabilities
+   * @returns {Promise<[string,FakeDriverCaps]>}
    */
   async createSession(w3cCapabilities1, w3cCapabilities2, w3cCapabilities3, driverData = []) {
     // TODO add validation on caps.app that we will get for free from
@@ -112,7 +141,7 @@ export class FakeDriver extends BaseDriver {
   /**
    * Set the 'thing' value (so that it can be retrieved later)
    *
-   * @param {any} thing
+   * @param {Thing} thing
    * @returns {Promise<null>}
    */
   async setFakeThing(thing) {
@@ -201,86 +230,17 @@ export class FakeDriver extends BaseDriver {
       res.send(JSON.stringify(cliArgs));
     });
   }
-
-  /*********
-   * ALERT *
-   *********/
-  assertNoAlert = alert.assertNoAlert;
-  assertAlert = alert.assertAlert;
-  getAlertText = alert.getAlertText;
-  setAlertText = alert.setAlertText;
-  postAcceptAlert = alert.postAcceptAlert;
-  postDismissAlert = alert.postDismissAlert;
-
-  /************
-   * CONTEXTS *
-   ************/
-  getRawContexts = contexts.getRawContexts;
-  assertWebviewContext = contexts.assertWebviewContext;
-  getCurrentContext = contexts.getCurrentContext;
-  getContexts = contexts.getContexts;
-  setContext = contexts.setContext;
-  setFrame = contexts.setFrame;
-
-  /************
-   * ELEMENTS *
-   ************/
-  getElements = element.getElements;
-  getElement = element.getElement;
-  getName = element.getName;
-  elementDisplayed = element.elementDisplayed;
-  elementEnabled = element.elementEnabled;
-  elementSelected = element.elementSelected;
-  setValue = element.setValue;
-  getText = element.getText;
-  clear = element.clear;
-  click = element.click;
-  getAttribute = element.getAttribute;
-  getElementRect = element.getElementRect;
-  getSize = element.getSize;
-  equalsElement = element.equalsElement;
-  getCssProperty = element.getCssProperty;
-  getLocation = element.getLocation;
-  getLocationInView = element.getLocationInView;
-
-  /********
-   * FIND *
-   ********/
-  getExistingElementForNode = find.getExistingElementForNode;
-  wrapNewEl = find.wrapNewEl;
-  findElOrEls = find.findElOrEls;
-  findElement = find.findElement;
-  findElements = find.findElements;
-  findElementFromElement = find.findElementFromElement;
-  findElementsFromElement = find.findElementsFromElement;
-
-  /***********
-   * GENERAL *
-   ***********/
-  title = general.title;
-  keys = general.keys;
-  setGeoLocation = general.setGeoLocation;
-  getGeoLocation = general.getGeoLocation;
-  getPageSource = general.getPageSource;
-  getOrientation = general.getOrientation;
-  setOrientation = general.setOrientation;
-  getScreenshot = general.getScreenshot;
-  getWindowSize = general.getWindowSize;
-  getWindowRect = general.getWindowRect;
-  performActions = general.performActions;
-  getLog = general.getLog;
-  mobileShake = general.mobileShake;
-  doubleClick = general.doubleClick;
-  execute = general.execute;
-  fakeAddition = general.fakeAddition;
-  releaseActions = general.releaseActions;
 }
 
+// eslint-disable-next-line import/no-unresolved
+export * from './commands';
+
 export default FakeDriver;
 
 /**
  * @typedef {import('./types').FakeDriverCaps} FakeDriverCaps
  * @typedef {import('./types').W3CFakeDriverCaps} W3CFakeDriverCaps
+ * @typedef {import('@appium/types').Element} Element
  */
 
 /**
@@ -292,3 +252,7 @@ export default FakeDriver;
  * @template {import('@appium/types').Constraints} C
  * @typedef {import('@appium/types').ExternalDriver<C>} ExternalDriver
  */
+
+/**
+ * @typedef {import('@appium/types').Orientation} Orientation
+ */

package/lib/fake-app.js

@@ -8,7 +8,7 @@ import {FakeElement} from './fake-element';
 
 const SCREENSHOT = path.join(__dirname, 'screen.png');
 
-class FakeApp {
+export class FakeApp {
   constructor() {
     this.dom = null;
     this.activeDom = null;
@@ -20,7 +20,9 @@ class FakeApp {
     this._width = null;
     this._height = null;
     this.rawXml = '';
+    /** @type {import('./driver').Orientation} */
     this.currentOrientation = 'PORTRAIT';
+    /** @type {import('@appium/types').ActionSequence[][]} */
     this.actionLog = [];
   }
 
@@ -176,8 +178,6 @@ class FakeWebView {
   }
 }
 
-export {FakeApp};
-
 /**
  * @typedef {Element & {data: any}} ElementWithData
  */

package/lib/fake-element.js

@@ -1,7 +1,20 @@
 import _ from 'lodash';
 import XMLDom from '@xmldom/xmldom';
 
-class FakeElement {
+export class FakeElement {
+  /** @type {FakeApp} */
+  app;
+
+  /** @type {string} */
+  type;
+
+  /** @type {Record<string,string>} */
+  nodeAttrs;
+
+  /**
+   * @param {any} xmlNode
+   * @param {FakeApp} app
+   */
   constructor(xmlNode, app) {
     this.app = app;
     this.node = xmlNode;
@@ -53,8 +66,8 @@ class FakeElement {
 
   getLocation() {
     return {
-      x: parseFloat(this.nodeAttrs.left || 0),
-      y: parseFloat(this.nodeAttrs.top || 0),
+      x: parseFloat(this.nodeAttrs.left || '0'),
+      y: parseFloat(this.nodeAttrs.top || '0'),
     };
   }
 
@@ -64,8 +77,8 @@ class FakeElement {
 
   getSize() {
     return {
-      width: parseFloat(this.nodeAttrs.width || 0),
-      height: parseFloat(this.nodeAttrs.height || 0),
+      width: parseFloat(this.nodeAttrs.width || '0'),
+      height: parseFloat(this.nodeAttrs.height || '0'),
     };
   }
 
@@ -99,4 +112,6 @@ class FakeElement {
   }
 }
 
-export {FakeElement};
+/**
+ * @typedef {import('./fake-app').FakeApp} FakeApp
+ */

package/lib/scripts/fake-error.js

@@ -1 +1,8 @@
-throw Error('Unsuccessfully ran the script');
+import ora from 'ora';
+
+const spinner = ora('Running fake-error...').start();
+
+setTimeout(() => {
+  spinner.fail('Oh nooooooo!');
+  throw Error('Unsuccessfully ran the script');
+}, 1000);

package/lib/scripts/fake-stdin.js

@@ -0,0 +1,9 @@
+import readline from 'node:readline';
+
+const rl = readline.createInterface({input: process.stdin, output: process.stderr});
+
+rl.question('Press ENTER to continue: ', () => {
+  rl.close();
+  // eslint-disable-next-line no-console
+  console.error('You did it!');
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/fake-driver",
-  "version": "5.1.5",
+  "version": "5.2.1",
   "description": "Mock driver used internally by Appium for testing. Ignore",
   "keywords": [
     "automation",
@@ -75,12 +75,13 @@
     "schema": "./build/lib/fake-driver-schema.js",
     "scripts": {
       "fake-error": "./build/lib/scripts/fake-error.js",
-      "fake-success": "./build/lib/scripts/fake-success.js"
+      "fake-success": "./build/lib/scripts/fake-success.js",
+      "fake-stdin": "./build/lib/scripts/fake-stdin.js"
     }
   },
   "typedoc": {
     "entryPoint": "./lib/index.js"
   },
   "types": "./build/lib/index.d.ts",
-  "gitHead": "322363b8876a7ea7b630d538e22965f7bab0ea06"
+  "gitHead": "872b924a97c13142bdb8bf4218a4db324f309ce4"
 }

package/lib/commands/alert.js

@@ -1,73 +0,0 @@
-import {errors} from 'appium/driver';
-
-export default {
-  /**
-   * @this {FakeDriver}
-   */
-  assertNoAlert() {
-    if (this.appModel.hasAlert()) {
-      throw new errors.UnexpectedAlertOpenError();
-    }
-  },
-
-  /**
-   * @this {FakeDriver}
-   */
-  assertAlert() {
-    if (!this.appModel.hasAlert()) {
-      throw new errors.NoAlertOpenError();
-    }
-  },
-
-  /**
-   * Get the text of an alert
-   *
-   * @returns {Promise<string>}
-   * @this {FakeDriver}
-   */
-  async getAlertText() {
-    this.assertAlert();
-    return this.appModel.alertText();
-  },
-
-  /**
-   * Set the text of an alert
-   *
-   * @param {string} text
-   * @returns {Promise<void>}
-   * @this {FakeDriver}
-   */
-  async setAlertText(text) {
-    this.assertAlert();
-    try {
-      this.appModel.setAlertText(text);
-    } catch (e) {
-      throw new errors.InvalidElementStateError();
-    }
-  },
-
-  /**
-   * Accept an alert
-   *
-   * @returns {Promise<void>}
-   * @this {FakeDriver}
-   */
-  async postAcceptAlert() {
-    this.assertAlert();
-    this.appModel.handleAlert();
-  },
-
-  /**
-   * Dismiss an alert
-   *
-   * @returns {Promise<void>}
-   * @this {FakeDriver}
-   */
-  async postDismissAlert() {
-    return this.postAcceptAlert();
-  },
-};
-
-/**
- * @typedef {import('../driver').FakeDriver} FakeDriver
- */