@appium/fake-driver 6.0.2 → 6.1.1

package/lib/driver.ts

@@ -0,0 +1,321 @@
+import {sleep} from 'asyncbox';
+import type {Express, Request, Response} from 'express';
+import type {Server as HttpServer} from 'node:http';
+import {BaseDriver, errors} from 'appium/driver';
+import type {DriverData, InitialOpts} from '@appium/types';
+import {desiredCapConstraints} from './desired-caps';
+import type {FakeDriverConstraints} from './desired-caps';
+import type {FakeDriverCaps, W3CFakeDriverCaps} from './types';
+import {FakeApp} from './fake-app';
+import type {FakeElement} from './fake-element';
+import * as alertCommands from './commands/alert';
+import * as contextsCommands from './commands/contexts';
+import * as elementCommands from './commands/element';
+import * as findCommands from './commands/find';
+import * as generalCommands from './commands/general';
+
+export type {FakeDriverConstraints};
+export type {Orientation} from '@appium/types';
+
+/** Driver supporting a generic "fake thing" value (getFakeThing / setFakeThing). */
+export class FakeDriver<Thing = unknown> extends BaseDriver<FakeDriverConstraints> {
+  readonly desiredCapConstraints = desiredCapConstraints;
+
+  curContext: string;
+  readonly appModel: FakeApp;
+  _proxyActive: boolean;
+  shook: boolean;
+  focusedElId: string | null;
+  fakeThing: Thing | null;
+  /** Next numeric id for new elements; keys in elMap are stringified. */
+  maxElId: number;
+  /** Map of element id (string) to FakeElement for this session. */
+  elMap: Record<string, FakeElement>;
+  /** If set, Bidi connections are proxied to this URL instead of handling locally. */
+  private _bidiProxyUrl: string | null;
+  private _clockRunning = false;
+  /** Current document URL; set by bidiNavigate, returned by getUrl. */
+  url: string = '';
+
+  // Alert commands
+  assertNoAlert = alertCommands.assertNoAlert;
+  assertAlert = alertCommands.assertAlert;
+  getAlertText = alertCommands.getAlertText;
+  setAlertText = alertCommands.setAlertText;
+  postAcceptAlert = alertCommands.postAcceptAlert;
+  postDismissAlert = alertCommands.postDismissAlert;
+
+  // Context commands
+  getRawContexts = contextsCommands.getRawContexts;
+  assertWebviewContext = contextsCommands.assertWebviewContext;
+  getCurrentContext = contextsCommands.getCurrentContext;
+  getContexts = contextsCommands.getContexts;
+  setContext = contextsCommands.setContext;
+  setFrame = contextsCommands.setFrame;
+
+  // Element commands
+  getElements = elementCommands.getElements;
+  getElement = elementCommands.getElement;
+  getName = elementCommands.getName;
+  elementDisplayed = elementCommands.elementDisplayed;
+  elementEnabled = elementCommands.elementEnabled;
+  elementSelected = elementCommands.elementSelected;
+  setValue = elementCommands.setValue;
+  getText = elementCommands.getText;
+  clear = elementCommands.clear;
+  click = elementCommands.click;
+  getAttribute = elementCommands.getAttribute;
+  getElementRect = elementCommands.getElementRect;
+  getSize = elementCommands.getSize;
+  equalsElement = elementCommands.equalsElement;
+  getCssProperty = elementCommands.getCssProperty;
+  getLocation = elementCommands.getLocation;
+  getLocationInView = elementCommands.getLocationInView;
+
+  // Find commands
+  getExistingElementForNode = findCommands.getExistingElementForNode;
+  wrapNewEl = findCommands.wrapNewEl;
+  findElOrEls = findCommands.findElOrEls;
+  findElement = findCommands.findElement;
+  findElements = findCommands.findElements;
+  findElementFromElement = findCommands.findElementFromElement;
+  findElementsFromElement = findCommands.findElementsFromElement;
+
+  // General commands
+  title = generalCommands.title;
+  keys = generalCommands.keys;
+  setGeoLocation = generalCommands.setGeoLocation;
+  getGeoLocation = generalCommands.getGeoLocation;
+  getPageSource = generalCommands.getPageSource;
+  getOrientation = generalCommands.getOrientation;
+  setOrientation = generalCommands.setOrientation;
+  getScreenshot = generalCommands.getScreenshot;
+  getWindowSize = generalCommands.getWindowSize;
+  getWindowRect = generalCommands.getWindowRect;
+  performActions = generalCommands.performActions;
+  releaseActions = generalCommands.releaseActions;
+  getLog = generalCommands.getLog;
+  mobileShake = generalCommands.mobileShake;
+  doubleClick = generalCommands.doubleClick;
+  execute = generalCommands.execute;
+  fakeAddition = generalCommands.fakeAddition;
+  getUrl = generalCommands.getUrl;
+  bidiNavigate = generalCommands.bidiNavigate;
+
+  constructor(opts: InitialOpts = {} as InitialOpts, shouldValidateCaps = true) {
+    super(opts, shouldValidateCaps);
+    this.curContext = 'NATIVE_APP';
+    this.elMap = {};
+    this.focusedElId = null;
+    this.maxElId = 0;
+    this.fakeThing = null;
+    this._proxyActive = false;
+    this.shook = false;
+    this.appModel = new FakeApp();
+    this._bidiProxyUrl = null;
+  }
+
+  proxyActive(): boolean {
+    return this._proxyActive;
+  }
+
+  canProxy(): boolean {
+    return true;
+  }
+
+  get bidiProxyUrl(): string | null {
+    return this._bidiProxyUrl;
+  }
+
+  proxyReqRes(req: Request, res: Response): void {
+    res.set('content-type', 'application/json');
+    const resBodyObj: {value: string; sessionId: string | null} = {
+      value: 'proxied via proxyReqRes',
+      sessionId: null,
+    };
+    const match = req.originalUrl.match(/\/session\/([^/]+)/);
+    resBodyObj.sessionId = match ? match[1] : null;
+    res.status(200).send(JSON.stringify(resBodyObj));
+  }
+
+  async proxyCommand<T = unknown>(): Promise<T> {
+    return 'proxied via proxyCommand' as T;
+  }
+
+  /**
+   * Create session and load fake app XML from caps.app.
+   * Starts clock event emitter if caps.runClock is true.
+   */
+  override async createSession(
+    w3cCapabilities1: W3CFakeDriverCaps,
+    w3cCapabilities2?: W3CFakeDriverCaps,
+    w3cCapabilities3?: W3CFakeDriverCaps,
+    driverData: DriverData[] = []
+  ): Promise<[string, FakeDriverCaps]> {
+    for (const d of driverData) {
+      if (d.isUnique) {
+        throw new errors.SessionNotCreatedError(
+          'Cannot start session; another ' +
+            'unique session is in progress that requires all resources'
+        );
+      }
+    }
+
+    const [sessionId, caps] = await super.createSession(
+      w3cCapabilities1,
+      w3cCapabilities2,
+      w3cCapabilities3,
+      driverData
+    ) as [string, FakeDriverCaps];
+    this.caps = caps;
+    await this.appModel.loadApp(caps.app);
+    if (this.caps.runClock) {
+      this.startClock();
+    }
+    return [sessionId, caps];
+  }
+
+  override async deleteSession(sessionId?: string): Promise<void> {
+    this.stopClock();
+    return await super.deleteSession(sessionId);
+  }
+
+  async getWindowHandle(): Promise<string> {
+    return '1';
+  }
+
+  async getWindowHandles(): Promise<string[]> {
+    return ['1'];
+  }
+
+  override get driverData(): {isUnique: boolean} {
+    return {
+      isUnique: !!this.caps.uniqueApp,
+    };
+  }
+
+  async getFakeThing(): Promise<Thing | null> {
+    await sleep(1);
+    return this.fakeThing;
+  }
+
+  async setFakeThing(thing: Thing): Promise<null> {
+    await sleep(1);
+    this.fakeThing = thing;
+    return null;
+  }
+
+  async getFakeDriverArgs(): Promise<typeof this.cliArgs> {
+    await sleep(1);
+    return this.cliArgs;
+  }
+
+  /** TODO: track deprecated commands when called and return their names. */
+  async getDeprecatedCommandsCalled(): Promise<string[]> {
+    await sleep(1);
+    return [];
+  }
+
+  async callDeprecatedCommand(): Promise<void> {
+    await sleep(1);
+  }
+
+  async doSomeMath(num1: number, num2: number): Promise<number> {
+    await sleep(1);
+    return num1 + num2;
+  }
+
+  async doSomeMath2(num1: number, num2: number): Promise<number> {
+    await sleep(1);
+    return num1 + num2;
+  }
+
+  private async startClock(): Promise<void> {
+    this._clockRunning = true;
+    while (this._clockRunning) {
+      await sleep(500);
+      this.eventEmitter.emit('bidiEvent', {
+        method: 'appium:clock.currentTime',
+        params: {time: Date.now()},
+      });
+    }
+  }
+
+  private stopClock(): void {
+    this._clockRunning = false;
+  }
+
+  static newBidiCommands = {
+    'appium:fake': {
+      getFakeThing: {
+        command: 'getFakeThing',
+      },
+      setFakeThing: {
+        command: 'setFakeThing',
+        params: {
+          required: ['thing'],
+        },
+      },
+      doSomeMath: {
+        command: 'doSomeMath',
+        params: {
+          required: ['num1', 'num2'],
+        },
+      },
+      doSomeMath2: {
+        command: 'doSomeMath2',
+        params: {
+          required: ['num1', 'num2'],
+        },
+      },
+    },
+  } as const;
+
+  static newMethodMap = {
+    '/session/:sessionId/fakedriver': {
+      GET: {command: 'getFakeThing'},
+      POST: {command: 'setFakeThing', payloadParams: {required: ['thing'] as const}},
+    },
+    '/session/:sessionId/fakedriverargs': {
+      GET: {command: 'getFakeDriverArgs'},
+    },
+    '/session/:sessionId/deprecated': {
+      POST: {command: 'callDeprecatedCommand', deprecated: true},
+    },
+    '/session/:sessionId/doubleclick': {
+      POST: {command: 'doubleClick'},
+    },
+  } as const;
+
+  static executeMethodMap = {
+    'fake: addition': {
+      command: 'fakeAddition',
+      params: {required: ['num1', 'num2'], optional: ['num3']},
+    },
+    'fake: getThing': {
+      command: 'getFakeThing',
+    },
+    'fake: setThing': {
+      command: 'setFakeThing',
+      params: {required: ['thing']},
+    },
+    'fake: getDeprecatedCommandsCalled': {
+      command: 'getDeprecatedCommandsCalled',
+    },
+  } as const;
+
+  static fakeRoute(req: Request, res: Response): void {
+    res.send(JSON.stringify({fakedriver: 'fakeResponse'}));
+  }
+
+  static async updateServer(
+    expressApp: Express,
+    httpServer: HttpServer,
+    cliArgs: Record<string, unknown>
+  ): Promise<void> {
+    expressApp.all('/fakedriver', FakeDriver.fakeRoute);
+    expressApp.all('/fakedriverCliArgs', (req: Request, res: Response) => {
+      res.send(JSON.stringify(cliArgs));
+    });
+  }
+}

