@testspectra/matchers 1.0.41 → 1.0.43

package/src/spectra.ts

@@ -12,19 +12,50 @@ 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: ElementTarget): SingleElementRunner {
     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: string): MultiElementRunner {
     return new MultiElementRunner(selector);
@@ -32,18 +63,44 @@ export class SpectraStatic {
 
   // --- 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: string): SingleElementRunner {
     return new SingleElementRunner(undefined, async () => {
       await browser.url(url);
     });
   }
 
+  /**
+   * Navigates back one step in the browser / app history.
+   *
+   * @example
+   * ```ts
+   * await Spectra.back();
+   * ```
+   */
   back(): SingleElementRunner {
     return new SingleElementRunner(undefined, async () => {
       await browser.back();
     });
   }
 
+  /**
+   * Refreshes the current browser page.
+   *
+   * @example
+   * ```ts
+   * await Spectra.refresh();
+   * ```
+   */
   refresh(): SingleElementRunner {
     return new SingleElementRunner(undefined, async () => {
       await browser.refresh();
@@ -52,6 +109,17 @@ export class SpectraStatic {
 
   // --- 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: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -59,6 +127,16 @@ export class SpectraStatic {
     });
   }
 
+  /**
+   * 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 {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -66,6 +144,17 @@ export class SpectraStatic {
     });
   }
 
+  /**
+   * 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 {
     const duration = typeof options === "number" ? options : options?.duration || 1000;
     return new SingleElementRunner(target, async () => {
@@ -81,6 +170,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: ElementTarget, value: string, options?: TypeOptions): SingleElementRunner {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -91,6 +192,15 @@ export class SpectraStatic {
     });
   }
 
+  /**
+   * 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 {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -98,6 +208,16 @@ export class SpectraStatic {
     });
   }
 
+  /**
+   * 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 {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -105,6 +225,15 @@ export class SpectraStatic {
     });
   }
 
+  /**
+   * 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 {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -112,12 +241,32 @@ export class SpectraStatic {
     });
   }
 
+  /**
+   * 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 {
     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: ElementTarget, destTarget: ElementTarget): SingleElementRunner {
     return new SingleElementRunner(sourceTarget, async () => {
       const source = await resolveElement(sourceTarget);
@@ -128,6 +277,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?: ScrollOptions): SingleElementRunner {
     return new SingleElementRunner(options?.selector, async () => {
       if (options?.selector) {
@@ -146,6 +305,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: SwipeOptions): SingleElementRunner {
     return new SingleElementRunner(options.selector, async () => {
       if (typeof (browser as any).touchAction === "function") {
@@ -168,12 +336,31 @@ 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: number): SingleElementRunner {
     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: ElementTarget, timeoutMs = 10000): SingleElementRunner {
     return new SingleElementRunner(target, async () => {
       const el = await resolveElement(target);
@@ -182,4 +369,8 @@ export class SpectraStatic {
   }
 }
 
+/**
+ * Global singleton instance of `SpectraStatic`.
+ */
 export const Spectra = new SpectraStatic();
+

package/src/types.ts

@@ -1,8 +1,7 @@
 /**
- * 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"
@@ -21,6 +20,10 @@ export type ActionKey =
   | "back"
   | "refresh";
 
+/**
+ * Canonical assertion keys supported across TestSpectra runner and database models.
+ * @see backend/src/models/test_step.rs
+ */
 export type AssertionKey =
   | "elementDisplayed"
   | "elementNotDisplayed"
@@ -44,6 +47,15 @@ export type AssertionKey =
   | "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"
@@ -56,36 +68,111 @@ export type KeyOption =
   | "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"
@@ -106,8 +193,20 @@ export type SingleElementMatcher =
   | "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";
+