@testspectra/matchers 1.2.0 → 1.2.1

package/dist/contract.d.ts

@@ -8,7 +8,7 @@
  * DSL layer contains zero platform branching.
  */
 import type { TestSpectraWorkerConfig } from './worker_config.js';
-import type { CDPNetworkEntry, MockInterceptHandle, MockRule, ScopedSelector, ScrollOptions, SpectraBrowserBridge, SwipeOptions } from './types.js';
+import type { CDPNetworkEntry, ElementBounds, MockInterceptHandle, MockRule, ScopedSelector, ScrollOptions, SpectraBrowserBridge, SwipeOptions } from './types.js';
 /**
  * @deprecated Renamed to `TestSpectraWorkerConfig` (now shared by E2E and component testing).
  * Kept as an alias for backwards compatibility.
@@ -120,6 +120,16 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
         value: string;
     }>;
     count(selector: string | ScopedSelector): Promise<number>;
+    waitForElementRemoved(selector: string | ScopedSelector, timeoutMs?: number, index?: number | null): Promise<void>;
+    waitForUndisplayed(selector: string | ScopedSelector, opts?: {
+        timeout?: number;
+    }, index?: number | null): Promise<void>;
+    waitForClickable(selector: string | ScopedSelector, opts?: {
+        timeout?: number;
+    }, index?: number | null): Promise<boolean>;
+    getBounds(selector: string | ScopedSelector, index?: number | null): Promise<ElementBounds>;
+    closest(selector: string | ScopedSelector, targetSelector: string, index?: number | null): Promise<string | null>;
+    clickAt(x: number, y: number): Promise<void>;
     pressKey(key: string | number): Promise<void>;
     scroll(options?: ScrollOptions): Promise<void>;
     swipe(options: SwipeOptions): Promise<void>;

package/dist/types.d.ts

@@ -2,7 +2,7 @@
  * 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' | 'focus' | 'blur' | 'dragDrop' | 'upload' | 'back' | 'refresh';
+export type ActionKey = 'navigate' | 'click' | 'type' | 'clear' | 'select' | 'scroll' | 'swipe' | 'wait' | 'waitForElement' | 'waitForElementRemoved' | 'waitForUndisplayed' | 'waitForClickable' | 'pressKey' | 'longPress' | 'doubleClick' | 'hover' | 'focus' | 'blur' | 'dragDrop' | 'upload' | 'back' | 'refresh';
 /**
  * Canonical assertion keys supported across TestSpectra runner and database models.
  * @see backend/src/models/test_step.rs
@@ -73,6 +73,22 @@ export interface ScrollOptions {
     /** Optional target element selector to scroll directly into view */
     selector?: ElementTarget;
 }
+/**
+ * Bounding rectangle of an element — mirrors `Element.getBoundingClientRect()` on web
+ * and the `bounds: [left, top, right, bottom]` field of an Android accessibility node.
+ */
+export interface ElementBounds {
+    /** Horizontal position relative to viewport (alias of `left`). */
+    x: number;
+    /** Vertical position relative to viewport (alias of `top`). */
+    y: number;
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    width: number;
+    height: number;
+}
 /**
  * Configuration options for touch swipe gestures (mobile & web).
  *
@@ -111,6 +127,10 @@ export interface ClickOptions {
     text?: string;
     /** Click type: standard single click or double click */
     clickType?: 'single' | 'double';
