@testspectra/matchers 1.0.41 → 1.0.43

package/dist/spectra.js

@@ -2,51 +2,140 @@ import { SingleElementRunner } from "./runner/single.js";
 import { MultiElementRunner } from "./runner/collection.js";
 import { resolveElement } from "./matchers.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 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) {
         return new SingleElementRunner(target);
     }
     /**
-     * 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) {
         return new MultiElementRunner(selector);
     }
     // --- Browser & Navigation Actions ---
+    /**
+     * 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) {
         return new SingleElementRunner(undefined, async () => {
             await browser.url(url);
         });
     }
+    /**
+     * Navigates back one step in the browser / app history.
+     *
+     * @example
+     * ```ts
+     * await Spectra.back();
+     * ```
+     */
     back() {
         return new SingleElementRunner(undefined, async () => {
             await browser.back();
         });
     }
+    /**
+     * Refreshes the current browser page.
+     *
+     * @example
+     * ```ts
+     * await Spectra.refresh();
+     * ```
+     */
     refresh() {
         return new SingleElementRunner(undefined, async () => {
             await browser.refresh();
         });
     }
     // --- Direct Interaction Actions ---
+    /**
+     * 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, textOrOptions) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.click();
         });
     }
+    /**
+     * 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, textOrOptions) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.doubleClick();
         });
     }
+    /**
+     * 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, options) {
         const duration = typeof options === "number" ? options : options?.duration || 1000;
         return new SingleElementRunner(target, async () => {
@@ -62,6 +151,18 @@ export class SpectraStatic {
             }
         });
     }
+    /**
+     * 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, value, options) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
@@ -71,29 +172,77 @@ export class SpectraStatic {
             await el.setValue(value);
         });
     }
+    /**
+     * 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) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.clearValue();
         });
     }
+    /**
+     * 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, value) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.selectByVisibleText(value);
         });
     }
+    /**
+     * 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) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.moveTo();
         });
     }
+    /**
+     * 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) {
         return new SingleElementRunner(undefined, async () => {
             await browser.keys(key);
         });
     }
+    /**
+     * 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, destTarget) {
         return new SingleElementRunner(sourceTarget, async () => {
             const source = await resolveElement(sourceTarget);
@@ -102,6 +251,16 @@ export class SpectraStatic {
         });
     }
     // --- Gesture Actions ---
+    /**
+     * 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) {
         return new SingleElementRunner(options?.selector, async () => {
             if (options?.selector) {
@@ -120,6 +279,15 @@ export class SpectraStatic {
             }
         });
     }
+    /**
+     * 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) {
         return new SingleElementRunner(options.selector, async () => {
             if (typeof browser.touchAction === "function") {
@@ -141,11 +309,30 @@ export class SpectraStatic {
         });
     }
     // --- Timing Actions ---
+    /**
+     * Pauses test execution for a specified duration in milliseconds.
+     *
+     * @param durationMs - Time to wait in milliseconds.
+     * @example
+     * ```ts
+     * await Spectra.wait(1000);
+     * ```
+     */
     wait(durationMs) {
         return new SingleElementRunner(undefined, async () => {
             await browser.pause(durationMs);
         });
     }
+    /**
+     * 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, timeoutMs = 10000) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
@@ -153,4 +340,7 @@ export class SpectraStatic {
         });
     }
 }
+/**
+ * Global singleton instance of `SpectraStatic`.
+ */
 export const Spectra = new SpectraStatic();

package/dist/types.d.ts

@@ -1,32 +1,131 @@
 /**
- * Database Canonical Action and Assertion Types
- * Matches backend/src/models/test_step.rs
+ * Canonical action keys supported across TestSpectra runner and database models.
+ * @see backend/src/models/test_step.rs
  */
 export type ActionKey = "navigate" | "click" | "type" | "clear" | "select" | "scroll" | "swipe" | "wait" | "waitForElement" | "pressKey" | "longPress" | "doubleClick" | "hover" | "dragDrop" | "back" | "refresh";
+/**
+ * Canonical assertion keys supported across TestSpectra runner and database models.
+ * @see backend/src/models/test_step.rs
+ */
 export type AssertionKey = "elementDisplayed" | "elementNotDisplayed" | "elementExists" | "elementEnabled" | "elementDisabled" | "textContains" | "textEquals" | "textNotContains" | "urlContains" | "urlEquals" | "valueEquals" | "valueContains" | "attributeEquals" | "attributeContains" | "hasClass" | "hasAttribute" | "isSelected" | "elementCount" | "elementCountGreaterThan" | "pageLoaded" | "noErrors";
+/**
+ * Supported keyboard key names for `Spectra.pressKey(key)`.
+ *
+ * @example
+ * ```ts
+ * await Spectra.pressKey("Enter");
+ * await Spectra.pressKey("Tab");
+ * ```
+ */
 export type KeyOption = "Enter" | "Tab" | "Escape" | "Backspace" | "Delete" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Space";
