@testspectra/matchers 1.0.0

package/src/runner/single.ts

@@ -0,0 +1,166 @@
+import { SingleElementMatcher, ElementTarget } from "../types.js";
+import { executeSingleMatcher, resolveElement } from "../matchers.js";
+
+type AssertionItem = {
+  target?: ElementTarget;
+  matcher: SingleElementMatcher;
+  args: any[];
+};
+
+export class SingleElementRunner implements PromiseLike<void> {
+  private _target: ElementTarget | undefined;
+  private _action: (() => Promise<any>) | null = null;
+  private _assertions: AssertionItem[] = [];
+
+  constructor(target?: ElementTarget, action?: () => Promise<any>) {
+    this._target = target;
+    this._action = action || null;
+  }
+
+  // --- Chained Actions on current target ---
+
+  click(): this {
+    const target = this.requireTarget("click");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.click();
+    };
+    return this;
+  }
+
+  doubleClick(): this {
+    const target = this.requireTarget("doubleClick");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.doubleClick();
+    };
+    return this;
+  }
+
+  longPress(durationMs = 1000): this {
+    const target = this.requireTarget("longPress");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      if (typeof (el as any).touchAction === "function") {
+        await (el as any).touchAction([
+          { action: "longPress", ms: durationMs },
+          { action: "release" },
+        ]);
+      } else {
+        await el.click();
+      }
+    };
+    return this;
+  }
+
+  type(value: string, options?: { clearFirst?: boolean }): this {
+    const target = this.requireTarget("type");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      if (options?.clearFirst) {
+        await el.clearValue();
+      }
+      await el.setValue(value);
+    };
+    return this;
+  }
+
+  clear(): this {
+    const target = this.requireTarget("clear");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.clearValue();
+    };
+    return this;
+  }
+
+  select(value: string): this {
+    const target = this.requireTarget("select");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.selectByVisibleText(value);
+    };
+    return this;
+  }
+
+  hover(): this {
+    const target = this.requireTarget("hover");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.moveTo();
+    };
+    return this;
+  }
+
+  waitForElement(timeoutMs = 10000): this {
+    const target = this.requireTarget("waitForElement");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.waitForDisplayed({ timeout: timeoutMs });
+    };
+    return this;
+  }
+
+  // --- Fluent Assertion Matchers ---
+
+  should(matcher: SingleElementMatcher, ...args: any[]): this;
+  should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
+  should(a: ElementTarget | SingleElementMatcher, b?: any, ...rest: any[]): this {
+    const isFirstArgMatcher =
+      typeof a === "string" &&
+      (a.includes(".") ||
+        a.includes("exist") ||
+        a.includes("visible") ||
+        a.includes("enabled") ||
+        a.includes("disabled") ||
+        a.includes("selected") ||
+        a.includes("checked"));
+
+    if (b !== undefined && !isFirstArgMatcher) {
+      // Form: should(target, matcher, ...args)
+      this._assertions.push({
+        target: a as ElementTarget,
+        matcher: b as SingleElementMatcher,
+        args: rest,
+      });
+    } else {
+      // Form: should(matcher, ...args) -> on current target
+      this._assertions.push({
+        target: this._target,
+        matcher: a as SingleElementMatcher,
+        args: b !== undefined ? [b, ...rest] : rest,
+      });
+    }
+    return this;
+  }
+
+  // --- Execution when awaited ---
+
+  async then<TResult1 = void, TResult2 = never>(
+    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    try {
+      if (this._action) {
+        await this._action();
+      }
+      for (const assert of this._assertions) {
+        await executeSingleMatcher(assert.target, assert.matcher, assert.args);
+      }
+      const res = (onfulfilled ? await onfulfilled() : undefined) as TResult1;
+      return res;
+    } catch (err) {
+      if (onrejected) {
+        return onrejected(err);
+      }
+      throw err;
+    }
+  }
+
+  private requireTarget(actionName: string): ElementTarget {
+    if (!this._target) {
+      throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);
+    }
+    return this._target;
+  }
+}

package/src/spectra.ts