+    /** X coordinate for a coordinate-based click (relative to the element). */
+    x?: number;
+    /** Y coordinate for a coordinate-based click (relative to the element). */
+    y?: number;
 }
 /**
  * Configuration options for typing input into form elements.
@@ -795,6 +815,58 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
     waitForDisplayed(opts?: {
         timeout?: number;
     }): Promise<boolean>;
+    /**
+     * Waits for the element to be removed from the DOM within the specified timeout.
+     * Opposite of `waitForElement()` — poll until the element no longer exists.
+     *
+     * @param timeoutMs Timeout in milliseconds (default: 5000ms).
+     */
+    waitForElementRemoved(timeoutMs?: number): Promise<void>;
+    /**
+     * Waits for the element to be hidden, detached, or not displayed within the specified timeout.
+     * Opposite of `waitForDisplayed()` — poll until the element is no longer visible.
+     *
+     * @param opts Optional timeout configuration object.
+     */
+    waitForUndisplayed(opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Waits until the element is enabled, visible, and clickable within the specified timeout.
+     *
+     * @param opts Optional timeout configuration object.
+     * @returns Promise resolving to true if the element became clickable, false on timeout.
+     */
+    waitForClickable(opts?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * Returns the element's bounding rectangle (position + size relative to viewport).
+     *
+     * @example
+     * ```ts
+     * const bounds = await Spectra.get('#modal').getBounds();
+     * console.log(bounds.x, bounds.y, bounds.width, bounds.height);
+     * ```
+     */
+    getBounds(): Promise<ElementBounds>;
+    /**
+     * Returns the parent element of this element in the DOM tree.
+     *
+     * @example
+     * ```ts
+     * const parent = await Spectra.get('#child').parent();
+     * await parent.shouldBeVisible();
+     * ```
+     */
+    parent(): SingleElementProxy;
+    /**
+     * Finds the closest ancestor that matches the selector (mirrors `Element.closest()`).
+     *
+     * @param selector CSS selector to match against ancestors.
+     * @returns Promise resolving to the closest matching ancestor, or null if none found.
+     */
+    closest(selector: string): Promise<SingleElementProxy | null>;
     /**
      * Returns the inner text content of the element.
      *
@@ -1000,6 +1072,17 @@ export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
         timeout?: number;
         timeoutMsg?: string;
     }): Promise<boolean>;
+    /**
+     * Clicks at absolute viewport coordinates (x, y).
+     *
+     * @param x Horizontal viewport coordinate.
+     * @param y Vertical viewport coordinate.
+     * @example
+     * ```ts
+     * await Spectra.browser.clickAt(100, 200);
+     * ```
+     */
+    clickAt(x: number, y: number): Promise<void>;
     /**
      * Retrieves captured browser console log entries.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Canonical TypeScript contracts and ambient type definitions for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/contract.ts

@@ -11,6 +11,7 @@
 import type { TestSpectraWorkerConfig } from './worker_config.js';
 import type {
   CDPNetworkEntry,
+  ElementBounds,
   MockInterceptHandle,
   MockRule,
   ScopedSelector,
@@ -171,6 +172,21 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
   getCSSProperty(selector: string | ScopedSelector, name: string, index?: number | null): Promise<{ value: string }>;
   count(selector: string | ScopedSelector): Promise<number>;
 
+  waitForElementRemoved(selector: string | ScopedSelector, timeoutMs?: number, index?: number | null): Promise<void>;
+  waitForUndisplayed(
+    selector: string | ScopedSelector,
+    opts?: { timeout?: number },
+    index?: number | null,
+  ): Promise<void>;
+  waitForClickable(
+    selector: string | ScopedSelector,
+    opts?: { timeout?: number },
+    index?: number | null,
+  ): Promise<boolean>;
+  getBounds(selector: string | ScopedSelector, index?: number | null): Promise<ElementBounds>;
+  closest(selector: string | ScopedSelector, targetSelector: string, index?: number | null): Promise<string | null>;
+  clickAt(x: number, y: number): Promise<void>;
+
   // --- Gestures & Keys ---
   pressKey(key: string | number): Promise<void>;
   scroll(options?: ScrollOptions): Promise<void>;

package/src/types.ts

@@ -12,6 +12,9 @@ export type ActionKey =
   | 'swipe'
   | 'wait'
   | 'waitForElement'
+  | 'waitForElementRemoved'
+  | 'waitForUndisplayed'
+  | 'waitForClickable'
   | 'pressKey'
   | 'longPress'
   | 'doubleClick'
@@ -147,6 +150,23 @@ export interface ScrollOptions {
   selector?: ElementTarget;
 }
 
+/**
+ * Bounding rectangle of an element — mirrors `Element.getBoundingClientRect()` on web
+ * and the `bounds: [left, top, right, bottom]` field of an Android accessibility node.
+ */
+export interface ElementBounds {
+  /** Horizontal position relative to viewport (alias of `left`). */
+  x: number;
+  /** Vertical position relative to viewport (alias of `top`). */
+  y: number;
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
 /**
  * Configuration options for touch swipe gestures (mobile & web).
  *
@@ -187,6 +207,10 @@ export interface ClickOptions {
   text?: string;
   /** Click type: standard single click or double click */
   clickType?: 'single' | 'double';
+  /** X coordinate for a coordinate-based click (relative to the element). */
+  x?: number;
+  /** Y coordinate for a coordinate-based click (relative to the element). */
+  y?: number;
 }
 
 /**
@@ -979,6 +1003,60 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
    */
   waitForDisplayed(opts?: { timeout?: number }): Promise<boolean>;
 
+  /**
+   * Waits for the element to be removed from the DOM within the specified timeout.
+   * Opposite of `waitForElement()` — poll until the element no longer exists.
+   *
+   * @param timeoutMs Timeout in milliseconds (default: 5000ms).
+   */
+  waitForElementRemoved(timeoutMs?: number): Promise<void>;
+
+  /**
+   * Waits for the element to be hidden, detached, or not displayed within the specified timeout.
+   * Opposite of `waitForDisplayed()` — poll until the element is no longer visible.
+   *
+   * @param opts Optional timeout configuration object.
+   */
+  waitForUndisplayed(opts?: { timeout?: number }): Promise<void>;
+
+  /**
+   * Waits until the element is enabled, visible, and clickable within the specified timeout.
+   *
+   * @param opts Optional timeout configuration object.
+   * @returns Promise resolving to true if the element became clickable, false on timeout.
+   */
+  waitForClickable(opts?: { timeout?: number }): Promise<boolean>;
+
+  /**
+   * Returns the element's bounding rectangle (position + size relative to viewport).
+   *
+   * @example
+   * ```ts
+   * const bounds = await Spectra.get('#modal').getBounds();
+   * console.log(bounds.x, bounds.y, bounds.width, bounds.height);
+   * ```
+   */
+  getBounds(): Promise<ElementBounds>;
+
+  /**
+   * Returns the parent element of this element in the DOM tree.
+   *
+   * @example
+   * ```ts
+   * const parent = await Spectra.get('#child').parent();
+   * await parent.shouldBeVisible();
+   * ```
+   */
+  parent(): SingleElementProxy;
+
+  /**
+   * Finds the closest ancestor that matches the selector (mirrors `Element.closest()`).
+   *
+   * @param selector CSS selector to match against ancestors.
+   * @returns Promise resolving to the closest matching ancestor, or null if none found.
+   */
+  closest(selector: string): Promise<SingleElementProxy | null>;
+
   /**
    * Returns the inner text content of the element.
    *
@@ -1204,6 +1282,18 @@ export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
    */
   waitUntil(fn: () => Promise<boolean> | boolean, opts?: { timeout?: number; timeoutMsg?: string }): Promise<boolean>;
 
+  /**
+   * Clicks at absolute viewport coordinates (x, y).
+   *
+   * @param x Horizontal viewport coordinate.
+   * @param y Vertical viewport coordinate.
+   * @example
+   * ```ts
+   * await Spectra.browser.clickAt(100, 200);
+   * ```
+   */
+  clickAt(x: number, y: number): Promise<void>;
+
   /**
    * Retrieves captured browser console log entries.
    *