@testspectra/matchers 1.0.41 → 1.0.43

package/src/proto.ts

@@ -4,48 +4,323 @@ import { resolveElement } from "./matchers.js";
 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.
+     */
+    export 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.
+     */
+    export 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.
+     */
+    export 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.
  */

package/src/runner/collection.ts

@@ -2,11 +2,35 @@ import { MultiElementMatcher } from "../types.js";
 import { executeMultiMatcher } from "../matchers.js";
 import { SingleElementRunner } from "./single.js";
 
+/**
+ * Representation of a queued assertion against an element collection.
+ */
 type CollectionAssertion = {
   matcher: MultiElementMatcher;
   args: any[];
 };
 
+/**
+ * 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 implements PromiseLike<void> {
   private _selector: string;
   private _assertions: CollectionAssertion[] = [];
@@ -17,6 +41,18 @@ export class MultiElementRunner implements PromiseLike<void> {
 
   // --- 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: MultiElementMatcher, ...args: any[]): this {
     this._assertions.push({ matcher, args });
     return this;
@@ -24,15 +60,43 @@ export class MultiElementRunner implements PromiseLike<void> {
 
   // --- 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: number): SingleElementRunner {
     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(): SingleElementRunner {
     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(): SingleElementRunner {
     const indexedSelector = `(${this._selector})[last()]`;
     return new SingleElementRunner(indexedSelector);
@@ -40,6 +104,17 @@ export class MultiElementRunner implements PromiseLike<void> {
 
   // --- 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: (el: SingleElementRunner, index: number) => Promise<void>
   ): Promise<void> {
@@ -53,6 +128,10 @@ export class MultiElementRunner implements PromiseLike<void> {
 
   // --- Execution when awaited ---
 
+  /**
+   * Standard Promise `then` implementation.
+   * Executes all queued collection assertions sequentially when awaited.
+   */
   async then<TResult1 = void, TResult2 = never>(
     onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
@@ -71,3 +150,4 @@ export class MultiElementRunner implements PromiseLike<void> {
     }
   }
 }
+

package/src/runner/single.ts

@@ -1,12 +1,35 @@
-import { SingleElementMatcher, ElementTarget } from "../types.js";
+import { SingleElementMatcher, ElementTarget, TypeOptions } from "../types.js";
 import { executeSingleMatcher, resolveElement } from "../matchers.js";
 
+/**
+ * Representation of a queued assertion against an element or page.
+ */
 type AssertionItem = {
   target?: ElementTarget;
   matcher: SingleElementMatcher;
   args: any[];
 };
 
