@testspectra/matchers 1.0.0

package/dist/index.d.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/dist/index.js

@@ -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/dist/matchers.d.ts

@@ -0,0 +1,14 @@
+import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./types.js";
+/**
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
+ * to an actionable WebdriverIO.Element.
+ */
+export declare function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element>;
+/**
+ * Executes a single element matcher against the WebdriverIO browser / element context.
+ */
+export declare function executeSingleMatcher(target: ElementTarget | undefined, matcher: SingleElementMatcher, args: any[]): Promise<void>;
+/**
+ * Executes a multi-element collection matcher against WebdriverIO $$.
+ */
+export declare function executeMultiMatcher(selector: string, matcher: MultiElementMatcher, args: any[]): Promise<void>;

package/dist/matchers.js

@@ -0,0 +1,114 @@
+/**
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
+ * to an actionable WebdriverIO.Element.
+ */
+export async function resolveElement(target) {
+    if (typeof target === "string") {
+        const el = await $(target);
+        return el;
+    }
+    const el = await target;
+    return el;
+}
+/**
+ * Executes a single element matcher against the WebdriverIO browser / element context.
+ */
+export async function executeSingleMatcher(target, matcher, args) {
+    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, matcher, args) {
+    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/dist/proto.d.ts

@@ -0,0 +1,46 @@
+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 declare function installPrototypes(): void;

package/dist/proto.js

@@ -0,0 +1,114 @@
+import { resolveElement } from "./matchers.js";
+/**
+ * Install direct callable assertion methods onto WebdriverIO browser/element and Promise prototypes.
+ */
+export function installPrototypes() {
+    const elementCommands = {
+        async shouldBeVisible() {
+            const el = await resolveElement(this);
+            await expect(el).toBeDisplayed();
+            return el;
+        },
+        async shouldNotBeVisible() {
+            const el = await resolveElement(this);
+            await expect(el).not.toBeDisplayed();
+            return el;
+        },
+        async shouldExist() {
+            const el = await resolveElement(this);
+            await expect(el).toExist();
+            return el;
+        },
+        async shouldNotExist() {
+            const el = await resolveElement(this);
+            await expect(el).not.toExist();
+            return el;
+        },
+        async shouldBeEnabled() {
+            const el = await resolveElement(this);
+            await expect(el).toBeEnabled();
+            return el;
+        },
+        async shouldBeDisabled() {
+            const el = await resolveElement(this);
+            await expect(el).toBeDisabled();
+            return el;
+        },
+        async shouldBeSelected() {
+            const el = await resolveElement(this);
+            await expect(el).toBeSelected();
+            return el;
+        },
+        async shouldBeChecked() {
+            const el = await resolveElement(this);
+            await expect(el).toBeSelected();
+            return el;
+        },
+        async shouldHaveValue(val) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveValue(val);
+            return el;
+        },
+        async shouldContainValue(val) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveValue(expect.stringContaining(val));
+            return el;
+        },
+        async shouldHaveText(text) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveText(text);
+            return el;
+        },
+        async shouldContainText(text) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveText(expect.stringContaining(text));
+            return el;
+        },
+        async shouldHaveClass(cls) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveElementClass(cls);
+            return el;
+        },
+        async shouldHaveAttribute(name, val) {
+            const el = await resolveElement(this);
+            if (val !== undefined) {
+                await expect(el).toHaveAttribute(name, val);
+            }
+            else {
+                await expect(el).toHaveAttribute(name);
+            }
+            return el;
+        },
+    };
+    const browserCommands = {
+        async shouldHaveUrl(url) {
+            await expect(browser).toHaveUrl(url);
+        },
+        async shouldContainUrl(url) {
+            await expect(browser).toHaveUrl(expect.stringContaining(url));
+        },
+        async shouldHaveTitle(title) {
+            await expect(browser).toHaveTitle(title);
+        },
+        async shouldContainTitle(title) {
+            await expect(browser).toHaveTitle(expect.stringContaining(title));
+        },
+    };
+    if (typeof browser !== "undefined" && browser.addCommand) {
+        for (const [name, fn] of Object.entries(elementCommands)) {
+            browser.addCommand(name, fn, true);
+        }
+        for (const [name, fn] of Object.entries(browserCommands)) {
+            browser.addCommand(name, fn, false);
+        }
+    }
+    // Attach to Promise.prototype for ChainablePromiseElement unwrapping
+    for (const [name, fn] of Object.entries(elementCommands)) {
+        if (typeof Promise.prototype[name] !== "function") {
+            Promise.prototype[name] = async function (...args) {
+                const el = await this;
+                return await fn.call(el, ...args);
+            };
+        }
+    }
+}

