@testspectra/matchers 1.1.14 → 1.2.0

package/dist/contract.d.ts

@@ -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>;

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' | '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
@@ -741,6 +741,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()`).
      */
@@ -1153,6 +1162,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 +1372,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 +1525,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.0",
   "description": "Canonical TypeScript contracts and ambient type definitions for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/contract.ts

@@ -151,6 +151,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>;

package/src/types.ts

@@ -16,6 +16,8 @@ export type ActionKey =
   | 'longPress'
   | 'doubleClick'
   | 'hover'
+  | 'focus'
+  | 'blur'
   | 'dragDrop'
   | 'upload'
   | 'back'
@@ -918,6 +920,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()`).
    */
@@ -1352,6 +1364,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 +1592,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 +1755,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[];
 }