@testspectra/matchers 1.0.0

package/dist/spectra.js

@@ -0,0 +1,156 @@
+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) {
+        return new SingleElementRunner(target);
+    }
+    /**
+     * Targets multiple elements / collections by selector.
+     */
+    getAll(selector) {
+        return new MultiElementRunner(selector);
+    }
+    // --- Browser & Navigation Actions ---
+    navigate(url) {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.url(url);
+        });
+    }
+    back() {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.back();
+        });
+    }
+    refresh() {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.refresh();
+        });
+    }
+    // --- Direct Interaction Actions ---
+    click(target, textOrOptions) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.click();
+        });
+    }
+    doubleClick(target, textOrOptions) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.doubleClick();
+        });
+    }
+    longPress(target, options) {
+        const duration = typeof options === "number" ? options : options?.duration || 1000;
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            if (typeof el.touchAction === "function") {
+                await el.touchAction([
+                    { action: "longPress", ms: duration },
+                    { action: "release" },
+                ]);
+            }
+            else {
+                await el.click();
+            }
+        });
+    }
+    type(target, value, options) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            if (options?.clearFirst) {
+                await el.clearValue();
+            }
+            await el.setValue(value);
+        });
+    }
+    clear(target) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.clearValue();
+        });
+    }
+    select(target, value) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.selectByVisibleText(value);
+        });
+    }
+    hover(target) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.moveTo();
+        });
+    }
+    pressKey(key) {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.keys(key);
+        });
+    }
+    dragDrop(sourceTarget, destTarget) {
+        return new SingleElementRunner(sourceTarget, async () => {
+            const source = await resolveElement(sourceTarget);
+            const target = await resolveElement(destTarget);
+            await source.dragAndDrop(target);
+        });
+    }
+    // --- Gesture Actions ---
+    scroll(options) {
+        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) {
+        return new SingleElementRunner(options.selector, async () => {
+            if (typeof browser.touchAction === "function") {
+                const distance = options.distance || 300;
+                await browser.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) {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.pause(durationMs);
+        });
+    }
+    waitForElement(target, timeoutMs = 10000) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.waitForDisplayed({ timeout: timeoutMs });
+        });
+    }
+}
+export const Spectra = new SpectraStatic();

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Database Canonical Action and Assertion Types
+ * Matches backend/src/models/test_step.rs
+ */
+export {};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@testspectra/matchers",
+  "version": "1.0.0",
+  "description": "Cross-platform action commands and direct callable assertion matchers for TestSpectra",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@wdio/globals": "^9.2.8",
+    "@wdio/mocha-framework": "^9.2.8",
+    "webdriverio": "^9.2.8",
+    "typescript": "^5.4.5"
+  },
+  "type": "module",
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./matchers.js";
+export * from "./runner/single.js";
+export * from "./runner/collection.js";
+export * from "./spectra.js";
+export * from "./proto.js";

package/src/matchers.ts