package/dist/runner/collection.d.ts

@@ -0,0 +1,13 @@
+import { MultiElementMatcher } from "../types.js";
+import { SingleElementRunner } from "./single.js";
+export declare class MultiElementRunner implements PromiseLike<void> {
+    private _selector;
+    private _assertions;
+    constructor(selector: string);
+    should(matcher: MultiElementMatcher, ...args: any[]): this;
+    eq(index: number): SingleElementRunner;
+    first(): SingleElementRunner;
+    last(): SingleElementRunner;
+    each(callback: (el: SingleElementRunner, index: number) => Promise<void>): Promise<void>;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}

package/dist/runner/collection.js

@@ -0,0 +1,51 @@
+import { executeMultiMatcher } from "../matchers.js";
+import { SingleElementRunner } from "./single.js";
+export class MultiElementRunner {
+    _selector;
+    _assertions = [];
+    constructor(selector) {
+        this._selector = selector;
+    }
+    // --- Collection Assertions ---
+    should(matcher, ...args) {
+        this._assertions.push({ matcher, args });
+        return this;
+    }
+    // --- Item Navigation ---
+    eq(index) {
+        const indexedSelector = `(${this._selector})[${index + 1}]`;
+        return new SingleElementRunner(indexedSelector);
+    }
+    first() {
+        return this.eq(0);
+    }
+    last() {
+        const indexedSelector = `(${this._selector})[last()]`;
+        return new SingleElementRunner(indexedSelector);
+    }
+    // --- Iteration Callback ---
+    async each(callback) {
+        const elements = await $$(this._selector);
+        const count = await elements.length;
+        for (let i = 0; i < count; i++) {
+            const runner = this.eq(i);
+            await callback(runner, i);
+        }
+    }
+    // --- Execution when awaited ---
+    async then(onfulfilled, onrejected) {
+        try {
+            for (const assert of this._assertions) {
+                await executeMultiMatcher(this._selector, assert.matcher, assert.args);
+            }
+            const res = (onfulfilled ? await onfulfilled() : undefined);
+            return res;
+        }
+        catch (err) {
+            if (onrejected) {
+                return onrejected(err);
+            }
+            throw err;
+        }
+    }
+}

package/dist/runner/single.d.ts

@@ -0,0 +1,21 @@
+import { SingleElementMatcher, ElementTarget } from "../types.js";
+export declare class SingleElementRunner implements PromiseLike<void> {
+    private _target;
+    private _action;
+    private _assertions;
+    constructor(target?: ElementTarget, action?: () => Promise<any>);
+    click(): this;
+    doubleClick(): this;
+    longPress(durationMs?: number): this;
+    type(value: string, options?: {
+        clearFirst?: boolean;
+    }): this;
+    clear(): this;
+    select(value: string): this;
+    hover(): this;
+    waitForElement(timeoutMs?: number): this;
+    should(matcher: SingleElementMatcher, ...args: any[]): this;
+    should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private requireTarget;
+}

package/dist/runner/single.js

