@appium/fake-driver 5.2.0 → 5.2.2

package/lib/commands/alert.ts

@@ -0,0 +1,70 @@
+import {FakeDriver} from '../driver';
+import {errors} from 'appium/driver';
+import {mixin} from './mixin';
+
+interface FakeDriverAlertMixin {
+  assertNoAlert(): void;
+  assertAlert(): void;
+
+  getAlertText(): Promise<string>;
+
+  setAlertText(text: string): Promise<void>;
+
+  postAcceptAlert(): Promise<void>;
+  postDismissAlert(): Promise<void>;
+}
+
+declare module '../driver' {
+  interface FakeDriver extends FakeDriverAlertMixin {}
+}
+
+const AlertMixin: FakeDriverAlertMixin = {
+  assertNoAlert(this: FakeDriver) {
+    if (this.appModel.hasAlert()) {
+      throw new errors.UnexpectedAlertOpenError();
+    }
+  },
+
+  assertAlert(this: FakeDriver) {
+    if (!this.appModel.hasAlert()) {
+      throw new errors.NoAlertOpenError();
+    }
+  },
+
+  /**
+   * Get the text of an alert
+   */
+  async getAlertText(this: FakeDriver) {
+    this.assertAlert();
+    return this.appModel.alertText();
+  },
+
+  /**
+   * Set the text of an alert
+   */
+  async setAlertText(this: FakeDriver, text: string) {
+    this.assertAlert();
+    try {
+      this.appModel.setAlertText(text);
+    } catch (e) {
+      throw new errors.InvalidElementStateError();
+    }
+  },
+
+  /**
+   * Accept an alert
+   */
+  async postAcceptAlert(this: FakeDriver) {
+    this.assertAlert();
+    this.appModel.handleAlert();
+  },
+
+  /**
+   * Dismiss an alert
+   */
+  async postDismissAlert(this: FakeDriver) {
+    return this.postAcceptAlert();
+  },
+};
+
+mixin(AlertMixin);

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

@@ -1,55 +1,53 @@
 import _ from 'lodash';
+import {FakeDriver} from '../driver';
 import {errors} from 'appium/driver';
+import {mixin} from './mixin';
+interface FakeDriverContextsMixin {
+  getRawContexts(): Record<string, any>;
+  assertWebviewContext(): void;
+  getCurrentContext(): Promise<string>;
+  getContexts(): Promise<string[]>;
+  setContext(context: string): Promise<void>;
+  setFrame(frame: number | null): Promise<void>;
+}
+declare module '../driver' {
+  interface FakeDriver extends FakeDriverContextsMixin {}
+}
 
