@testspectra/matchers 1.0.69 → 1.1.0

package/dist/proto.d.ts

@@ -1,288 +1,23 @@
+import type { SpectraBrowserBridge, SpectraStatic } from './types.js';
 declare global {
+    /**
+     * The global TestSpectra static automation and assertion instance.
+     */
+    var Spectra: SpectraStatic;
+    /**
+     * The global TestSpectra browser bridge instance.
+     */
+    var browser: SpectraBrowserBridge;
+    /**
+     * Global fixture store injected by TestSpectra runner.
+     */
+    var Fixture: Record<string, any>;
+    /**
+     * Global step library injected by TestSpectra runner.
+     */
+    var Step: Record<string, any>;
     namespace WebdriverIO {
-        interface Element {
-            /**
-             * Asserts that the element is displayed on the screen and visible to the user.
-             *
-             * @example
-             * ```ts
-             * await LoginPage.submitButton.shouldBeVisible();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldBeVisible(): Promise<Element>;
-            /**
-             * Asserts that the element is NOT displayed or is hidden from view.
-             *
-             * @example
-             * ```ts
-             * await LoginPage.errorMessage.shouldNotBeVisible();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldNotBeVisible(): Promise<Element>;
-            /**
-             * Asserts that the element exists in the DOM/UI hierarchy.
-             *
-             * @example
-             * ```ts
-             * await LoginPage.rememberMeCheckbox.shouldExist();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldExist(): Promise<Element>;
-            /**
-             * Asserts that the element does NOT exist in the DOM/UI hierarchy.
-             *
-             * @example
-             * ```ts
-             * await LoginPage.loadingSpinner.shouldNotExist();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldNotExist(): Promise<Element>;
-            /**
-             * Asserts that the element is enabled for interaction.
-             *
-             * @example
-             * ```ts
-             * await LoginPage.loginButton.shouldBeEnabled();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldBeEnabled(): Promise<Element>;
-            /**
-             * Asserts that the element is disabled (cannot be interacted with).
-             *
-             * @example
-             * ```ts
-             * await LoginPage.disabledSubmit.shouldBeDisabled();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldBeDisabled(): Promise<Element>;
-            /**
-             * Asserts that the form element (radio button, checkbox, option) is selected.
-             *
-             * @example
-             * ```ts
-             * await SettingsPage.darkModeRadio.shouldBeSelected();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldBeSelected(): Promise<Element>;
-            /**
-             * Asserts that the checkbox or radio element is checked.
-             *
-             * @example
-             * ```ts
-             * await SettingsPage.termsCheckbox.shouldBeChecked();
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldBeChecked(): Promise<Element>;
-            /**
-             * Asserts that the input element has the exact given value.
-             *
-             * @param expectedValue - The exact expected value.
-             * @example
-             * ```ts
-             * await LoginPage.usernameInput.shouldHaveValue("admin@test.com");
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldHaveValue(expectedValue: string): Promise<Element>;
-            /**
-             * Asserts that the input element's value contains the given substring.
-             *
-             * @param expectedValue - Substring expected to be present in the value.
-             * @example
-             * ```ts
-             * await LoginPage.tokenInput.shouldContainValue("JWT_");
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldContainValue(expectedValue: string): Promise<Element>;
-            /**
-             * Asserts that the element's text content matches the exact expected text.
-             *
-             * @param expectedText - The exact expected text content.
-             * @example
-             * ```ts
-             * await LoginPage.headerTitle.shouldHaveText("Welcome to TestSpectra");
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldHaveText(expectedText: string): Promise<Element>;
-            /**
-             * Asserts that the element's text content contains the expected substring.
-             *
-             * @param expectedText - Substring expected to be within the element text.
-             * @example
-             * ```ts
-             * await LoginPage.welcomeBanner.shouldContainText("Welcome");
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldContainText(expectedText: string): Promise<Element>;
-            /**
-             * Asserts that the element has the specified CSS class.
-             *
-             * @param className - Expected CSS class name.
-             * @example
-             * ```ts
-             * await NavigationBar.homeTab.shouldHaveClass("is-active");
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldHaveClass(className: string): Promise<Element>;
-            /**
-             * Asserts that the element has the specified attribute, optionally checking its exact value.
-             *
-             * @param attributeName - Name of the attribute (e.g. `aria-label`, `disabled`, `href`).
-             * @param expectedValue - Optional expected value of the attribute.
-             * @example
-             * ```ts
-             * await NavigationBar.logoLink.shouldHaveAttribute("href", "/dashboard");
-             * await NavigationBar.cartButton.shouldHaveAttribute("aria-expanded");
-             * ```
-             * @returns The element instance for chaining.
-             */
-            shouldHaveAttribute(attributeName: string, expectedValue?: string): Promise<Element>;
+        interface Browser extends SpectraBrowserBridge {
         }
-        /**
-         * Optional settings for HTTP network interception responses.
-         */
-        interface InterceptFixtureOptions {
-            /** HTTP status code to return in the mocked response (default: 200) */
-            statusCode?: number;
-            /** Custom HTTP response headers */
-            headers?: Record<string, string>;
-        }
-        /**
-         * Structured mock payload object with optional status code and headers.
-         */
-        interface InterceptFixtureObject<TData = unknown> {
-            /** HTTP status code */
-            statusCode?: number;
-            /** Response body payload */
-            body: TData;
-            /** Custom HTTP response headers */
-            headers?: Record<string, string>;
-        }
-        /**
-         * Input payload for API mocking: JSON object, string, or structured fixture object.
-         */
-        type InterceptInput<TData = unknown> = InterceptFixtureObject<TData> | TData | string;
-        interface Mock {
-            /**
-             * Dynamically set or change the fixture response for this mock instance.
-             * Supports fixture file paths, structured `{ statusCode, body, headers }` objects, or raw data.
-             *
-             * @param fixture - Data payload or Fixture reference.
-             * @param options - Optional status code and header overrides.
-             * @example
-             * ```ts
-             * const mock = await browser.intercept("/api/user", "GET");
-             * await mock.respondWith({ name: "Admin", role: "superadmin" });
-             * ```
-             */
-            respondWith<TData = unknown>(fixture: InterceptInput<TData>, options?: InterceptFixtureOptions): Promise<void>;
-        }
-        interface Browser {
-            /**
-             * Intercepts and mocks network API requests matching the specified endpoint.
-             * Supports automatic base URL resolution and TestSpectra JSON Fixtures.
-             *
-             * @param path - URL path or route to intercept (e.g. `"/api/users"` or `"https://api.example.com/v1/*"`).
-             * @param method - HTTP request method (`"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, `"PATCH"`).
-             * @param fixture - Optional initial response payload or Fixture object.
-             * @param options - Optional status code and header configuration.
-             * @example
-             * ```ts
-             * // Intercept with JSON Fixture
-             * await browser.intercept("/api/status", "GET", Fixture.userData);
-             *
-             * // Intercept with custom payload & status code
-             * await browser.intercept("/api/auth/login", "POST", { token: "xyz" }, { statusCode: 200 });
-             * ```
-             * @returns `Mock` instance allowing dynamic response modification.
-             */
-            intercept<TData = unknown>(path: string, method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH", fixture?: InterceptInput<TData>, options?: InterceptFixtureOptions): Promise<Mock>;
-            /**
-             * Asserts that the current browser page URL exactly matches the expected URL.
-             *
-             * @param expectedUrl - The exact URL expected.
-             * @example
-             * ```ts
-             * await browser.shouldHaveUrl("https://app.example.com/dashboard");
-             * ```
-             */
-            shouldHaveUrl(expectedUrl: string): Promise<void>;
-            /**
-             * Asserts that the current browser page URL contains the given substring.
-             *
-             * @param expectedUrl - Substring expected in the current URL.
-             * @example
-             * ```ts
-             * await browser.shouldContainUrl("/dashboard");
-             * ```
-             */
-            shouldContainUrl(expectedUrl: string): Promise<void>;
-            /**
-             * Asserts that the current browser page title matches the expected title.
-             *
-             * @param expectedTitle - The exact title expected.
-             * @example
-             * ```ts
-             * await browser.shouldHaveTitle("Dashboard - TestSpectra");
-             * ```
-             */
-            shouldHaveTitle(expectedTitle: string): Promise<void>;
-            /**
-             * Asserts that the current browser page title contains the expected substring.
-             *
-             * @param expectedTitle - Substring expected in the title.
-             * @example
-             * ```ts
-             * await browser.shouldContainTitle("Dashboard");
-             * ```
-             */
-            shouldContainTitle(expectedTitle: string): Promise<void>;
-        }
-    }
-    interface Promise<T> {
-        /** Asserts that the element promise resolves to a visible element. */
-        shouldBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to a hidden/non-visible element. */
-        shouldNotBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an existing element in the DOM. */
-        shouldExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element that does not exist in the DOM. */
-        shouldNotExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an enabled element. */
-        shouldBeEnabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to a disabled element. */
-        shouldBeDisabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to a selected element. */
-        shouldBeSelected(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to a checked checkbox or radio. */
-        shouldBeChecked(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element with the exact value. */
-        shouldHaveValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element whose value contains the substring. */
-        shouldContainValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element with the exact text content. */
-        shouldHaveText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element whose text contains the substring. */
-        shouldContainText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element having the CSS class. */
-        shouldHaveClass(this: Promise<WebdriverIO.Element>, className: string): Promise<WebdriverIO.Element>;
-        /** Asserts that the element promise resolves to an element having the attribute. */
-        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

@@ -1,114 +1 @@
-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);
-            };
-        }
-    }
-}
+export {};

package/dist/reporter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Interactive Command Reporter
+ *
+ * Real-time, single-line colorful reporter for every action, assertion,
+ * and browser command executed within the TestSpectra test lifecycle.
+ */
+export declare const colors: {
+    reset: string;
+    bold: string;
+    dim: string;
+    italic: string;
+    underline: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    gray: string;
+    passBadge: string;
+    failBadge: string;
+};
+export declare function formatTarget(target: any): string;
+export declare function formatArgs(args: any[]): string;
+/**
+ * Tracks and reports a single TestSpectra command with live interactive single-line feedback.
+ */
+export declare function trackCommand<T>(category: 'action' | 'assertion' | 'browser' | 'step', commandText: string | object, fn: () => Promise<T>): Promise<T>;

package/dist/reporter.js

@@ -0,0 +1,85 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Interactive Command Reporter
+ *
+ * Real-time, single-line colorful reporter for every action, assertion,
+ * and browser command executed within the TestSpectra test lifecycle.
+ */
+export const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[90m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+    // Vibrant ANSI colors
+    red: '\x1b[38;2;248;113;113m', // Light coral red
+    green: '\x1b[38;2;52;211;153m', // Emerald green
+    yellow: '\x1b[38;2;251;191;36m', // Amber yellow
+    blue: '\x1b[38;2;96;165;250m', // Sky blue
+    magenta: '\x1b[38;2;192;132;252m', // Purple
+    cyan: '\x1b[38;2;45;212;191m', // Teal / Cyan
+    white: '\x1b[38;2;241;245;249m', // Crisp white
+    gray: '\x1b[38;2;148;163;184m', // Slate gray
+    // Status symbols
+    passBadge: '\x1b[38;2;52;211;153m✓\x1b[0m',
+    failBadge: '\x1b[38;2;248;113;113m✗\x1b[0m',
+};
+export function formatTarget(target) {
+    if (target === undefined || target === null)
+        return 'Spectra';
+    if (typeof target === 'string') {
+        return `Spectra.get("${target}")`;
+    }
+    if (typeof target === 'object') {
+        if (target.selector) {
+            return `Spectra.get("${target.selector}")`;
+        }
+        if (target.constructor && target.constructor.name && target.constructor.name !== 'Object') {
+            return target.constructor.name;
+        }
+    }
+    return String(target);
+}
+export function formatArgs(args) {
+    if (!args || args.length === 0)
+        return '';
+    return args
+        .map((a) => {
+        if (typeof a === 'string')
+            return `"${a}"`;
+        if (typeof a === 'number' || typeof a === 'boolean')
+            return String(a);
+        if (a === null)
+            return 'null';
+        if (a === undefined)
+            return 'undefined';
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(', ');
+}
+/**
+ * Tracks and reports a single TestSpectra command with live interactive single-line feedback.
+ */
+export async function trackCommand(category, commandText, fn) {
+    const start = Date.now();
+    const payload = typeof commandText === 'object' ? JSON.stringify(commandText) : commandText;
+    console.log(`[TESTSPECTRA_STEP_START] ${payload}`);
+    try {
+        const result = await fn();
+        const duration = Date.now() - start;
+        console.log(`[TESTSPECTRA_STEP_PASS] ${payload} (${duration}ms)`);
+        return result;
+    }
+    catch (err) {
+        const duration = Date.now() - start;
+        console.log(`[TESTSPECTRA_STEP_FAIL] ${payload} (${duration}ms)`);
+        const msg = err && err.message ? err.message : String(err);
+        console.log(`[TESTSPECTRA_TEST_ERROR] ${msg}`);
+        throw err;
+    }
+}

package/dist/runner/collection.d.ts

@@ -1,43 +1,56 @@
-import { MultiElementMatcher } from "../types.js";
-import { SingleElementRunner } from "./single.js";
+import { CollectionReceiverAssertions } from '../types.js';
+import { SingleElementRunner } from './single.js';
 /**
  * Fluent assertion, filtering, and iteration runner for multi-element collections.
  *
- * Implements `PromiseLike<void>`, allowing assertions across matching elements,
+ * Implements `PromiseLike<void>` and `CollectionReceiverAssertions<MultiElementRunner>`,
+ * allowing assertions across matching elements,
  * array index access (`.eq()`, `.first()`, `.last()`), and sequential iteration (`.each()`).
  *
  * @example
  * ```ts
  * // Assert collection size
- * await Spectra.getAll(".cart-item").should("have.length", 3);
+ * await Spectra.getAll(".cart-item").shouldHaveLength(3);
  *
  * // Target specific element from collection
  * await Spectra.getAll(".todo-item").first().click();
- * await Spectra.getAll(".todo-item").eq(2).should("have.text", "Buy Milk");
+ * await Spectra.getAll(".todo-item").eq(2).shouldHaveText("Buy Milk");
  *
  * // Iteration
  * await Spectra.getAll(".nav-link").each(async (link, i) => {
- *   await link.should("be.visible");
+ *   await link.shouldBeVisible();
  * });
  * ```
  */
-export declare class MultiElementRunner implements PromiseLike<void> {
+export declare class MultiElementRunner implements PromiseLike<void>, CollectionReceiverAssertions<MultiElementRunner> {
     private _selector;
     private _assertions;
     constructor(selector: string);
+    private _pushAssertion;
     /**
-     * Queues an assertion matcher against the multi-element collection.
-     *
-     * @param matcher - Multi-element matcher string (e.g. `'have.length'`, `'be.empty'`).
-     * @param args - Expected values or limits for the matcher.
-     * @example
-     * ```ts
-     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
-     * await Spectra.getAll(".error-badge").should("be.empty");
-     * ```
-     * @returns Current collection runner instance for chaining.
+     * Asserts that the collection contains exactly `count` elements.
+     */
+    shouldHaveLength(count: number): this;
+    /**
+     * Asserts that the collection does not contain `count` elements.
+     */
+    shouldNotHaveLength(count: number): this;
+    /**
+     * Asserts that the collection contains more than `min` elements.
+     */
+    shouldHaveLengthGreaterThan(min: number): this;
+    /**
+     * Asserts that the collection contains less than `max` elements.
+     */
+    shouldHaveLengthLessThan(max: number): this;
+    /**
+     * Asserts that the collection is empty (contains 0 elements).
+     */
+    shouldBeEmpty(): this;
+    /**
+     * Asserts that the collection is not empty (contains at least 1 element).
      */
-    should(matcher: MultiElementMatcher, ...args: any[]): this;
+    shouldNotBeEmpty(): this;
     /**
      * Returns a `SingleElementRunner` targeting the element at the specified 0-based index.
      *
@@ -64,7 +77,7 @@ export declare class MultiElementRunner implements PromiseLike<void> {
      *
      * @example
      * ```ts
-     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
+     * await Spectra.getAll(".step-indicator").last().shouldHaveClass("current");
      * ```
      * @returns `SingleElementRunner` for the last element.
      */
@@ -76,7 +89,7 @@ export declare class MultiElementRunner implements PromiseLike<void> {
      * @example
      * ```ts
      * await Spectra.getAll(".checkbox").each(async (item, index) => {
-     *   await item.should("be.visible");
+     *   await item.shouldBeVisible();
      * });
      * ```
      */