@@ -0,0 +1,138 @@
+import { executeSingleMatcher, resolveElement } from "../matchers.js";
+export class SingleElementRunner {
+    _target;
+    _action = null;
+    _assertions = [];
+    constructor(target, action) {
+        this._target = target;
+        this._action = action || null;
+    }
+    // --- Chained Actions on current target ---
+    click() {
+        const target = this.requireTarget("click");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.click();
+        };
+        return this;
+    }
+    doubleClick() {
+        const target = this.requireTarget("doubleClick");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.doubleClick();
+        };
+        return this;
+    }
+    longPress(durationMs = 1000) {
+        const target = this.requireTarget("longPress");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            if (typeof el.touchAction === "function") {
+                await el.touchAction([
+                    { action: "longPress", ms: durationMs },
+                    { action: "release" },
+                ]);
+            }
+            else {
+                await el.click();
+            }
+        };
+        return this;
+    }
+    type(value, options) {
+        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() {
+        const target = this.requireTarget("clear");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.clearValue();
+        };
+        return this;
+    }
+    select(value) {
+        const target = this.requireTarget("select");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.selectByVisibleText(value);
+        };
+        return this;
+    }
+    hover() {
+        const target = this.requireTarget("hover");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.moveTo();
+        };
+        return this;
+    }
+    waitForElement(timeoutMs = 10000) {
+        const target = this.requireTarget("waitForElement");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.waitForDisplayed({ timeout: timeoutMs });
+        };
+        return this;
+    }
+    should(a, b, ...rest) {
+        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,
+                matcher: b,
+                args: rest,
+            });
+        }
+        else {
+            // Form: should(matcher, ...args) -> on current target
+            this._assertions.push({
+                target: this._target,
+                matcher: a,
+                args: b !== undefined ? [b, ...rest] : rest,
+            });
+        }
+        return this;
+    }
+    // --- Execution when awaited ---
+    async then(onfulfilled, onrejected) {
+        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);
+            return res;
+        }
+        catch (err) {
+            if (onrejected) {
+                return onrejected(err);
+            }
+            throw err;
+        }
+    }
+    requireTarget(actionName) {
+        if (!this._target) {
+            throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);
+        }
+        return this._target;
+    }
+}

package/dist/spectra.d.ts

@@ -0,0 +1,34 @@
+import { ClickOptions, ElementTarget, KeyOption, LongPressOptions, ScrollOptions, SwipeOptions, TypeOptions } from "./types.js";
+import { SingleElementRunner } from "./runner/single.js";
+import { MultiElementRunner } from "./runner/collection.js";
+/**
+ * Main Spectra testing API orchestrator.
+ * Combines direct actions, single element queries (get), and collections (getAll).
+ */
+export declare class SpectraStatic {
+    /**
+     * Targets a single element by selector or Page Object element.
+     */
+    get(target: ElementTarget): SingleElementRunner;
+    /**
+     * Targets multiple elements / collections by selector.
+     */
+    getAll(selector: string): MultiElementRunner;
+    navigate(url: string): SingleElementRunner;
+    back(): SingleElementRunner;
+    refresh(): SingleElementRunner;
+    click(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    doubleClick(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    longPress(target: ElementTarget, options?: LongPressOptions | number): SingleElementRunner;
+    type(target: ElementTarget, value: string, options?: TypeOptions): SingleElementRunner;
+    clear(target: ElementTarget): SingleElementRunner;
+    select(target: ElementTarget, value: string): SingleElementRunner;
+    hover(target: ElementTarget): SingleElementRunner;
+    pressKey(key: KeyOption | string): SingleElementRunner;
+    dragDrop(sourceTarget: ElementTarget, destTarget: ElementTarget): SingleElementRunner;
+    scroll(options?: ScrollOptions): SingleElementRunner;
+    swipe(options: SwipeOptions): SingleElementRunner;
+    wait(durationMs: number): SingleElementRunner;
+    waitForElement(target: ElementTarget, timeoutMs?: number): SingleElementRunner;
+}
+export declare const Spectra: SpectraStatic;