@testspectra/matchers 1.1.14 → 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.
@@ -101,6 +101,7 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
     select(selector: string | ScopedSelector, option: string, index?: number | null): Promise<void>;
     hover(selector: string | ScopedSelector, index?: number | null): Promise<void>;
     focus(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    blur(selector: string | ScopedSelector, index?: number | null): Promise<void>;
     dragDrop(sourceSelector: string | ScopedSelector, targetSelector: string, sourceIndex?: number | null): Promise<void>;
     longPress(selector: string | ScopedSelector, duration: number, index?: number | null): Promise<void>;
     scrollIntoView(selector: string | ScopedSelector, index?: number | null): Promise<void>;
@@ -119,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' | '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.
@@ -741,6 +761,15 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
      * ```
      */
     focus(): Promise<void>;
+    /**
+     * Removes focus from the target element (blurs it).
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#email-input').blur();
+     * ```
+     */
+    blur(): Promise<void>;
     /**
      * Moves the mouse cursor to the element (alias to `hover()`).
      */
@@ -786,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.
      *
@@ -991,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.
      *
@@ -1153,6 +1245,53 @@ export interface CDPNetworkEntry {
     /** Start timestamp epoch. */
     startTime: number;
 }
+/**
+ * A user- or library-registered command callable on the global `Spectra` object.
+ *
+ * Commands are registered at runtime via `Spectra.registerCommand()` (typically from a plugin's
+ * `setup()`), and their types are exposed to consumers through TypeScript module augmentation of
+ * `SpectraStatic` — there is no type-generator integration for external plugins.
+ */
+export type SpectraCommand = (...args: any[]) => any;
+/**
+ * Context passed to a plugin's `setup()`. Plugins use `platform` to register only the commands
+ * that are valid for the active target.
+ */
+export interface SpectraPluginContext {
+    /** Active execution platform: `'web'`, `'android'`, or `'ios'`. */
+    platform: string;
+}
+/**
+ * A TestSpectra plugin. A plugin is any external library that extends the `Spectra` DSL — its
+ * `setup` receives the live `Spectra` object and registers commands (or performs other one-time
+ * wiring) before test files are imported.
+ *
+ * Plugins are declared in `spectra.config.ts` under `executionConfig.plugins` as module specifiers
+ * and loaded by both the native E2E worker and the component-testing runtime. Platform-specific
+ * command **types** are shipped as per-stem subpath entries (`./web`, `./android`, `./ios`,
+ * `./mobile`, `./common`) and wired into the generated ambient declarations by the type generator.
+ *
+ * @example
+ * ```ts
+ * import type { SpectraPlugin } from '@testspectra/matchers';
+ *
+ * const plugin: SpectraPlugin = {
+ *   name: 'my-plugin',
+ *   setup(spectra, { platform }) {
+ *     spectra.registerCommand('findButton', (selector: string) => spectra.get(selector));
+ *     if (platform === 'web') spectra.registerCommand('findByCss', (s: string) => spectra.get(s));
+ *   },
+ * };
+ *
+ * export default plugin;
+ * ```
+ */
+export interface SpectraPlugin {
+    /** Unique plugin identifier, used for diagnostics. */
+    name: string;
+    /** One-time wiring executed after `Spectra` is built and before test files are imported. */
+    setup(spectra: SpectraStatic, context: SpectraPluginContext): void | Promise<void>;
+}
 /**
  * Main TestSpectra cross-platform automation and assertion interface contract.
  */
@@ -1316,6 +1455,16 @@ export interface SpectraStatic {
      * ```
      */
     focus(target: ElementTarget): Promise<void>;
+    /**
+     * Removes focus from the target element (blurs it).
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.blur('#email-input');
+     * ```
+     */
+    blur(target: ElementTarget): Promise<void>;
     /**
      * Drags a source element and drops it onto a destination element target.
      *
@@ -1459,4 +1608,32 @@ export interface SpectraStatic {
      * ```
      */
     clearMocks(): void;
+    /**
+     * Registers a custom command on the `Spectra` object, making it callable as
+     * `Spectra.<name>(...)`. Intended for plugins to extend the DSL.
+     *
+     * Throws if `name` is not a valid identifier, collides with a built-in `Spectra` method, or is
+     * already registered — built-ins can never be monkey-patched.
+     *
+     * @param name Command name (must be a valid JavaScript identifier).
+     * @param command Implementation to attach.
+     * @example
+     * ```ts
+     * Spectra.registerCommand('findButton', (selector: string) => Spectra.get(selector));
+     * ```
+     */
+    registerCommand(name: string, command: SpectraCommand): void;
+    /**
+     * Registers multiple custom commands at once. Each entry is validated exactly like
+     * `registerCommand`.
+     *
+     * @example
+     * ```ts
+     * Spectra.registerCommands({
+     *   findButton: (selector: string) => Spectra.get(selector),
+     *   findInput: (selector: string) => Spectra.get(selector),
+     * });
+     * ```
+     */
+    registerCommands(commands: Record<string, SpectraCommand>): void;
 }

package/dist/worker_config.d.ts

@@ -94,4 +94,9 @@ export interface TestSpectraWorkerConfig {
     }[];
     /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
     environmentVariables?: Record<string, string>;
+    /**
+     * Mirrors `spectra.config.ts`'s `executionConfig.plugins` — module specifiers (absolute paths,
+     * after CLI resolution) of TestSpectra plugins to install before test files are imported.
+     */
+    plugins?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.1.14",
+  "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,
@@ -151,6 +152,7 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
   select(selector: string | ScopedSelector, option: string, index?: number | null): Promise<void>;
   hover(selector: string | ScopedSelector, index?: number | null): Promise<void>;
   focus(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  blur(selector: string | ScopedSelector, index?: number | null): Promise<void>;
   dragDrop(sourceSelector: string | ScopedSelector, targetSelector: string, sourceIndex?: number | null): Promise<void>;
   longPress(selector: string | ScopedSelector, duration: number, index?: number | null): Promise<void>;
   scrollIntoView(selector: string | ScopedSelector, index?: number | null): Promise<void>;
@@ -170,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,10 +12,15 @@ export type ActionKey =
   | 'swipe'
   | 'wait'
   | 'waitForElement'
+  | 'waitForElementRemoved'
+  | 'waitForUndisplayed'
+  | 'waitForClickable'
   | 'pressKey'
   | 'longPress'
   | 'doubleClick'
   | 'hover'
+  | 'focus'
+  | 'blur'
   | 'dragDrop'
   | 'upload'
   | 'back'
@@ -145,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).
  *
@@ -185,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;
 }
 
 /**
@@ -918,6 +944,16 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
    */
   focus(): Promise<void>;
 
