@testspectra/matchers 1.0.69 → 1.1.0

package/src/spectra.ts

@@ -1,376 +0,0 @@
-import {
-  ClickOptions,
-  ElementTarget,
-  KeyOption,
-  LongPressOptions,
-  ScrollOptions,
-  SwipeOptions,
-  TypeOptions,
-} from "./types.js";
-import { SingleElementRunner } from "./runner/single.js";
-import { MultiElementRunner } from "./runner/collection.js";
-import { resolveElement } from "./matchers.js";
-
-/**
- * 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 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 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);
-  }
-
-  // --- 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();
-    });
-  }
-
-  // --- 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);
-      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: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner {
-    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: ElementTarget, options?: LongPressOptions | number): SingleElementRunner {
-    const duration = typeof options === "number" ? options : options?.duration || 1000;
-    return new SingleElementRunner(target, async () => {
-      const el = await resolveElement(target);
-      if (typeof (el as any).touchAction === "function") {
-        await (el as any).touchAction([
-          { action: "longPress", ms: duration },
-          { action: "release" },
-        ]);
-      } else {
-        await el.click();
-      }
-    });
-  }
-
-  /**
-   * 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);
-      if (options?.clearFirst) {
-        await el.clearValue();
-      }
-      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: ElementTarget): SingleElementRunner {
-    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: ElementTarget, value: string): SingleElementRunner {
-    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: ElementTarget): SingleElementRunner {
-    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: 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);
-      const target = await resolveElement(destTarget);
-      await source.dragAndDrop(target);
-    });
-  }
-
-  // --- 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) {
-        const el = await resolveElement(options.selector);
-        await el.scrollIntoView();
-      } else {
-        await browser.execute((direction, pixels) => {
-          const delta = pixels || 500;
-          window.scrollBy({
-            top: direction === "up" ? -delta : direction === "down" ? delta : 0,
-            left: direction === "left" ? -delta : direction === "right" ? delta : 0,
-            behavior: "smooth",
-          });
-        }, options?.direction || "down", options?.pixels || 500);
-      }
-    });
-  }
-
-  /**
-   * 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") {
-        const distance = options.distance || 300;
-        await (browser as any).touchAction([
-          { action: "press", x: 200, y: 500 },
-          {
-            action: "moveTo",
-            x: options.direction === "right" ? 200 + distance : options.direction === "left" ? 200 - distance : 200,
-            y: options.direction === "down" ? 500 + distance : options.direction === "up" ? 500 - distance : 500,
-          },
-          { action: "release" },
-        ]);
-      } else {
-        // Fallback to web scroll
-        await this.scroll({ direction: options.direction, pixels: options.distance });
-      }
-    });
-  }
-
-  // --- 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);
-      await el.waitForDisplayed({ timeout: timeoutMs });
-    });
-  }
-}
-
-/**
- * Global singleton instance of `SpectraStatic`.
- */
-export const Spectra = new SpectraStatic();
-