-export default {
-  /**
-   * @this {FakeDriver}
-   */
-  getRawContexts() {
-    let contexts = {NATIVE_APP: null, PROXY: null};
-    let wvs = this.appModel?.getWebviews() ?? [];
+const ContextsMixin: FakeDriverContextsMixin = {
+  getRawContexts(this: FakeDriver) {
+    const contexts = {NATIVE_APP: null, PROXY: null};
+    const wvs = this.appModel.getWebviews() ?? [];
     for (let i = 1; i < wvs.length + 1; i++) {
       contexts[`WEBVIEW_${i}`] = wvs[i - 1];
     }
     return contexts;
   },
 
-  /**
-   * @this {FakeDriver}
-   */
-  assertWebviewContext() {
+  assertWebviewContext(this: FakeDriver) {
     if (this.curContext === 'NATIVE_APP') {
       throw new errors.InvalidContextError();
     }
   },
 
-  /**
-   * @returns {Promise<string>}
-   * @this {FakeDriver}
-   */
-  async getCurrentContext() {
+  async getCurrentContext(this: FakeDriver): Promise<string> {
     return this.curContext;
   },
 
   /**
    * Get the list of available contexts
-   *
-   * @returns {Promise<string[]>}
-   * @this {FakeDriver}
    */
-  async getContexts() {
+  async getContexts(this: FakeDriver) {
     return _.keys(this.getRawContexts());
   },
 
   /**
    * Set the current context
    *
-   * @param {string} context - name of the context
-   * @returns {Promise<void>}
-   * @this {FakeDriver}
+   * @param context - name of the context
    */
-  async setContext(context) {
-    let contexts = this.getRawContexts();
+  async setContext(this: FakeDriver, context: string) {
+    const contexts = this.getRawContexts();
     if (context in contexts) {
       this.curContext = context;
       if (context === 'NATIVE_APP') {
@@ -68,17 +66,13 @@ export default {
 
   /**
    * Set the active frame
-   *
-   * @param {number} frameId
-   * @returns {Promise<void>}
-   * @this {FakeDriver}
    */
-  async setFrame(frameId) {
+  async setFrame(this: FakeDriver, frameId: number | null) {
     this.assertWebviewContext();
     if (frameId === null) {
       this.appModel.deactivateFrame();
     } else {
-      let nodes = this.appModel.xpathQuery(`//iframe[@id="${frameId}"]`);
+      const nodes = this.appModel.xpathQuery(`//iframe[@id="${frameId}"]`);
       if (!nodes.length) {
         throw new errors.NoSuchFrameError();
       }
@@ -87,6 +81,4 @@ export default {
   },
 };
 
-/**
- * @typedef {import('../driver').FakeDriver} FakeDriver
- */
+mixin(ContextsMixin);

package/lib/commands/element.ts

@@ -0,0 +1,138 @@
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+import {FakeDriver} from '../driver';
+import {Position, Rect, Size} from '@appium/types';
+import {FakeElement} from '../fake-element';
+import {mixin} from './mixin';
+
+interface FakeDriverElementsMixin {
+  getElements(elementIds: string[]): FakeElement[];
+  getElement(elementId: string): FakeElement;
+  getName(elementId: string): Promise<string>;
+  elementDisplayed(elementId: string): Promise<boolean>;
+  elementEnabled(elementId: string): Promise<boolean>;
+  elementSelected(elementId: string): Promise<boolean>;
+  setValue(keys: string | string[], value: string): Promise<void>;
+  getText(elementId: string): Promise<string>;
+  clear(elementId: string): Promise<void>;
+  click(elementId: string): Promise<void>;
+
+  getAttribute(elementId: string, attributeName: string): Promise<string>;
+  getElementRect(elementId: string): Promise<Rect>;
+  getSize(elementId: string): Promise<Size>;
+  equalsElement(elementId: string, otherElementId: string): Promise<boolean>;
+  getCssProperty(elementId: string, propertyName: string): Promise<string>;
+  getLocation(elementId: string): Promise<Position>;
+  getLocationInView(elementId: string): Promise<Position>;
+}
+
+declare module '../driver' {
+  interface FakeDriver extends FakeDriverElementsMixin {}
+}
+
+const ElementsMixin: FakeDriverElementsMixin = {
+  getElements(this: FakeDriver, elementIds: string[]) {
+    for (const elId of elementIds) {
+      if (!_.has(this.elMap, elId)) {
+        throw new errors.StaleElementReferenceError();
+      }
+    }
+    return elementIds.map((e) => this.elMap[e]);
+  },
+
+  getElement(this: FakeDriver, elementId: string) {
+    return this.getElements([elementId])[0];
+  },
+
+  async getName(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.tagName;
+  },
+
+  async elementDisplayed(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.isVisible();
+  },
+
+  async elementEnabled(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.isEnabled();
+  },
+
+  async elementSelected(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.isSelected();
+  },
+
+  async setValue(this: FakeDriver, keys: string | string[], elementId: string) {
+    let value = keys;
+    if (keys instanceof Array) {
+      value = keys.join('');
+    }
+    const el = this.getElement(elementId);
+    if (el.type !== 'MockInputField') {
+      throw new errors.InvalidElementStateError();
+    }
+    el.setAttr('value', value);
+  },
+
+  async getText(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.getAttr('value');
+  },
+
+  async clear(this: FakeDriver, elementId: string) {
+    await this.setValue('', elementId);
+  },
+
+  /**
+   * This comment should be displayed instead of the one from ExternalDriver
+   */
+  async click(this: FakeDriver, elementId: string) {
+    this.assertNoAlert();
+    const el = this.getElement(elementId);
+    if (!el.isVisible()) {
+      throw new errors.InvalidElementStateError();
+    }
+    el.click();
+    this.focusedElId = elementId;
+  },
+
+  async getAttribute(this: FakeDriver, attr: string, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.getAttr(attr);
+  },
+
+  async getElementRect(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.getElementRect();
+  },
+
+  async getSize(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.getSize();
+  },
+
+  async equalsElement(this: FakeDriver, elementIdA: string, elementIdB: string) {
+    const el1 = this.getElement(elementIdA);
+    const el2 = this.getElement(elementIdB);
+    return el1.equals(el2);
+  },
+
+  async getCssProperty(this: FakeDriver, prop: string, elementId: string) {
+    this.assertWebviewContext();
+    const el = this.getElement(elementId);
+    return el.getCss(prop);
+  },
+
+  async getLocation(this: FakeDriver, elementId: string) {
+    const el = this.getElement(elementId);
+    return el.getLocation();
+  },
+
+  async getLocationInView(this: FakeDriver, elementId: string) {
+    return this.getLocation(elementId);
+  },
+};
+
+mixin(ElementsMixin);

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<unknown[]>;
+}
+
+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
+ */
+
+import './alert';
+import './contexts';
+import './element';
+import './find';
+import './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);
+}