+  /**
+   * Removes focus from the target element (blurs it).
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#email-input').blur();
+   * ```
+   */
+  blur(): Promise<void>;
+
   /**
    * Moves the mouse cursor to the element (alias to `hover()`).
    */
@@ -967,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.
    *
@@ -1192,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.
    *
@@ -1352,6 +1454,56 @@ export interface CDPNetworkEntry {
   startTime: number;
 }
 
+/**
+ * A user- or library-registered command callable on the global `Spectra` object.
+ *
+ * Commands are registered at runtime via `Spectra.registerCommand()` (typically from a plugin's
+ * `setup()`), and their types are exposed to consumers through TypeScript module augmentation of
+ * `SpectraStatic` — there is no type-generator integration for external plugins.
+ */
+export type SpectraCommand = (...args: any[]) => any;
+
+/**
+ * Context passed to a plugin's `setup()`. Plugins use `platform` to register only the commands
+ * that are valid for the active target.
+ */
+export interface SpectraPluginContext {
+  /** Active execution platform: `'web'`, `'android'`, or `'ios'`. */
+  platform: string;
+}
+
+/**
+ * A TestSpectra plugin. A plugin is any external library that extends the `Spectra` DSL — its
+ * `setup` receives the live `Spectra` object and registers commands (or performs other one-time
+ * wiring) before test files are imported.
+ *
+ * Plugins are declared in `spectra.config.ts` under `executionConfig.plugins` as module specifiers
+ * and loaded by both the native E2E worker and the component-testing runtime. Platform-specific
+ * command **types** are shipped as per-stem subpath entries (`./web`, `./android`, `./ios`,
+ * `./mobile`, `./common`) and wired into the generated ambient declarations by the type generator.
+ *
+ * @example
+ * ```ts
+ * import type { SpectraPlugin } from '@testspectra/matchers';
+ *
+ * const plugin: SpectraPlugin = {
+ *   name: 'my-plugin',
+ *   setup(spectra, { platform }) {
+ *     spectra.registerCommand('findButton', (selector: string) => spectra.get(selector));
+ *     if (platform === 'web') spectra.registerCommand('findByCss', (s: string) => spectra.get(s));
+ *   },
+ * };
+ *
+ * export default plugin;
+ * ```
+ */
+export interface SpectraPlugin {
+  /** Unique plugin identifier, used for diagnostics. */
+  name: string;
+  /** One-time wiring executed after `Spectra` is built and before test files are imported. */
+  setup(spectra: SpectraStatic, context: SpectraPluginContext): void | Promise<void>;
+}
+
 /**
  * Main TestSpectra cross-platform automation and assertion interface contract.
  */
@@ -1530,6 +1682,17 @@ export interface SpectraStatic {
    */
   focus(target: ElementTarget): Promise<void>;
 
+  /**
+   * Removes focus from the target element (blurs it).
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.blur('#email-input');
+   * ```
+   */
+  blur(target: ElementTarget): Promise<void>;
+
   /**
    * Drags a source element and drops it onto a destination element target.
    *
@@ -1682,4 +1845,34 @@ export interface SpectraStatic {
    * ```
    */
   clearMocks(): void;
+
+  /**
+   * Registers a custom command on the `Spectra` object, making it callable as
+   * `Spectra.<name>(...)`. Intended for plugins to extend the DSL.
+   *
+   * Throws if `name` is not a valid identifier, collides with a built-in `Spectra` method, or is
+   * already registered — built-ins can never be monkey-patched.
+   *
+   * @param name Command name (must be a valid JavaScript identifier).
+   * @param command Implementation to attach.
+   * @example
+   * ```ts
+   * Spectra.registerCommand('findButton', (selector: string) => Spectra.get(selector));
+   * ```
+   */
+  registerCommand(name: string, command: SpectraCommand): void;
+
+  /**
+   * Registers multiple custom commands at once. Each entry is validated exactly like
+   * `registerCommand`.
+   *
+   * @example
+   * ```ts
+   * Spectra.registerCommands({
+   *   findButton: (selector: string) => Spectra.get(selector),
+   *   findInput: (selector: string) => Spectra.get(selector),
+   * });
+   * ```
+   */
+  registerCommands(commands: Record<string, SpectraCommand>): void;
 }

package/src/worker_config.ts

@@ -99,4 +99,9 @@ export interface TestSpectraWorkerConfig {
   monitoredDomains?: { domain: string; enabled: boolean }[];
   /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
   environmentVariables?: Record<string, string>;
+  /**
+   * Mirrors `spectra.config.ts`'s `executionConfig.plugins` — module specifiers (absolute paths,
+   * after CLI resolution) of TestSpectra plugins to install before test files are imported.
+   */
+  plugins?: string[];
 }