@testspectra/matchers 1.0.41 → 1.0.42

package/dist/index.d.ts

@@ -1,3 +1,23 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers
+ *
+ * Cross-platform action commands, fluent runners, and callable assertion matchers for TestSpectra.
+ *
+ * ## Features:
+ * - **`Spectra`**: Unified automation API (`Spectra.get()`, `Spectra.getAll()`, `Spectra.click()`, `Spectra.type()`, etc.)
+ * - **`SingleElementRunner`**: Fluent interaction & assertion runner for single element targets
+ * - **`MultiElementRunner`**: Fluent assertion & traversal runner for multi-element collections
+ * - **Callable Matchers**: Ambient prototypes for WebdriverIO Element & Browser (`.shouldBeVisible()`, `.shouldHaveText()`, etc.)
+ *
+ * @example
+ * ```ts
+ * import { Spectra } from "@testspectra/matchers";
+ *
+ * await Spectra.get("#login-btn").click().should("not.be.visible");
+ * await Spectra.getAll(".list-item").should("have.length.greaterThan", 0);
+ * ```
+ */
 export * from "./types.js";
 export * from "./matchers.js";
 export * from "./runner/single.js";

package/dist/index.js

@@ -1,3 +1,23 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers
+ *
+ * Cross-platform action commands, fluent runners, and callable assertion matchers for TestSpectra.
+ *
+ * ## Features:
+ * - **`Spectra`**: Unified automation API (`Spectra.get()`, `Spectra.getAll()`, `Spectra.click()`, `Spectra.type()`, etc.)
+ * - **`SingleElementRunner`**: Fluent interaction & assertion runner for single element targets
+ * - **`MultiElementRunner`**: Fluent assertion & traversal runner for multi-element collections
+ * - **Callable Matchers**: Ambient prototypes for WebdriverIO Element & Browser (`.shouldBeVisible()`, `.shouldHaveText()`, etc.)
+ *
+ * @example
+ * ```ts
+ * import { Spectra } from "@testspectra/matchers";
+ *
+ * await Spectra.get("#login-btn").click().should("not.be.visible");
+ * await Spectra.getAll(".list-item").should("have.length.greaterThan", 0);
+ * ```
+ */
 export * from "./types.js";
 export * from "./matchers.js";
 export * from "./runner/single.js";

package/dist/matchers.d.ts

@@ -2,13 +2,24 @@ import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./type
 /**
  * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
  * to an actionable WebdriverIO.Element.
+ *
+ * @param target - Selector string or element instance.
+ * @returns Resolved WebdriverIO.Element instance.
  */
 export declare function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element>;
 /**
  * Executes a single element matcher against the WebdriverIO browser / element context.
+ *
+ * @param target - Optional element target (not required for browser-level assertions).
+ * @param matcher - Single element matcher string.
+ * @param args - Arguments passed to the matcher.
  */
 export declare function executeSingleMatcher(target: ElementTarget | undefined, matcher: SingleElementMatcher, args: any[]): Promise<void>;
 /**
  * Executes a multi-element collection matcher against WebdriverIO $$.
+ *
+ * @param selector - CSS/XPath selector for the collection.
+ * @param matcher - Multi-element matcher string.
+ * @param args - Expected values or count limits.
  */
 export declare function executeMultiMatcher(selector: string, matcher: MultiElementMatcher, args: any[]): Promise<void>;

package/dist/matchers.js