+/**
+ * Fluent interaction and assertion runner for a single element or browser context.
+ *
+ * Implements `PromiseLike<void>`, allowing it to be awaited directly or chained with
+ * multiple actions and `.should(...)` assertions.
+ *
+ * @example
+ * ```ts
+ * // Direct action + chained assertion
+ * await Spectra.get("#submit-btn")
+ *   .click()
+ *   .should("not.be.visible");
+ *
+ * // Query + multiple assertions
+ * await Spectra.get(LoginPage.usernameInput)
+ *   .should("be.visible")
+ *   .should("be.enabled")
+ *   .should("have.value", "admin");
+ * ```
+ */
 export class SingleElementRunner implements PromiseLike<void> {
   private _target: ElementTarget | undefined;
   private _action: (() => Promise<any>) | null = null;
@@ -19,6 +42,15 @@ export class SingleElementRunner implements PromiseLike<void> {
 
   // --- Chained Actions on current target ---
 
+  /**
+   * Clicks on the target element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get("#login-btn").click();
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   click(): this {
     const target = this.requireTarget("click");
     this._action = async () => {
@@ -28,6 +60,15 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
+  /**
+   * Double-clicks on the target element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get(".file-row").doubleClick();
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   doubleClick(): this {
     const target = this.requireTarget("doubleClick");
     this._action = async () => {
@@ -37,6 +78,16 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
+  /**
+   * Performs a long-press touch or hold gesture on the target element.
+   *
+   * @param durationMs - Duration in milliseconds to hold (default: 1000).
+   * @example
+   * ```ts
+   * await Spectra.get("#context-menu-trigger").longPress(1500);
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   longPress(durationMs = 1000): this {
     const target = this.requireTarget("longPress");
     this._action = async () => {
@@ -53,7 +104,18 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
-  type(value: string, options?: { clearFirst?: boolean }): this {
+  /**
+   * Types string value into the target input element.
+   *
+   * @param value - Text string to type into the element.
+   * @param options - Optional typing options (e.g. `clearFirst: true`).
+   * @example
+   * ```ts
+   * await Spectra.get("#search-input").type("iPhone 15", { clearFirst: true });
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
+  type(value: string, options?: TypeOptions): this {
     const target = this.requireTarget("type");
     this._action = async () => {
       const el = await resolveElement(target);
@@ -65,6 +127,15 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
+  /**
+   * Clears the current value of the target input element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get("#search-input").clear();
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   clear(): this {
     const target = this.requireTarget("clear");
     this._action = async () => {
@@ -74,6 +145,16 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
+  /**
+   * Selects an option from a `<select>` dropdown by its visible text.
+   *
+   * @param value - Visible text of the option to select.
+   * @example
+   * ```ts
+   * await Spectra.get("#country-select").select("United States");
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   select(value: string): this {
     const target = this.requireTarget("select");
     this._action = async () => {
@@ -83,6 +164,15 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
+  /**
+   * Moves the mouse cursor over the target element (hover).
+   *
+   * @example
+   * ```ts
+   * await Spectra.get("#dropdown-menu-trigger").hover();
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   hover(): this {
     const target = this.requireTarget("hover");
     this._action = async () => {
@@ -92,6 +182,16 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this;
   }
 
+  /**
+   * Waits for the target element to become displayed in the DOM.
+   *
+   * @param timeoutMs - Maximum duration in milliseconds to wait (default: 10000).
+   * @example
+   * ```ts
+   * await Spectra.get("#modal-dialog").waitForElement(5000);
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   waitForElement(timeoutMs = 10000): this {
     const target = this.requireTarget("waitForElement");
     this._action = async () => {
@@ -103,8 +203,35 @@ export class SingleElementRunner implements PromiseLike<void> {
 
   // --- Fluent Assertion Matchers ---
 
+  /**
+   * Queues an assertion matcher against the current target element or page.
+   *
+   * @param matcher - Single element matcher string (e.g. `'be.visible'`, `'have.text'`).
+   * @param args - Additional parameters for the matcher (e.g. expected text or value).
+   * @example
+   * ```ts
+   * await Spectra.get("#status-badge").should("be.visible");
+   * await Spectra.get("#username").should("have.value", "alice");
+   * await Spectra.get("#banner").should("have.class", "alert-success");
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   should(matcher: SingleElementMatcher, ...args: any[]): this;
+
+  /**
+   * Queues an assertion matcher targeting a specific element.
+   *
+   * @param target - Custom element target for this specific assertion.
+   * @param matcher - Single element matcher string.
+   * @param args - Additional parameters for the matcher.
+   * @example
+   * ```ts
+   * await Spectra.should(LoginPage.submitBtn, "be.enabled");
+   * ```
+   * @returns Current runner instance for method chaining.
+   */
   should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
+
   should(a: ElementTarget | SingleElementMatcher, b?: any, ...rest: any[]): this {
     const isFirstArgMatcher =
       typeof a === "string" &&
@@ -136,6 +263,10 @@ export class SingleElementRunner implements PromiseLike<void> {
 
   // --- Execution when awaited ---
 
+  /**
+   * Standard Promise `then` implementation.
+   * Executes queued action first (if any), followed sequentially by all queued assertions.
+   */
   async then<TResult1 = void, TResult2 = never>(
     onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
@@ -157,6 +288,9 @@ export class SingleElementRunner implements PromiseLike<void> {
     }
   }
 
+  /**
+   * Helper that throws an error if an action is called without a defined target.
+   */
   private requireTarget(actionName: string): ElementTarget {
     if (!this._target) {
       throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);
@@ -164,3 +298,4 @@ export class SingleElementRunner implements PromiseLike<void> {
     return this._target;
   }
 }
+