@appium/fake-driver 6.0.2 → 6.1.0

package/lib/commands/find.ts

@@ -1,161 +1,146 @@
 import _ from 'lodash';
-import {Element} from '@appium/types';
+import type {Element} from '@appium/types';
 import {errors} from 'appium/driver';
-import {FakeElement} from '../fake-element';
-import {FakeDriver} from '../driver';
+import {FakeElement, type XmlNodeLike} from '../fake-element';
+import type {FakeDriver} from '../driver';
 import {util} from 'appium/support';
-import {mixin} from './mixin';
 
 const {W3C_WEB_ELEMENT_IDENTIFIER} = util;
 
-async function findElOrEls<Ctx = any>(
-  this: FakeDriver<any>,
+/** Find an existing element id in elMap for the same underlying node (reference equality). */
+export function getExistingElementForNode(
+  this: FakeDriver,
+  node: FakeElement
+): string | null {
+  for (const [id, el] of _.toPairs(this.elMap)) {
+    if (el.node === node.node) {
+      return id;
+    }
+  }
+  return null;
+}
+
+/** Accepts either a FakeElement (reuse existing id) or a raw XmlNodeLike from xpath. */
+export function wrapNewEl(
+  this: FakeDriver,
+  obj: FakeElement | XmlNodeLike
+): Element {
+  const node: XmlNodeLike = _.has(obj, 'node') && (obj as FakeElement).node
+      ? (obj as FakeElement).node
+      : (obj as XmlNodeLike);
+
+  if (_.has(obj, 'node')) {
+    const existingElId = this.getExistingElementForNode(obj as FakeElement);
+    if (existingElId) {
+      return {ELEMENT: existingElId, [W3C_WEB_ELEMENT_IDENTIFIER]: existingElId};
+    }
+  } else {
+    // raw node: reuse id if we already have an element for this node
+    for (const [id, el] of _.toPairs(this.elMap)) {
+      if (el.node === node) {
+        return {ELEMENT: id, [W3C_WEB_ELEMENT_IDENTIFIER]: id};
+      }
+    }
+  }
+
+  this.maxElId++;
+  const maxElId = this.maxElId.toString();
+  this.elMap[maxElId] = new FakeElement(node, this.appModel);
+  return {ELEMENT: maxElId, [W3C_WEB_ELEMENT_IDENTIFIER]: maxElId};
+}
+
+async function findElOrElsImpl<Ctx = unknown>(
+  this: FakeDriver,
   strategy: string,
   selector: string,
   mult: true,
   context?: Ctx
 ): Promise<Element[]>;
-async function findElOrEls<Ctx = any>(
-  this: FakeDriver<any>,
+async function findElOrElsImpl<Ctx = unknown>(
+  this: FakeDriver,
   strategy: string,
   selector: string,
   mult: false,
   context?: Ctx
 ): Promise<Element>;
-async function findElOrEls<Ctx = any>(
-  this: FakeDriver<any>,
+async function findElOrElsImpl<Ctx = unknown>(
+  this: FakeDriver,
   strategy: string,
   selector: string,
   mult: boolean,
   context?: Ctx
 ): Promise<Element | Element[]> {
-  const qMap = {
+  // Map WebDriver locator strategy to FakeApp query method name.
+  const qMap: Record<string, 'xpathQuery' | 'idQuery' | 'classQuery' | 'cssQuery'> = {
     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);
+  const methodName = qMap[strategy];
+  const raw = (this.appModel[methodName] as (sel: string, ctx?: unknown) => unknown).call(
+    this.appModel,
+    selector,
+    context
+  );
+  const els = _.isArray(raw) ? raw : raw ? [raw] : [];
 
-  let retval: Element | Element[];
   if (els.length) {
     if (mult) {
-      const allEls: Element[] = [];
-      for (const el of els) {
-        allEls.push(this.wrapNewEl(el));
-      }
-      retval = allEls;
-    } else {
-      retval = this.wrapNewEl(els[0]);
+      return els.map((el) => this.wrapNewEl(el as XmlNodeLike));
     }
-  } else if (mult) {
-    retval = [];
-  } else {
-    throw new errors.NoSuchElementError();
+    return this.wrapNewEl(els[0] as XmlNodeLike);
+  }
+  if (mult) {
+    return [];
   }
-  return retval;
+  throw new errors.NoSuchElementError();
 }
 
-interface FakeDriverFindMixin {
-  getExistingElementForNode(node: FakeElement): string | null;
-  wrapNewEl(obj: FakeElement): Element;
-
-  findElOrEls(
-    this: FakeDriver,
-    strategy: string,
-    selector: string,
-    mult: true,
-    context?: any
-  ): Promise<Element[]>;
-  findElOrEls(
-    this: FakeDriver,
-    strategy: string,
-    selector: string,
-    mult: false,
-    context?: any
-  ): Promise<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[]>;
-}
+export const findElOrEls = findElOrElsImpl;
 
-declare module '../driver' {
-  interface FakeDriver extends FakeDriverFindMixin {}
+export async function findElement(
+  this: FakeDriver,
+  strategy: string,
+  selector: string
+): Promise<Element> {
+  return this.findElOrEls(strategy, selector, false);
 }
 
-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};
-  },
-
-  findElOrEls,
+// Protocol passes (strategy, selector, elementId) for find-from-element routes.
 
-  /**
-   * 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);
-  },
+export async function findElements(
+  this: FakeDriver,
+  strategy: string,
+  selector: string
+): Promise<Element[]> {
+  return this.findElOrEls(strategy, selector, true);
+}
 
-  async findElementsFromElement(
-    this: FakeDriver,
-    strategy: string,
-    selector: string,
-    elementId: string
-  ) {
-    const el = this.getElement(elementId);
-    return this.findElOrEls(strategy, selector, true, el.xmlFragment);
-  },
-};
+export async function findElementFromElement(
+  this: FakeDriver,
+  strategy: string,
+  selector: string,
+  elementId: string
+): Promise<Element> {
+  const el = this.getElement(elementId);
+  return this.findElOrEls(strategy, selector, false, el.xmlFragment);
+}
 
-mixin(FindMixin);
+export async function findElementsFromElement(
+  this: FakeDriver,
+  strategy: string,
+  selector: string,
+  elementId: string
+): Promise<Element[]> {
+  const el = this.getElement(elementId);
+  return this.findElOrEls(strategy, selector, true, el.xmlFragment);
+}

package/lib/commands/general.ts

@@ -1,128 +1,123 @@
-import {ActionSequence, Location, Rect, Size} from '@appium/types';
+import type {ActionSequence, Location, Rect, Size, Orientation} from '@appium/types';
 import {errors} from 'appium/driver';
-import {FakeDriver} from '../driver';
-import {mixin} from './mixin';
-import type {Orientation} from '../driver';
-
-const ORIENTATIONS = new Set(['LANDSCAPE', 'PORTRAIT']);
-
-interface FakeDriverGeneralMixin {
-  title(): Promise<string>;
-  keys(value: string | string[]): Promise<void>;
-  setGeoLocation(location: Location): Promise<Location>;
-  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>;
-  getUrl(): Promise<string>;
-
-  bidiNavigate(context: string, url: string): Promise<void>;
-}
-
-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;
-    return location;
-  },
-
-  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);
-  },
-
-  async getUrl() {
-    return this.url;
-  },
-
-  async bidiNavigate(context: string, url: string) {
-    this.url = url;
-  },
-};
-
-mixin(GeneralMixin);
+import type {FakeDriver} from '../driver';
+
+const ORIENTATIONS = new Set<string>(['LANDSCAPE', 'PORTRAIT']);
+
+/** Requires webview context (title comes from active document). */
+export async function title(this: FakeDriver): Promise<string> {
+  this.assertWebviewContext();
+  return this.appModel.title;
+}
+
+export async function keys(
+  this: FakeDriver,
+  value: string | string[]
+): Promise<void> {
+  if (!this.focusedElId) {
+    throw new errors.InvalidElementStateError();
+  }
+  await this.setValue(value, this.focusedElId);
+}
+
+export async function setGeoLocation(
+  this: FakeDriver,
+  location: Location
+): Promise<Location> {
+  this.appModel.lat = location.latitude;
+  this.appModel.long = location.longitude;
+  return location;
+}
+
+export async function getGeoLocation(this: FakeDriver): Promise<Location> {
+  return this.appModel.currentGeoLocation;
+}
+
+export async function getPageSource(this: FakeDriver): Promise<string> {
+  return this.appModel.rawXml;
+}
+
+export async function getOrientation(this: FakeDriver): Promise<string> {
+  return this.appModel.orientation;
+}
+
+export async function setOrientation(
+  this: FakeDriver,
+  o: Orientation
+): Promise<void> {
+  if (!ORIENTATIONS.has(o)) {
+    throw new errors.UnknownError('Orientation must be LANDSCAPE or PORTRAIT');
+  }
+  this.appModel.orientation = o;
+}
+
+export async function getScreenshot(this: FakeDriver): Promise<string> {
+  return this.appModel.getScreenshot();
+}
+
+export async function getWindowSize(this: FakeDriver): Promise<Size> {
+  return {width: this.appModel.width, height: this.appModel.height};
+}
+
+export async function getWindowRect(this: FakeDriver): Promise<Rect> {
+  return {width: this.appModel.width, height: this.appModel.height, x: 0, y: 0};
+}
+
+export async function performActions(
+  this: FakeDriver,
+  actions: ActionSequence[]
+): Promise<void> {
+  this.appModel.actionLog.push(actions);
+}
+
+export async function releaseActions(this: FakeDriver): Promise<void> {}
+
+/** Supported log types: 'actions'. TODO: add more log types if needed for tests. */
+export async function 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}'`);
+  }
+}
+
+export async function mobileShake(this: FakeDriver): Promise<void> {
+  this.shook = true;
+}
+
+export async function doubleClick(this: FakeDriver): Promise<void> {}
+
+export async function execute(
+  this: FakeDriver,
+  script: string,
+  args: any[]
+): Promise<any> {
+  return await this.executeMethod(script, args);
+}
+
+export async function fakeAddition(
+  this: FakeDriver,
+  num1: number,
+  num2: number,
+  num3 = 0
+): Promise<number> {
+  return num1 + num2 + (num3 ?? 0);
+}
+
+/** Get current URL. Returns empty string until bidiNavigate (or equivalent) sets one. @see https://w3c.github.io/webdriver/#get-current-url */
+export async function getUrl(this: FakeDriver): Promise<string> {
+  return this.url ?? '';
+}
+
+/** Set current URL (used by Bidi browsingContext.navigate). */
+export async function bidiNavigate(
+  this: FakeDriver,
+  context: string,
+  url: string
+): Promise<void> {
+  this.url = url;
+}