@@ -0,0 +1,131 @@
+import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./types.js";
+
+/**
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
+ * to an actionable WebdriverIO.Element.
+ */
+export async function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element> {
+  if (typeof target === "string") {
+    const el = await $(target);
+    return el as unknown as WebdriverIO.Element;
+  }
+  const el = await (target as any);
+  return el as unknown as WebdriverIO.Element;
+}
+
+/**
+ * Executes a single element matcher against the WebdriverIO browser / element context.
+ */
+export async function executeSingleMatcher(
+  target: ElementTarget | undefined,
+  matcher: SingleElementMatcher,
+  args: any[]
+): Promise<void> {
+  const isBrowserLevel =
+    matcher === "have.url" ||
+    matcher === "contain.url" ||
+    matcher === "have.title" ||
+    matcher === "contain.title";
+
+  if (isBrowserLevel) {
+    const expected = args[0];
+    switch (matcher) {
+      case "have.url":
+        await expect(browser).toHaveUrl(expected);
+        break;
+      case "contain.url":
+        await expect(browser).toHaveUrl(expect.stringContaining(expected));
+        break;
+      case "have.title":
+        await expect(browser).toHaveTitle(expected);
+        break;
+      case "contain.title":
+        await expect(browser).toHaveTitle(expect.stringContaining(expected));
+        break;
+    }
+    return;
+  }
+
+  if (!target) {
+    throw new Error(`Assertion matcher '${matcher}' requires an element target.`);
+  }
+
+  const el = await resolveElement(target);
+
+  switch (matcher) {
+    case "be.visible":
+      await expect(el).toBeDisplayed();
+      break;
+    case "not.be.visible":
+      await expect(el).not.toBeDisplayed();
+      break;
+    case "exist":
+      await expect(el).toExist();
+      break;
+    case "not.exist":
+      await expect(el).not.toExist();
+      break;
+    case "be.enabled":
+      await expect(el).toBeEnabled();
+      break;
+    case "be.disabled":
+      await expect(el).toBeDisabled();
+      break;
+    case "be.checked":
+    case "be.selected":
+      await expect(el).toBeSelected();
+      break;
+    case "have.value":
+      await expect(el).toHaveValue(args[0]);
+      break;
+    case "contain.value":
+      await expect(el).toHaveValue(expect.stringContaining(args[0]));
+      break;
+    case "have.text":
+      await expect(el).toHaveText(args[0]);
+      break;
+    case "contain.text":
+      await expect(el).toHaveText(expect.stringContaining(args[0]));
+      break;
+    case "have.class":
+      await expect(el).toHaveElementClass(args[0]);
+      break;
+    case "have.attr":
+      if (args.length >= 2) {
+        await expect(el).toHaveAttribute(args[0], args[1]);
+      } else {
+        await expect(el).toHaveAttribute(args[0]);
+      }
+      break;
+    default:
+      throw new Error(`Unsupported matcher: ${matcher}`);
+  }
+}
+
+/**
+ * Executes a multi-element collection matcher against WebdriverIO $$.
+ */
+export async function executeMultiMatcher(
+  selector: string,
+  matcher: MultiElementMatcher,
+  args: any[]
+): Promise<void> {
+  const elements = await $$(selector);
+
+  switch (matcher) {
+    case "have.length":
+      await expect(elements).toBeElementsArrayOfSize(args[0]);
+      break;
+    case "have.length.greaterThan":
+      await expect(elements).toBeElementsArrayOfSize({ gte: args[0] + 1 });
+      break;
+    case "be.empty":
+      await expect(elements).toBeElementsArrayOfSize(0);
+      break;
+    case "exist":
+      await expect(elements).toBeElementsArrayOfSize({ gte: 1 });
+      break;
+    default:
+      throw new Error(`Unsupported multi-element matcher: ${matcher}`);
+  }
+}

package/src/proto.ts

