@testspectra/matchers 1.0.1 → 1.0.42

package/dist/runner/single.d.ts

@@ -1,21 +1,148 @@
-import { SingleElementMatcher, ElementTarget } from "../types.js";
+import { SingleElementMatcher, ElementTarget, TypeOptions } from "../types.js";
+/**
+ * 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 declare class SingleElementRunner implements PromiseLike<void> {
     private _target;
     private _action;
     private _assertions;
     constructor(target?: ElementTarget, action?: () => Promise<any>);
+    /**
+     * Clicks on the target element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get("#login-btn").click();
+     * ```
+     * @returns Current runner instance for method chaining.
+     */
     click(): this;
+    /**
+     * Double-clicks on the target element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get(".file-row").doubleClick();
+     * ```
+     * @returns Current runner instance for method chaining.
+     */
     doubleClick(): 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?: number): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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?: number): this;
+    /**
+     * 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;
+    /**
+     * Standard Promise `then` implementation.
+     * Executes queued action first (if any), followed sequentially by all queued assertions.
+     */
     then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Helper that throws an error if an action is called without a defined target.
+     */
     private requireTarget;
 }

package/dist/runner/single.js

@@ -1,4 +1,24 @@
 import { executeSingleMatcher, resolveElement } from "../matchers.js";