@@ -1,6 +1,9 @@
 /**
  * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
  * to an actionable WebdriverIO.Element.
+ *
+ * @param target - Selector string or element instance.
+ * @returns Resolved WebdriverIO.Element instance.
  */
 export async function resolveElement(target) {
     if (typeof target === "string") {
@@ -12,6 +15,10 @@ export async function resolveElement(target) {
 }
 /**
  * Executes a single element matcher against the WebdriverIO browser / element context.
+ *
+ * @param target - Optional element target (not required for browser-level assertions).
+ * @param matcher - Single element matcher string.
+ * @param args - Arguments passed to the matcher.
  */
 export async function executeSingleMatcher(target, matcher, args) {
     const isBrowserLevel = matcher === "have.url" ||
@@ -92,6 +99,10 @@ export async function executeSingleMatcher(target, matcher, args) {
 }
 /**
  * Executes a multi-element collection matcher against WebdriverIO $$.
+ *
+ * @param selector - CSS/XPath selector for the collection.
+ * @param matcher - Multi-element matcher string.
+ * @param args - Expected values or count limits.
  */
 export async function executeMultiMatcher(selector, matcher, args) {
     const elements = await $$(selector);

package/dist/proto.d.ts

@@ -1,42 +1,284 @@
 declare global {
     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>;
         }
+        /**
+         * 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>;
     }
 }

package/dist/runner/collection.d.ts

@@ -1,13 +1,89 @@
 import { MultiElementMatcher } 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,
+ * array index access (`.eq()`, `.first()`, `.last()`), and sequential iteration (`.each()`).
+ *
+ * @example
+ * ```ts
+ * // Assert collection size
+ * await Spectra.getAll(".cart-item").should("have.length", 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");
+ *
+ * // Iteration
+ * await Spectra.getAll(".nav-link").each(async (link, i) => {
+ *   await link.should("be.visible");
+ * });
+ * ```
+ */
 export declare class MultiElementRunner implements PromiseLike<void> {
     private _selector;
     private _assertions;
     constructor(selector: string);
+    /**
+     * 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.
+     */
     should(matcher: MultiElementMatcher, ...args: any[]): this;
+    /**
+     * Returns a `SingleElementRunner` targeting the element at the specified 0-based index.
+     *
+     * @param index - 0-based index of the element within the matched collection.
+     * @example
+     * ```ts
+     * await Spectra.getAll("li.menu-item").eq(1).click();
+     * ```
+     * @returns `SingleElementRunner` for the indexed element.
+     */
     eq(index: number): SingleElementRunner;
+    /**
+     * Returns a `SingleElementRunner` targeting the first element in the collection (`index = 0`).
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll(".result-item").first().click();
+     * ```
+     * @returns `SingleElementRunner` for the first element.
+     */
     first(): SingleElementRunner;
+    /**
+     * Returns a `SingleElementRunner` targeting the last element in the collection.
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
+     * ```
+     * @returns `SingleElementRunner` for the last element.
+     */
     last(): SingleElementRunner;
+    /**
+     * Iterates asynchronously through every matched element in the collection sequentially.
+     *
+     * @param callback - Async function called for each element with `(runner, index)`.
+     * @example
+     * ```ts
+     * await Spectra.getAll(".checkbox").each(async (item, index) => {
+     *   await item.should("be.visible");
+     * });
+     * ```
+     */
     each(callback: (el: SingleElementRunner, index: number) => Promise<void>): Promise<void>;
+    /**
+     * Standard Promise `then` implementation.
+     * Executes all queued collection assertions sequentially when awaited.
+     */
     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

@@ -1,5 +1,26 @@
 import { executeMultiMatcher } from "../matchers.js";
 import { SingleElementRunner } from "./single.js";
+/**
+ * Fluent assertion, filtering, and iteration runner for multi-element collections.
+ *
+ * Implements `PromiseLike<void>`, 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);
+ *
+ * // Target specific element from collection
+ * await Spectra.getAll(".todo-item").first().click();
+ * await Spectra.getAll(".todo-item").eq(2).should("have.text", "Buy Milk");
+ *
+ * // Iteration
+ * await Spectra.getAll(".nav-link").each(async (link, i) => {
+ *   await link.should("be.visible");
+ * });
+ * ```
+ */
 export class MultiElementRunner {
     _selector;
     _assertions = [];
@@ -7,23 +28,74 @@ export class MultiElementRunner {
         this._selector = selector;
     }
     // --- Collection Assertions ---
+    /**
+     * 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.
+     */
     should(matcher, ...args) {
         this._assertions.push({ matcher, args });
         return this;
     }
     // --- Item Navigation ---
+    /**
+     * Returns a `SingleElementRunner` targeting the element at the specified 0-based index.
+     *
+     * @param index - 0-based index of the element within the matched collection.
+     * @example
+     * ```ts
+     * await Spectra.getAll("li.menu-item").eq(1).click();
+     * ```
+     * @returns `SingleElementRunner` for the indexed element.
+     */
     eq(index) {
         const indexedSelector = `(${this._selector})[${index + 1}]`;
         return new SingleElementRunner(indexedSelector);
     }
+    /**
+     * Returns a `SingleElementRunner` targeting the first element in the collection (`index = 0`).
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll(".result-item").first().click();
+     * ```
+     * @returns `SingleElementRunner` for the first element.
+     */
     first() {
         return this.eq(0);
     }
+    /**
+     * Returns a `SingleElementRunner` targeting the last element in the collection.
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
+     * ```
+     * @returns `SingleElementRunner` for the last element.
+     */
     last() {
         const indexedSelector = `(${this._selector})[last()]`;
         return new SingleElementRunner(indexedSelector);
     }
     // --- Iteration Callback ---
+    /**
+     * Iterates asynchronously through every matched element in the collection sequentially.
+     *
+     * @param callback - Async function called for each element with `(runner, index)`.
+     * @example
+     * ```ts
+     * await Spectra.getAll(".checkbox").each(async (item, index) => {
+     *   await item.should("be.visible");
+     * });
+     * ```
+     */
     async each(callback) {
         const elements = await $$(this._selector);
         const count = await elements.length;
@@ -33,6 +105,10 @@ export class MultiElementRunner {
         }
     }
     // --- Execution when awaited ---
+    /**
+     * Standard Promise `then` implementation.
+     * Executes all queued collection assertions sequentially when awaited.
+     */
     async then(onfulfilled, onrejected) {
         try {
             for (const assert of this._assertions) {