@@ -0,0 +1,163 @@
+import { ElementTarget } from "./types.js";
+import { resolveElement } from "./matchers.js";
+
+declare global {
+  namespace WebdriverIO {
+    interface Element {
+      shouldBeVisible(): Promise<Element>;
+      shouldNotBeVisible(): Promise<Element>;
+      shouldExist(): Promise<Element>;
+      shouldNotExist(): Promise<Element>;
+      shouldBeEnabled(): Promise<Element>;
+      shouldBeDisabled(): Promise<Element>;
+      shouldBeSelected(): Promise<Element>;
+      shouldBeChecked(): Promise<Element>;
+      shouldHaveValue(expectedValue: string): Promise<Element>;
+      shouldContainValue(expectedValue: string): Promise<Element>;
+      shouldHaveText(expectedText: string): Promise<Element>;
+      shouldContainText(expectedText: string): Promise<Element>;
+      shouldHaveClass(className: string): Promise<Element>;
+      shouldHaveAttribute(attributeName: string, expectedValue?: string): Promise<Element>;
+    }
+
+    interface Browser {
+      shouldHaveUrl(expectedUrl: string): Promise<void>;
+      shouldContainUrl(expectedUrl: string): Promise<void>;
+      shouldHaveTitle(expectedTitle: string): Promise<void>;
+      shouldContainTitle(expectedTitle: string): Promise<void>;
+    }
+  }
+
+  interface Promise<T> {
+    shouldBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldNotBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldNotExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeEnabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeDisabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeSelected(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeChecked(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldHaveValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
+    shouldContainValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
+    shouldHaveText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
+    shouldContainText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
+    shouldHaveClass(this: Promise<WebdriverIO.Element>, className: string): Promise<WebdriverIO.Element>;
+    shouldHaveAttribute(this: Promise<WebdriverIO.Element>, attributeName: string, expectedValue?: string): Promise<WebdriverIO.Element>;
+  }
+}
+
+/**
+ * Install direct callable assertion methods onto WebdriverIO browser/element and Promise prototypes.
+ */
+export function installPrototypes() {
+  const elementCommands: Record<string, Function> = {
+    async shouldBeVisible(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeDisplayed();
+      return el;
+    },
+    async shouldNotBeVisible(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).not.toBeDisplayed();
+      return el;
+    },
+    async shouldExist(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toExist();
+      return el;
+    },
+    async shouldNotExist(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).not.toExist();
+      return el;
+    },
+    async shouldBeEnabled(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeEnabled();
+      return el;
+    },
+    async shouldBeDisabled(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeDisabled();
+      return el;
+    },
+    async shouldBeSelected(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeSelected();
+      return el;
+    },
+    async shouldBeChecked(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeSelected();
+      return el;
+    },
+    async shouldHaveValue(this: any, val: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveValue(val);
+      return el;
+    },
+    async shouldContainValue(this: any, val: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveValue(expect.stringContaining(val));
+      return el;
+    },
+    async shouldHaveText(this: any, text: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveText(text);
+      return el;
+    },
+    async shouldContainText(this: any, text: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveText(expect.stringContaining(text));
+      return el;
+    },
+    async shouldHaveClass(this: any, cls: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveElementClass(cls);
+      return el;
+    },
+    async shouldHaveAttribute(this: any, name: string, val?: string) {
+      const el = await resolveElement(this);
+      if (val !== undefined) {
+        await expect(el).toHaveAttribute(name, val);
+      } else {
+        await expect(el).toHaveAttribute(name);
+      }
+      return el;
+    },
+  };
+
+  const browserCommands: Record<string, Function> = {
+    async shouldHaveUrl(url: string) {
+      await expect(browser).toHaveUrl(url);
+    },
+    async shouldContainUrl(url: string) {
+      await expect(browser).toHaveUrl(expect.stringContaining(url));
+    },
+    async shouldHaveTitle(title: string) {
+      await expect(browser).toHaveTitle(title);
+    },
+    async shouldContainTitle(title: string) {
+      await expect(browser).toHaveTitle(expect.stringContaining(title));
+    },
+  };
+
+  if (typeof browser !== "undefined" && (browser as any).addCommand) {
+    for (const [name, fn] of Object.entries(elementCommands)) {
+      (browser as any).addCommand(name, fn, true);
+    }
+    for (const [name, fn] of Object.entries(browserCommands)) {
+      (browser as any).addCommand(name, fn, false);
+    }
+  }
+
+  // Attach to Promise.prototype for ChainablePromiseElement unwrapping
+  for (const [name, fn] of Object.entries(elementCommands)) {
+    if (typeof (Promise.prototype as any)[name] !== "function") {
+      (Promise.prototype as any)[name] = async function (this: Promise<any>, ...args: any[]) {
+        const el = await this;
+        return await fn.call(el, ...args);
+      };
+    }
+  }
+}

package/src/runner/collection.ts

@@ -0,0 +1,73 @@
+import { MultiElementMatcher } from "../types.js";
+import { executeMultiMatcher } from "../matchers.js";
+import { SingleElementRunner } from "./single.js";
+
+type CollectionAssertion = {
+  matcher: MultiElementMatcher;
+  args: any[];
+};
+
+export class MultiElementRunner implements PromiseLike<void> {
+  private _selector: string;
+  private _assertions: CollectionAssertion[] = [];
+
+  constructor(selector: string) {
+    this._selector = selector;
+  }
+
+  // --- Collection Assertions ---
+
+  should(matcher: MultiElementMatcher, ...args: any[]): this {
+    this._assertions.push({ matcher, args });
+    return this;
+  }
+
+  // --- Item Navigation ---
+
+  eq(index: number): SingleElementRunner {
+    const indexedSelector = `(${this._selector})[${index + 1}]`;
+    return new SingleElementRunner(indexedSelector);
+  }
+
+  first(): SingleElementRunner {
+    return this.eq(0);
+  }
+
+  last(): SingleElementRunner {
+    const indexedSelector = `(${this._selector})[last()]`;
+    return new SingleElementRunner(indexedSelector);
+  }
+
+  // --- Iteration Callback ---
+
+  async each(
+    callback: (el: SingleElementRunner, index: number) => Promise<void>
+  ): Promise<void> {
+    const elements = await $$(this._selector);
+    const count = await (elements as any).length;
+    for (let i = 0; i < count; i++) {
+      const runner = this.eq(i);
+      await callback(runner, i);
+    }
+  }
+
+  // --- 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 {
+      for (const assert of this._assertions) {
+        await executeMultiMatcher(this._selector, assert.matcher, assert.args);
+      }
+      const res = (onfulfilled ? await onfulfilled() : undefined) as TResult1;
+      return res;
+    } catch (err) {
+      if (onrejected) {
+        return onrejected(err);
+      }
+      throw err;
+    }
+  }
+}