+/**
+ * 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 {
     _target;
     _action = null;
@@ -8,6 +28,15 @@ export class SingleElementRunner {
         this._action = action || null;
     }
     // --- 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() {
         const target = this.requireTarget("click");
         this._action = async () => {
@@ -16,6 +45,15 @@ export class SingleElementRunner {
         };
         return this;
     }
+    /**
+     * Double-clicks on the target element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get(".file-row").doubleClick();
+     * ```
+     * @returns Current runner instance for method chaining.
+     */
     doubleClick() {
         const target = this.requireTarget("doubleClick");
         this._action = async () => {
@@ -24,6 +62,16 @@ export class SingleElementRunner {
         };
         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) {
         const target = this.requireTarget("longPress");
         this._action = async () => {
@@ -40,6 +88,17 @@ export class SingleElementRunner {
         };
         return 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, options) {
         const target = this.requireTarget("type");
         this._action = async () => {
@@ -51,6 +110,15 @@ export class SingleElementRunner {
         };
         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() {
         const target = this.requireTarget("clear");
         this._action = async () => {
@@ -59,6 +127,16 @@ export class SingleElementRunner {
         };
         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) {
         const target = this.requireTarget("select");
         this._action = async () => {
@@ -67,6 +145,15 @@ export class SingleElementRunner {
         };
         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() {
         const target = this.requireTarget("hover");
         this._action = async () => {
@@ -75,6 +162,16 @@ export class SingleElementRunner {
         };
         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) {
         const target = this.requireTarget("waitForElement");
         this._action = async () => {
@@ -111,6 +208,10 @@ export class SingleElementRunner {
         return this;
     }
     // --- Execution when awaited ---
+    /**
+     * Standard Promise `then` implementation.
+     * Executes queued action first (if any), followed sequentially by all queued assertions.
+     */
     async then(onfulfilled, onrejected) {
         try {
             if (this._action) {
@@ -129,6 +230,9 @@ export class SingleElementRunner {
             throw err;
         }
     }
+    /**
+     * Helper that throws an error if an action is called without a defined target.
+     */
     requireTarget(actionName) {
         if (!this._target) {
             throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);

package/dist/spectra.d.ts

@@ -2,33 +2,223 @@ import { ClickOptions, ElementTarget, KeyOption, LongPressOptions, ScrollOptions
 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).
+ * Main TestSpectra cross-platform automation and assertion orchestrator.
+ *
+ * Provides a unified, ergonomic testing API across Web, Android, and iOS.
+ * Features single element targeting (`.get`), collection targeting (`.getAll`),
+ * and built-in actions (`.click`, `.type`, `.scroll`, `.swipe`, `.navigate`).
+ *
+ * @example
+ * ```ts
+ * // Single element interaction
+ * await Spectra.get("#username").type("admin");
+ *
+ * // Collection assertion
+ * await Spectra.getAll(".item").should("have.length", 5);
+ *
+ * // Mobile touch swipe
+ * await Spectra.swipe({ direction: "left", distance: 350 });
+ * ```
  */
 export declare class SpectraStatic {
     /**
-     * Targets a single element by selector or Page Object element.
+     * Targets a single element by CSS/XPath selector or Page Object element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @example
+     * ```ts
+     * await Spectra.get("#login-btn").click();
+     * await Spectra.get(LoginPage.submitButton).should("be.visible");
+     * ```
+     * @returns `SingleElementRunner` for chaining actions and assertions.
      */
     get(target: ElementTarget): SingleElementRunner;
     /**
-     * Targets multiple elements / collections by selector.
+     * Targets multiple elements or collections matching a CSS/XPath selector.
+     *
+     * @param selector - Selector string matching multiple elements.
+     * @example
+     * ```ts
+     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
+     * await Spectra.getAll("li.tab").first().click();
+     * ```
+     * @returns `MultiElementRunner` for collection assertions and indexing.
      */
     getAll(selector: string): MultiElementRunner;
+    /**
+     * Navigates the browser to the specified URL.
+     *
+     * @param url - Relative URL or absolute URL.
+     * @example
+     * ```ts
+     * await Spectra.navigate("/login");
+     * await Spectra.navigate("https://app.testspectra.dev/dashboard");
+     * ```
+     */
     navigate(url: string): SingleElementRunner;
+    /**
+     * Navigates back one step in the browser / app history.
+     *
+     * @example
+     * ```ts
+     * await Spectra.back();
+     * ```
+     */
     back(): SingleElementRunner;
+    /**
+     * Refreshes the current browser page.
+     *
+     * @example
+     * ```ts
+     * await Spectra.refresh();
+     * ```
+     */
     refresh(): SingleElementRunner;
+    /**
+     * Clicks on the specified element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @param textOrOptions - Optional text filter or click configuration.
+     * @example
+     * ```ts
+     * await Spectra.click("#submit-button");
+     * await Spectra.click(LoginPage.loginBtn);
+     * ```
+     */
     click(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    /**
+     * Performs a double-click on the specified element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @param textOrOptions - Optional text filter or click configuration.
+     * @example
+     * ```ts
+     * await Spectra.doubleClick(".grid-row");
+     * ```
+     */
     doubleClick(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    /**
+     * Performs a long-press touch or hold gesture on the specified element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @param options - Optional duration in ms or LongPressOptions object.
+     * @example
+     * ```ts
+     * await Spectra.longPress("#message-item", 1500);
+     * await Spectra.longPress(ChatPage.audioRecordBtn, { duration: 2000 });
+     * ```
+     */
     longPress(target: ElementTarget, options?: LongPressOptions | number): SingleElementRunner;
+    /**
+     * Types text into the specified element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @param value - Text string to enter.
+     * @param options - Optional typing options (e.g. `clearFirst: true`).
+     * @example
+     * ```ts
+     * await Spectra.type("#email", "user@example.com", { clearFirst: true });
+     * await Spectra.type(LoginPage.passwordInput, "SecretPass123");
+     * ```
+     */
     type(target: ElementTarget, value: string, options?: TypeOptions): SingleElementRunner;
+    /**
+     * Clears the input content from the specified element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @example
+     * ```ts
+     * await Spectra.clear("#coupon-input");
+     * ```
+     */
     clear(target: ElementTarget): SingleElementRunner;
+    /**
+     * Selects an option from a `<select>` dropdown by its visible text.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @param value - Visible text of the option to select.
+     * @example
+     * ```ts
+     * await Spectra.select("#shipping-country", "Indonesia");
+     * ```
+     */
     select(target: ElementTarget, value: string): SingleElementRunner;
+    /**
+     * Hovers the mouse pointer over the specified element.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @example
+     * ```ts
+     * await Spectra.hover("#nav-profile-menu");
+     * ```
+     */
     hover(target: ElementTarget): SingleElementRunner;
+    /**
+     * Simulates pressing a specific keyboard key.
+     *
+     * @param key - Key name string (e.g. `'Enter'`, `'Tab'`, `'Escape'`).
+     * @example
+     * ```ts
+     * await Spectra.pressKey("Enter");
+     * await Spectra.pressKey("Escape");
+     * ```
+     */
     pressKey(key: KeyOption | string): SingleElementRunner;
+    /**
+     * Drags a source element and drops it onto a destination target.
+     *
+     * @param sourceTarget - Element to drag.
+     * @param destTarget - Destination element or drop zone.
+     * @example
+     * ```ts
+     * await Spectra.dragDrop("#task-item-1", "#column-done");
+     * ```
+     */
     dragDrop(sourceTarget: ElementTarget, destTarget: ElementTarget): SingleElementRunner;
+    /**
+     * Scrolls the page or scrolls a specific element into view.
+     *
+     * @param options - Direction, pixels, or selector to scroll.
+     * @example
+     * ```ts
+     * await Spectra.scroll({ direction: "down", pixels: 400 });
+     * await Spectra.scroll({ selector: "#footer" });
+     * ```
+     */
     scroll(options?: ScrollOptions): SingleElementRunner;
+    /**
+     * Performs a touch swipe gesture in the given direction (for mobile and touch-enabled browsers).
+     *
+     * @param options - Swipe configuration with `direction` and optional `distance`.
+     * @example
+     * ```ts
+     * await Spectra.swipe({ direction: "left", distance: 300 });
+     * ```
+     */
     swipe(options: SwipeOptions): SingleElementRunner;
+    /**
+     * Pauses test execution for a specified duration in milliseconds.
+     *
+     * @param durationMs - Time to wait in milliseconds.
+     * @example
+     * ```ts
+     * await Spectra.wait(1000);
+     * ```
+     */
     wait(durationMs: number): SingleElementRunner;
+    /**
+     * Waits until the specified element is displayed on the screen.
+     *
+     * @param target - Selector string or Page Object element property.
+     * @param timeoutMs - Maximum time in milliseconds to wait (default: 10000).
+     * @example
+     * ```ts
+     * await Spectra.waitForElement("#confirmation-dialog", 5000);
+     * ```
+     */
     waitForElement(target: ElementTarget, timeoutMs?: number): SingleElementRunner;
 }
+/**
+ * Global singleton instance of `SpectraStatic`.
+ */
 export declare const Spectra: SpectraStatic;