package/lib/fake-app.ts

@@ -0,0 +1,234 @@
+import {fs} from 'appium/support';
+import {readFileSync} from 'node:fs';
+import path from 'node:path';
+import XMLDom from '@xmldom/xmldom';
+import * as xpath from 'xpath';
+import {log} from './logger';
+import _ from 'lodash';
+import {FakeElement, type XmlNodeLike} from './fake-element';
+import type {ActionSequence, Location, Orientation} from '@appium/types';
+import type {Document as XMLDocument, Node as XMLNode} from '@xmldom/xmldom';
+
+const SCREENSHOT = path.join(__dirname, 'screen.png');
+
+export interface FakeWebView {
+  node: XmlNodeLike;
+}
+
+/** In-memory app model: XML DOM, webviews, alerts, geo, orientation, actions log. */
+export class FakeApp {
+  dom: XMLDocument | null;
+  activeDom: XMLDocument | null;
+  activeWebview: FakeWebView | null;
+  activeFrame: XMLDocument | null;
+  activeAlert: FakeElement | null;
+  lat: number;
+  long: number;
+  private _width: number | null;
+  private _height: number | null;
+  rawXml: string;
+  currentOrientation: Orientation;
+  actionLog: ActionSequence[][];
+
+  constructor() {
+    this.dom = null;
+    this.activeDom = null;
+    this.activeWebview = null;
+    this.activeFrame = null;
+    this.activeAlert = null;
+    this.lat = 0;
+    this.long = 0;
+    this._width = null;
+    this._height = null;
+    this.rawXml = '';
+    this.currentOrientation = 'PORTRAIT';
+    this.actionLog = [];
+  }
+
+  get title(): string {
+    const nodes = this.xpathQuery('//title');
+    if (!_.isArray(nodes) || nodes.length < 1) {
+      throw new Error('No title!');
+    }
+    const node = nodes[0];
+    const firstChild = node.firstChild as unknown as {data: string} | null;
+    return firstChild?.data ?? '';
+  }
+
+  get currentGeoLocation(): Location {
+    return {
+      latitude: this.lat,
+      longitude: this.long,
+    };
+  }
+
+  get orientation(): Orientation {
+    return this.currentOrientation;
+  }
+
+  set orientation(o: Orientation) {
+    this.currentOrientation = o;
+  }
+
+  get width(): number {
+    if (this._width === null) {
+      this.setDims();
+    }
+    const w = this._width;
+    if (w === null) {
+      throw new Error('Cannot fetch app dimensions');
+    }
+    return w;
+  }
+
+  get height(): number {
+    if (this._height === null) {
+      this.setDims();
+    }
+    const h = this._height;
+    if (h === null) {
+      throw new Error('Cannot fetch app dimensions');
+    }
+    return h;
+  }
+
+  private setDims(): void {
+    const nodes = this.xpathQuery('//app');
+    if (!_.isArray(nodes)) {
+      throw new Error(
+        'Cannot fetch app dimensions because no corresponding node has been found in the source'
+      );
+    }
+    const app = new FakeElement(nodes[0] as unknown as XmlNodeLike, this);
+    this._width = parseInt(app.nodeAttrs.width, 10);
+    this._height = parseInt(app.nodeAttrs.height, 10);
+  }
+
+  async loadApp(appPath: string): Promise<void> {
+    log.info(`Loading Mock app model at ${appPath}`);
+    const data = await fs.readFile(appPath);
+    log.info('Parsing Mock app XML');
+    this.rawXml = data.toString();
+    this.rawXml = this.rawXml.replace('<app ', '<AppiumAUT><app ');
+    this.rawXml = this.rawXml.replace('<app>', '<AppiumAUT><app>');
+    this.rawXml = this.rawXml.replace('</app>', '</app></AppiumAUT>');
+    this.dom = new XMLDom.DOMParser().parseFromString(
+      this.rawXml,
+      XMLDom.MIME_TYPE.XML_TEXT
+    ) as XMLDocument;
+    this.activeDom = this.dom;
+  }
+
+  getWebviews(): FakeWebView[] {
+    const nodes = this.xpathQuery('//MockWebView/*[1]');
+    return _.isArray(nodes) ? nodes.map((n) => new FakeWebViewImpl(n as unknown as XmlNodeLike)) : [];
+  }
+
+  activateWebview(wv: FakeWebView): void {
+    this.activeWebview = wv;
+    const fragment = new XMLDom.XMLSerializer().serializeToString(
+      wv.node as unknown as XMLNode
+    );
+    this.activeDom = new XMLDom.DOMParser().parseFromString(
+      fragment,
+      XMLDom.MIME_TYPE.XML_TEXT
+    ) as XMLDocument;
+  }
+
+  deactivateWebview(): void {
+    this.activeWebview = null;
+    this.activeDom = this.dom;
+  }
+
+  activateFrame(frame: XMLDocument): void {
+    this.activeFrame = frame;
+    const fragment = new XMLDom.XMLSerializer().serializeToString(
+      frame as unknown as XMLNode
+    );
+    this.activeDom = new XMLDom.DOMParser().parseFromString(
+      fragment,
+      XMLDom.MIME_TYPE.XML_TEXT
+    ) as XMLDocument;
+  }
+
+  deactivateFrame(): void {
+    this.activeFrame = null;
+    if (this.activeWebview) {
+      this.activateWebview(this.activeWebview);
+    }
+  }
+
+  xpathQuery(sel: string, ctx?: XMLDocument | null): xpath.SelectedValue {
+    const node = ctx ?? this.activeDom;
+    return xpath.select(
+      sel,
+      node as unknown as Node
+    ) as xpath.SelectedValue;
+  }
+
+  idQuery(id: string, ctx?: XMLDocument | null): xpath.SelectedValue {
+    return this.xpathQuery(`//*[@id="${id}"]`, ctx);
+  }
+
+  classQuery(className: string, ctx?: XMLDocument | null): xpath.SelectedValue {
+    return this.xpathQuery(`//${className}`, ctx);
+  }
+
+  cssQuery(css: string, ctx?: XMLDocument | null): xpath.SelectedValue {
+    if (css.startsWith('#')) {
+      return this.idQuery(css.slice(1), ctx);
+    }
+    if (css.startsWith('.')) {
+      return this.classQuery(css.slice(1), ctx);
+    }
+    return this.classQuery(css, ctx);
+  }
+
+  hasAlert(): boolean {
+    return this.activeAlert !== null;
+  }
+
+  setAlertText(text: string): void {
+    if (!this.activeAlert?.hasPrompt()) {
+      throw new Error('No prompt to set text of');
+    }
+    this.activeAlert?.setAttr('prompt', text);
+  }
+
+  showAlert(alertId: string): void {
+    const nodes = this.xpathQuery(`//alert[@id="${alertId}"]`);
+    if (!_.isArray(nodes) || _.isEmpty(nodes)) {
+      throw new Error(`Alert ${alertId} doesn't exist!`);
+    }
+    this.activeAlert = new FakeElement(nodes[0] as unknown as XmlNodeLike, this);
+  }
+
+  /** Alert text from prompt attr or node text attr (e.g. <alert text="Fake Alert">). */
+  alertText(): string {
+    const prompt = this.activeAlert?.getAttr('prompt');
+    if (prompt) {
+      return prompt;
+    }
+    const fromAttrs = this.activeAlert?.nodeAttrs?.text;
+    if (fromAttrs) {
+      return fromAttrs;
+    }
+    const node = this.activeAlert?.node as {getAttribute?(name: string): string | null} | undefined;
+    return node?.getAttribute?.('text') ?? '';
+  }
+
+  handleAlert(): void {
+    this.activeAlert = null;
+  }
+
+  getScreenshot(): string {
+    return readFileSync(SCREENSHOT, 'base64');
+  }
+}
+
+export class FakeWebViewImpl implements FakeWebView {
+  readonly node: XmlNodeLike;
+  constructor(node: XmlNodeLike) {
+    this.node = node;
+  }
+}

package/lib/fake-driver-schema.ts

@@ -0,0 +1,43 @@
+/**
+ * JSON Schema for Fake Driver CLI/server arguments.
+ * Could be a .json file; kept as TS for consistency and type export.
+ */
+export interface FakeDriverSchema {
+  type: 'object';
+  title: string;
+  description: string;
+  properties: {
+    'silly-web-server-port'?: {
+      type: 'integer';
+      minimum: number;
+      maximum: number;
+      description: string;
+    };
+    sillyWebServerHost?: {
+      type: 'string';
+      description: string;
+      default?: string;
+    };
+  };
+}
+
+const schema: FakeDriverSchema = {
+  type: 'object',
+  title: 'Fake Driver Configuration',
+  description: 'A schema for Fake Driver arguments',
+  properties: {
+    'silly-web-server-port': {
+      type: 'integer',
+      minimum: 1,
+      maximum: 65535,
+      description: 'The port to use for the fake web server',
+    },
+    sillyWebServerHost: {
+      type: 'string',
+      description: 'The host to use for the fake web server',
+      default: 'sillyhost',
+    },
+  },
+};
+
+export default schema;