+/**
+ * Cardinal directions for gestures such as swipe and scroll.
+ */
 export type Direction = "up" | "down" | "left" | "right";
+/**
+ * Target reference for locating an element.
+ * Can be a CSS/XPath selector string, a resolved `WebdriverIO.Element`,
+ * or a chainable element promise `ChainablePromiseElement`.
+ *
+ * @example
+ * ```ts
+ * // Selector string
+ * Spectra.get("#submit-btn");
+ *
+ * // Page Object property
+ * Spectra.get(LoginPage.submitButton);
+ * ```
+ */
 export type ElementTarget = string | WebdriverIO.Element | ChainablePromiseElement;
+/**
+ * Configuration options for scroll actions.
+ *
+ * @example
+ * ```ts
+ * await Spectra.scroll({ direction: "down", pixels: 300 });
+ * await Spectra.scroll({ selector: "#footer" });
+ * ```
+ */
 export interface ScrollOptions {
+    /** Direction to scroll (default: "down") */
     direction?: Direction;
+    /** Distance in pixels to scroll (default: 500) */
     pixels?: number;
+    /** Optional target element selector to scroll directly into view */
     selector?: ElementTarget;
 }
+/**
+ * Configuration options for touch swipe gestures (mobile & web).
+ *
+ * @example
+ * ```ts
+ * await Spectra.swipe({ direction: "left", distance: 400 });
+ * ```
+ */
 export interface SwipeOptions {
+    /** Direction of the swipe gesture */
     direction: Direction;
+    /** Distance in pixels to swipe (default: 300) */
     distance?: number;
+    /** Optional element target to anchor the swipe gesture */
     selector?: ElementTarget;
 }
+/**
+ * Configuration options for long-press gestures.
+ *
+ * @example
+ * ```ts
+ * await Spectra.longPress("#draggable-card", { duration: 1500 });
+ * ```
+ */
 export interface LongPressOptions {
+    /** Optional label or text associated with the element */
     text?: string;
+    /** Duration in milliseconds to hold the press (default: 1000) */
     duration?: number;
 }
+/**
+ * Configuration options for click interactions.
+ */
 export interface ClickOptions {
+    /** Optional inner text filter */
     text?: string;
+    /** Click type: standard single click or double click */
     clickType?: "single" | "double";
 }
+/**
+ * Configuration options for typing input into form elements.
+ *
+ * @example
+ * ```ts
+ * await Spectra.type("#username", "john_doe", { clearFirst: true });
+ * ```
+ */
 export interface TypeOptions {
+    /** Whether to clear existing input value before typing new text (default: false) */
     clearFirst?: boolean;
 }
+/**
+ * Fluent assertion matcher strings for single element verification.
+ * Used in `Spectra.get(target).should(matcher, ...args)`.
+ *
+ * @example
+ * ```ts
+ * await Spectra.get("#username").should("be.visible");
+ * await Spectra.get("#greeting").should("have.text", "Welcome back");
+ * await Spectra.get("#status").should("have.class", "active");
+ * ```
+ */
 export type SingleElementMatcher = "be.visible" | "not.be.visible" | "exist" | "not.exist" | "be.enabled" | "be.disabled" | "be.checked" | "be.selected" | "have.value" | "contain.value" | "have.text" | "contain.text" | "have.class" | "have.attr" | "have.url" | "contain.url" | "have.title" | "contain.title";
+/**
+ * Fluent assertion matcher strings for multi-element collections.
+ * Used in `Spectra.getAll(selector).should(matcher, ...args)`.
+ *
+ * @example
+ * ```ts
+ * await Spectra.getAll(".product-item").should("have.length", 4);
+ * await Spectra.getAll(".product-item").should("have.length.greaterThan", 0);
+ * await Spectra.getAll(".badge").should("not.be.empty");
+ * ```
+ */
 export type MultiElementMatcher = "have.length" | "have.length.greaterThan" | "be.empty" | "exist";

package/dist/types.js

@@ -1,5 +1 @@
-/**
- * Database Canonical Action and Assertion Types
- * Matches backend/src/models/test_step.rs
- */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "description": "Cross-platform action commands and direct callable assertion matchers for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -1,6 +1,28 @@
+/**
+ * @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";
 export * from "./runner/collection.js";
 export * from "./spectra.js";
 export * from "./proto.js";
+

package/src/matchers.ts

@@ -3,6 +3,9 @@ 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 async function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element> {
   if (typeof target === "string") {
@@ -15,6 +18,10 @@ export async function resolveElement(target: ElementTarget): Promise<WebdriverIO
 
 /**
  * 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: ElementTarget | undefined,
@@ -104,6 +111,10 @@ export async function executeSingleMatcher(
 
 /**
  * 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: string,