@@ -0,0 +1,185 @@
+import {
+  ClickOptions,
+  ElementTarget,
+  KeyOption,
+  LongPressOptions,
+  ScrollOptions,
+  SwipeOptions,
+  TypeOptions,
+} from "./types.js";
+import { SingleElementRunner } from "./runner/single.js";
+import { MultiElementRunner } from "./runner/collection.js";
+import { resolveElement } from "./matchers.js";
+
+/**
+ * Main Spectra testing API orchestrator.
+ * Combines direct actions, single element queries (get), and collections (getAll).
+ */
+export class SpectraStatic {
+  /**
+   * Targets a single element by selector or Page Object element.
+   */
+  get(target: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(target);
+  }
+
+  /**
+   * Targets multiple elements / collections by selector.
+   */
+  getAll(selector: string): MultiElementRunner {
+    return new MultiElementRunner(selector);
+  }
+
+  // --- Browser & Navigation Actions ---
+
+  navigate(url: string): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.url(url);
+    });
+  }
+
+  back(): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.back();
+    });
+  }
+
+  refresh(): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.refresh();
+    });
+  }
+
+  // --- Direct Interaction Actions ---
+
+  click(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.click();
+    });
+  }
+
+  doubleClick(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.doubleClick();
+    });
+  }
+
+  longPress(target: ElementTarget, options?: LongPressOptions | number): SingleElementRunner {
+    const duration = typeof options === "number" ? options : options?.duration || 1000;
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      if (typeof (el as any).touchAction === "function") {
+        await (el as any).touchAction([
+          { action: "longPress", ms: duration },
+          { action: "release" },
+        ]);
+      } else {
+        await el.click();
+      }
+    });
+  }
+
+  type(target: ElementTarget, value: string, options?: TypeOptions): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      if (options?.clearFirst) {
+        await el.clearValue();
+      }
+      await el.setValue(value);
+    });
+  }
+
+  clear(target: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.clearValue();
+    });
+  }
+
+  select(target: ElementTarget, value: string): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.selectByVisibleText(value);
+    });
+  }
+
+  hover(target: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.moveTo();
+    });
+  }
+
+  pressKey(key: KeyOption | string): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.keys(key);
+    });
+  }
+
+  dragDrop(sourceTarget: ElementTarget, destTarget: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(sourceTarget, async () => {
+      const source = await resolveElement(sourceTarget);
+      const target = await resolveElement(destTarget);
+      await source.dragAndDrop(target);
+    });
+  }
+
+  // --- Gesture Actions ---
+
+  scroll(options?: ScrollOptions): SingleElementRunner {
+    return new SingleElementRunner(options?.selector, async () => {
+      if (options?.selector) {
+        const el = await resolveElement(options.selector);
+        await el.scrollIntoView();
+      } else {
+        await browser.execute((direction, pixels) => {
+          const delta = pixels || 500;
+          window.scrollBy({
+            top: direction === "up" ? -delta : direction === "down" ? delta : 0,
+            left: direction === "left" ? -delta : direction === "right" ? delta : 0,
+            behavior: "smooth",
+          });
+        }, options?.direction || "down", options?.pixels || 500);
+      }
+    });
+  }
+
+  swipe(options: SwipeOptions): SingleElementRunner {
+    return new SingleElementRunner(options.selector, async () => {
+      if (typeof (browser as any).touchAction === "function") {
+        const distance = options.distance || 300;
+        await (browser as any).touchAction([
+          { action: "press", x: 200, y: 500 },
+          {
+            action: "moveTo",
+            x: options.direction === "right" ? 200 + distance : options.direction === "left" ? 200 - distance : 200,
+            y: options.direction === "down" ? 500 + distance : options.direction === "up" ? 500 - distance : 500,
+          },
+          { action: "release" },
+        ]);
+      } else {
+        // Fallback to web scroll
+        await this.scroll({ direction: options.direction, pixels: options.distance });
+      }
+    });
+  }
+
+  // --- Timing Actions ---
+
+  wait(durationMs: number): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.pause(durationMs);
+    });
+  }
+
+  waitForElement(target: ElementTarget, timeoutMs = 10000): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.waitForDisplayed({ timeout: timeoutMs });
+    });
+  }
+}
+
+export const Spectra = new SpectraStatic();

package/src/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Database Canonical Action and Assertion Types
+ * Matches backend/src/models/test_step.rs
+ */
+
+export type ActionKey =
+  | "navigate"
+  | "click"
+  | "type"
+  | "clear"
+  | "select"
+  | "scroll"
+  | "swipe"
+  | "wait"
+  | "waitForElement"
+  | "pressKey"
+  | "longPress"
+  | "doubleClick"
+  | "hover"
+  | "dragDrop"
+  | "back"
+  | "refresh";
+
+export type AssertionKey =
+  | "elementDisplayed"
+  | "elementNotDisplayed"
+  | "elementExists"
+  | "elementEnabled"
+  | "elementDisabled"
+  | "textContains"
+  | "textEquals"
+  | "textNotContains"
+  | "urlContains"
+  | "urlEquals"
+  | "valueEquals"
+  | "valueContains"
+  | "attributeEquals"
+  | "attributeContains"
+  | "hasClass"
+  | "hasAttribute"
+  | "isSelected"
+  | "elementCount"
+  | "elementCountGreaterThan"
+  | "pageLoaded"
+  | "noErrors";
+
+export type KeyOption =
+  | "Enter"
+  | "Tab"
+  | "Escape"
+  | "Backspace"
+  | "Delete"
+  | "ArrowUp"
+  | "ArrowDown"
+  | "ArrowLeft"
+  | "ArrowRight"
+  | "Space";
+
+export type Direction = "up" | "down" | "left" | "right";
+
+export type ElementTarget = string | WebdriverIO.Element | ChainablePromiseElement;
+
+export interface ScrollOptions {
+  direction?: Direction;
+  pixels?: number;
+  selector?: ElementTarget;
+}
+
+export interface SwipeOptions {
+  direction: Direction;
+  distance?: number;
+  selector?: ElementTarget;
+}
+
+export interface LongPressOptions {
+  text?: string;
+  duration?: number;
+}
+
+export interface ClickOptions {
+  text?: string;
+  clickType?: "single" | "double";
+}
+
+export interface TypeOptions {
+  clearFirst?: boolean;
+}
+
+export type SingleElementMatcher =
+  | "be.visible"
+  | "not.be.visible"
+  | "exist"
+  | "not.exist"
+  | "be.enabled"
+  | "be.disabled"
+  | "be.checked"
+  | "be.selected"
+  | "have.value"
+  | "contain.value"
+  | "have.text"
+  | "contain.text"
+  | "have.class"
+  | "have.attr"
+  | "have.url"
+  | "contain.url"
+  | "have.title"
+  | "contain.title";
+
+export type MultiElementMatcher =
+  | "have.length"
+  | "have.length.greaterThan"
+  | "be.empty"
+  | "exist";

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node", "@wdio/globals/types", "@wdio/mocha-framework"],
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}