package/lib/desired-caps.ts

@@ -0,0 +1,16 @@
+import type {Constraints} from '@appium/types';
+
+export const desiredCapConstraints = {
+  app: {
+    presence: true,
+    isString: true,
+  },
+  uniqueApp: {
+    isBoolean: true,
+  },
+  runClock: {
+    isBoolean: true,
+  },
+} as const satisfies Constraints;
+
+export type FakeDriverConstraints = typeof desiredCapConstraints;

package/lib/doctor/common.ts

@@ -0,0 +1,26 @@
+import {doctor} from 'appium/support';
+import type {IDoctorCheck, AppiumLogger, DoctorCheckResult} from '@appium/types';
+
+export class EnvVarAndPathCheck implements IDoctorCheck {
+  log!: AppiumLogger;
+
+  constructor(private readonly varName: string) {}
+
+  async diagnose(): Promise<DoctorCheckResult> {
+    return doctor.ok(
+      `${this.varName} environment variable is always set because it's fake`
+    );
+  }
+
+  async fix(): Promise<string> {
+    return `Make sure the environment variable ${this.varName} is properly configured for the Appium server process`;
+  }
+
+  hasAutofix(): boolean {
+    return false;
+  }
+
+  isOptional(): boolean {
+    return false;
+  }
+}

package/lib/doctor/fake1.ts

@@ -0,0 +1,3 @@
+import {EnvVarAndPathCheck} from './common';
+
+export const fakeCheck1 = new EnvVarAndPathCheck('FAKE1');

package/lib/doctor/fake2.ts

@@ -0,0 +1,3 @@
+import {EnvVarAndPathCheck} from './common';
+
+export const fakeCheck2 = new EnvVarAndPathCheck('FAKE2');