@testspectra/matchers 1.1.11-rc.5 → 1.1.13

package/dist/proto.d.ts

@@ -29,3 +29,4 @@ declare global {
         }
     }
 }
+export type SpectraEnv = globalThis.SpectraEnv;

package/dist/reporter.js

@@ -67,7 +67,19 @@ export function formatArgs(args) {
  */
 export async function trackCommand(category, commandText, fn) {
     const start = Date.now();
-    const payload = typeof commandText === 'object' ? JSON.stringify(commandText) : commandText;
+    const payloadObj = typeof commandText === 'object' ? { ...commandText } : { text: commandText };
+    if (typeof globalThis !== 'undefined') {
+        const g = globalThis;
+        const currentTest = g.__CURRENT_TEST_TITLE__ || g.__CURRENT_TEST_ID__;
+        if (currentTest && !payloadObj.test) {
+            payloadObj.test = currentTest;
+        }
+        const workerId = g.__TESTSPECTRA_WORKER_ID__;
+        if (workerId !== undefined && payloadObj.workerId === undefined) {
+            payloadObj.workerId = workerId;
+        }
+    }
+    const payload = JSON.stringify(payloadObj);
     console.log(`[TESTSPECTRA_STEP_START] ${payload}`);
     try {
         const result = await fn();

package/dist/runner/collection.js

@@ -84,9 +84,22 @@ export class MultiElementRunner {
     eq(index) {
         const targetSelector = `${this._selector}[${index}]`;
         const elPromise = (async () => {
-            if (typeof $$ !== 'undefined') {
-                const elements = await $$(this._selector);
-                return elements[index];
+            const getElements = typeof $$ !== 'undefined' ? $$ : globalThis.$$;
+            if (typeof getElements === 'function') {
+                const elements = await getElements(this._selector);
+                if (typeof elements?.nth === 'function') {
+                    return elements.nth(index);
+                }
+                if (index === 0 && typeof elements?.first === 'function') {
+                    return elements.first();
+                }
+                if (elements && elements[index] !== undefined) {
+                    return elements[index];
+                }
+            }
+            const getDollar = typeof $ !== 'undefined' ? $ : globalThis.$;
+            if (typeof getDollar === 'function') {
+                return getDollar(targetSelector);
             }
             return { selector: targetSelector };
         })();
@@ -117,10 +130,23 @@ export class MultiElementRunner {
     last() {
         const targetSelector = `${this._selector}[last()]`;
         const elPromise = (async () => {
-            if (typeof $$ !== 'undefined') {
-                const elements = await $$(this._selector);
+            const getElements = typeof $$ !== 'undefined' ? $$ : globalThis.$$;
+            if (typeof getElements === 'function') {
+                const elements = await getElements(this._selector);
+                if (typeof elements?.last === 'function') {
+                    return elements.last();
+                }
+                if (typeof elements?.nth === 'function') {
+                    return elements.nth(-1);
+                }
                 const arr = Array.isArray(elements) ? elements : await elements;
-                return arr[arr.length - 1];
+                if (arr && arr.length > 0) {
+                    return arr[arr.length - 1];
+                }
+            }
+            const getDollar = typeof $ !== 'undefined' ? $ : globalThis.$;
+            if (typeof getDollar === 'function') {
+                return getDollar(targetSelector);
             }
             return { selector: targetSelector };
         })();

package/dist/runner/single.d.ts

@@ -90,11 +90,11 @@ export declare class SingleElementRunner implements PromiseLike<void>, ElementRe
      */
     select(value: string): this;
     /**
-     * Moves the mouse cursor over the target element (hover).
+     * Hovers over the target element.
      *
      * @example
      * ```ts
-     * await Spectra.get("#dropdown-menu-trigger").hover();
+     * await Spectra.get("#dropdown-trigger").hover();
      * ```
      * @returns Current runner instance for method chaining.
      */

package/dist/runner/single.js

@@ -120,9 +120,17 @@ export class SingleElementRunner {
         this._action = async () => {
             const el = await resolveElement(target);
             if (options?.clearFirst) {
-                await el.clearValue();
+                if (typeof el.clearValue === 'function')
+                    await el.clearValue();
+                else if (typeof el.clear === 'function')
+                    await el.clear();
             }
-            await el.setValue(value);
+            if (typeof el.setValue === 'function')
+                await el.setValue(value);
+            else if (typeof el.fill === 'function')
+                await el.fill(value);
+            else if (typeof el.type === 'function')
+                await el.type(value);
         };
         return this;
     }
@@ -140,7 +148,10 @@ export class SingleElementRunner {
         this._actionPayload = { type: 'action', key: 'clear', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
-            await el.clearValue();
+            if (typeof el.clearValue === 'function')
+                await el.clearValue();
+            else if (typeof el.clear === 'function')
+                await el.clear();
         };
         return this;
     }
@@ -159,16 +170,19 @@ export class SingleElementRunner {
         this._actionPayload = { type: 'action', key: 'selectOption', target: getRawTarget(target), args: [value] };
         this._action = async () => {
             const el = await resolveElement(target);
-            await el.selectByVisibleText(value);
+            if (typeof el.selectByVisibleText === 'function')
+                await el.selectByVisibleText(value);
+            else if (typeof el.selectOption === 'function')
+                await el.selectOption({ label: value });
         };
         return this;
     }
     /**
-     * Moves the mouse cursor over the target element (hover).
+     * Hovers over the target element.
      *
      * @example
      * ```ts
-     * await Spectra.get("#dropdown-menu-trigger").hover();
+     * await Spectra.get("#dropdown-trigger").hover();
      * ```
      * @returns Current runner instance for method chaining.
      */
@@ -177,7 +191,10 @@ export class SingleElementRunner {
         this._actionPayload = { type: 'action', key: 'hover', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
-            await el.moveTo();
+            if (typeof el.moveTo === 'function')
+                await el.moveTo();
+            else if (typeof el.hover === 'function')
+                await el.hover();
         };
         return this;
     }

package/dist/semantic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Semantic Natural Language Formatter
+ *
+ * Formats commands, actions, and assertions into clean, grammatically
+ * correct English sentences for real-time reporting.
+ */
+export declare function formatSemanticTarget(target: any, isCollection?: boolean): string;
+export declare function formatSemanticAction(action: string, target: any, args?: any[]): string;
+export declare function formatSemanticMatcher(target: any, matcher: string, args?: any[], isCollection?: boolean): string;
+export declare function formatSemanticBrowser(method: string, args?: any[]): string;

package/dist/semantic.js

@@ -0,0 +1,141 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Semantic Natural Language Formatter
+ *
+ * Formats commands, actions, and assertions into clean, grammatically
+ * correct English sentences for real-time reporting.
+ */
+export function formatSemanticTarget(target, isCollection = false) {
+    if (target === undefined || target === null)
+        return isCollection ? 'collection' : 'element';
+    if (typeof target === 'string') {
+        return isCollection ? `collection "${target}"` : `element "${target}"`;
+    }
+    if (typeof target === 'object') {
+        if (target.selector) {
+            return isCollection ? `collection "${target.selector}"` : `element "${target.selector}"`;
+        }
+        if (target.constructor && target.constructor.name && target.constructor.name !== 'Object') {
+            return `element "${target.constructor.name}"`;
+        }
+    }
+    return `element "${String(target)}"`;
+}
+export function formatSemanticAction(action, target, args = []) {
+    const targetStr = formatSemanticTarget(target, false);
+    const arg0 = args[0] !== undefined ? String(args[0]) : '';
+    switch (action) {
+        case 'type':
+            return `Type "${arg0}" into ${targetStr}`;
+        case 'click':
+            return `Click on ${targetStr}`;
+        case 'doubleClick':
+            return `Double-click on ${targetStr}`;
+        case 'rightClick':
+            return `Right-click on ${targetStr}`;
+        case 'check':
+            return `Check checkbox ${targetStr}`;
+        case 'uncheck':
+            return `Uncheck checkbox ${targetStr}`;
+        case 'selectOption':
+            return `Select option "${arg0}" in ${targetStr}`;
+        case 'clear':
+            return `Clear text in ${targetStr}`;
+        case 'hover':
+            return `Hover over ${targetStr}`;
+        case 'scrollIntoView':
+            return `Scroll ${targetStr} into view`;
+        case 'navigate':
+            return `Navigate to "${arg0}"`;
+        case 'wait':
+            return `Wait for ${arg0}ms`;
+        case 'pause':
+            return `Pause execution for ${arg0}ms`;
+        default:
+            return `Perform ${action} on ${targetStr}`;
+    }
+}
+export function formatSemanticMatcher(target, matcher, args = [], isCollection = false) {
+    const targetStr = formatSemanticTarget(target, isCollection);
+    const arg0 = args[0] !== undefined ? String(args[0]) : '';
+    const arg1 = args[1] !== undefined ? String(args[1]) : '';
+    switch (matcher) {
+        case 'be.visible':
+            return `Expect ${targetStr} to be visible`;
+        case 'not.be.visible':
+            return `Expect ${targetStr} not to be visible`;
+        case 'exist':
+            return `Expect ${targetStr} to exist in DOM`;
+        case 'not.exist':
+            return `Expect ${targetStr} not to exist in DOM`;
+        case 'be.enabled':
+            return `Expect ${targetStr} to be enabled`;
+        case 'be.disabled':
+            return `Expect ${targetStr} to be disabled`;
+        case 'be.checked':
+            return `Expect ${targetStr} to be checked`;
+        case 'not.be.checked':
+            return `Expect ${targetStr} not to be checked`;
+        case 'have.text':
+            return `Expect ${targetStr} to have text "${arg0}"`;
+        case 'not.have.text':
+            return `Expect ${targetStr} not to have text "${arg0}"`;
+        case 'contain.text':
+            return `Expect ${targetStr} to contain text "${arg0}"`;
+        case 'not.contain.text':
+            return `Expect ${targetStr} not to contain text "${arg0}"`;
+        case 'have.value':
+            return `Expect ${targetStr} to have value "${arg0}"`;
+        case 'not.have.value':
+            return `Expect ${targetStr} not to have value "${arg0}"`;
+        case 'contain.value':
+            return `Expect ${targetStr} to contain value "${arg0}"`;
+        case 'not.contain.value':
+            return `Expect ${targetStr} not to contain value "${arg0}"`;
+        case 'have.class':
+            return `Expect ${targetStr} to have class "${arg0}"`;
+        case 'not.have.class':
+            return `Expect ${targetStr} not to have class "${arg0}"`;
+        case 'have.attr':
+            return args.length >= 2
+                ? `Expect ${targetStr} to have attribute "${arg0}" = "${arg1}"`
+                : `Expect ${targetStr} to have attribute "${arg0}"`;
+        case 'not.have.attr':
+            return `Expect ${targetStr} not to have attribute "${arg0}"`;
+        case 'be.focused':
+            return `Expect ${targetStr} to be focused`;
+        case 'be.selected':
+            return `Expect ${targetStr} to be selected`;
+        case 'be.empty':
+            return `Expect ${targetStr} to be empty`;
+        case 'not.be.empty':
+            return `Expect ${targetStr} not to be empty`;
+        case 'have.length':
+            return `Expect ${targetStr} count to equal ${arg0}`;
+        case 'have.length.greaterThan':
+            return `Expect ${targetStr} count to be greater than ${arg0}`;
+        case 'have.length.lessThan':
+            return `Expect ${targetStr} count to be less than ${arg0}`;
+        case 'have.length.atLeast':
+            return `Expect ${targetStr} count to be at least ${arg0}`;
+        case 'have.length.atMost':
+            return `Expect ${targetStr} count to be at most ${arg0}`;
+        default:
+            return `Expect ${targetStr} to match ${matcher}`;
+    }
+}
+export function formatSemanticBrowser(method, args = []) {
+    const arg0 = args[0] !== undefined ? String(args[0]) : '';
+    switch (method) {
+        case 'shouldContainTitle':
+            return `Expect browser title to contain "${arg0}"`;
+        case 'shouldHaveTitle':
+            return `Expect browser title to be "${arg0}"`;
+        case 'shouldContainUrl':
+            return `Expect browser URL to contain "${arg0}"`;
+        case 'shouldHaveUrl':
+            return `Expect browser URL to be "${arg0}"`;
+        default:
+            return `Expect browser to ${method} "${arg0}"`;
+    }
+}

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' | 'back' | 'refresh';
+export type ActionKey = 'navigate' | 'click' | 'type' | 'clear' | 'select' | 'scroll' | 'swipe' | 'wait' | 'waitForElement' | 'pressKey' | 'longPress' | 'doubleClick' | 'hover' | 'dragDrop' | 'upload' | 'back' | 'refresh';
 /**
  * Canonical assertion keys supported across TestSpectra runner and database models.
  * @see backend/src/models/test_step.rs
@@ -685,6 +685,28 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
      * ```
      */
     clear(): Promise<void>;
+    /**
+     * Uploads one or more files to this file input element (`<input type="file">`).
+     * Accepts a file path string, fixture object/path (e.g. `Fixture.sampleImage`), `File` instance, or an array of them.
+     *
+     * @param files File path, fixture path, or File instance to attach.
+     * @example
+     * ```ts
+     * await Spectra.get('#file-upload').upload(Fixture.sampleImage);
+     * await Spectra.get('input[type="file"]').upload('fixtures/sample.pdf');
+     * ```
+     */
+    upload(files: unknown): Promise<void>;
+    /**
+     * Uploads one or more files to this file input element (alias to `upload()`).
+     *
+     * @param files File path, fixture path, or File instance to attach.
+     * @example
+     * ```ts
+     * await Spectra.get('#file-upload').uploadFile(Fixture.sampleImage);
+     * ```
+     */
+    uploadFile(files: unknown): Promise<void>;
     /**
      * Selects an option in a `<select>` element by its visible text or value.
      *
@@ -1006,6 +1028,17 @@ export interface QueuedMockResponse {
     /** Milliseconds to wait before fulfilling this response — simulates a late/slow network reply. */
     delayMs?: number;
 }
+/**
+ * A transport-agnostic selected mock response: the next `respondOnce` queue item wins (FIFO),
+ * otherwise the rule default. Produced by the shared `consumeMockResponse` helper; each
+ * transport (CDP `Fetch.fulfillRequest`, in-page `Response`, mobile mock proxy) renders it.
+ */
+export interface ConsumedMockResponse {
+    body: unknown;
+    statusCode: number;
+    headers: Record<string, string>;
+    delayMs?: number;
+}
 /**
  * Mock rule configuration for CDP & Mobile network request interception.
  */

package/dist/worker_config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared worker-runtime configuration contract.
+ *
+ * This is the single source of truth for the shape of `globalThis.__TESTSPECTRA_CONFIG__`, the
+ * runtime config object every host injects before the shared DSL is exercised:
+ *
+ * - E2E: the Rust orchestrator writes it into the Bun worker script
+ *   (`core/orchestrator/src/worker_runtime.rs`) — one worker per spec batch.
+ * - Component testing: `@testspectra/react`'s browser prelude publishes it
+ *   (`tools/react/src/prelude.ts`) — one page per spec file.
+ *
+ * `core/worker-runtime/src/harness/config.ts`'s `getWorkerConfig()` reads it back with the
+ * priority: in-memory override → this global → `process.env.TESTSPECTRA_CONFIG` → hard defaults,
+ * so both hosts resolve runtime knobs (step delay, implicit wait, env vars, network monitoring)
+ * identically instead of each keeping a private config shape.
+ */
+/** Metadata for an auto-discovered Page Object class. */
+export interface PageObjectInfo {
+    name: string;
+    file_path: string;
+}
+/** Metadata for an auto-discovered Fixture data file. */
+export interface FixtureInfo {
+    name: string;
+    file_path: string;
+    is_json: boolean;
+}
+/** Metadata for an auto-discovered Step definition. */
+export interface StepInfo {
+    name: string;
+    file_path: string;
+}
+/** Metadata for an auto-discovered custom Action. */
+export interface ActionInfo {
+    name: string;
+    file_path: string;
+}
+/** Metadata for an auto-discovered lifecycle Hook. */
+export interface HookInfo {
+    hook_type: 'before' | 'after' | 'beforeEach' | 'afterEach' | string;
+    file_path: string;
+}
+/** Auto-import manifest containing all discovered support files. */
+export interface AutoImportManifestConfig {
+    page_objects?: PageObjectInfo[];
+    fixtures?: FixtureInfo[];
+    steps?: StepInfo[];
+    actions?: ActionInfo[];
+    global_hooks?: HookInfo[];
+    suite_hooks?: Record<string, HookInfo[]>;
+}
+/** One targeted test case inside a worker's batch. */
+export interface TestCaseTargetItem {
+    id: string;
+    title: string;
+    filePath: string;
+    suite: string;
+}
+/**
+ * Runtime configuration injected by a host (Rust orchestrator or `@testspectra/react`) via
+ * `globalThis.__TESTSPECTRA_CONFIG__`.
+ */
+export interface TestSpectraWorkerConfig {
+    workerId?: number;
+    rootDir: string;
+    testFilePath?: string;
+    testFiles?: TestCaseTargetItem[];
+    activePlatform: string;
+    configuredBaseUrl: string;
+    cdpWsUrl: string;
+    driverServerUrl: string;
+    manifest?: AutoImportManifestConfig;
+    /** Target app package (Android). Paired with androidSerial/adbPath for on-demand adb actions. */
+    appPackage?: string;
+    /** Target adb device serial for this worker (Android only). */
+    androidSerial?: string;
+    /** Resolved `adb` binary path (Android only), paired with androidSerial above. */
+    adbPath?: string;
+    /** Host port this worker's own MobileMockProxyServer should listen on (Android only). */
+    mockProxyPort?: number;
+    implicitWaitMs?: number;
+    timeoutMs?: number;
+    stepDelayMs?: number;
+    /** Video recording options or boolean toggle */
+    video?: boolean | Record<string, any>;
+    /** Configured host aliases (e.g. auth: 'http://auth.local'). */
+    hosts?: Record<string, string>;
+    /** Mirrors `spectra.config.ts`'s `executionConfig.networkMonitoringEnabled` (default: true). */
+    networkMonitoringEnabled?: boolean;
+    /** Mirrors `spectra.config.ts`'s `executionConfig.monitoredDomains`. Empty/absent = capture all. */
+    monitoredDomains?: {
+        domain: string;
+        enabled: boolean;
+    }[];
+    /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
+    environmentVariables?: Record<string, string>;
+}

package/dist/worker_config.js

@@ -0,0 +1,17 @@
+/**
+ * Shared worker-runtime configuration contract.
+ *
+ * This is the single source of truth for the shape of `globalThis.__TESTSPECTRA_CONFIG__`, the
+ * runtime config object every host injects before the shared DSL is exercised:
+ *
+ * - E2E: the Rust orchestrator writes it into the Bun worker script
+ *   (`core/orchestrator/src/worker_runtime.rs`) — one worker per spec batch.
+ * - Component testing: `@testspectra/react`'s browser prelude publishes it
+ *   (`tools/react/src/prelude.ts`) — one page per spec file.
+ *
+ * `core/worker-runtime/src/harness/config.ts`'s `getWorkerConfig()` reads it back with the
+ * priority: in-memory override → this global → `process.env.TESTSPECTRA_CONFIG` → hard defaults,
+ * so both hosts resolve runtime knobs (step delay, implicit wait, env vars, network monitoring)
+ * identically instead of each keeping a private config shape.
+ */
+export {};

package/package.json

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

package/src/contract.ts

@@ -8,6 +8,7 @@
  * DSL layer contains zero platform branching.
  */
 
+import type { TestSpectraWorkerConfig } from './worker_config.js';
 import type {
   CDPNetworkEntry,
   MockInterceptHandle,
@@ -19,38 +20,10 @@ import type {
 } from './types.js';
 
 /**
- * Runtime configuration injected by the Rust orchestrator via `globalThis.__TESTSPECTRA_CONFIG__`.
+ * @deprecated Renamed to `TestSpectraWorkerConfig` (now shared by E2E and component testing).
+ * Kept as an alias for backwards compatibility.
  */
-export interface RuntimeWorkerConfig {
-  workerId?: number;
-  rootDir: string;
-  testFilePath?: string;
-  testFiles?: Array<{ id: string; title: string; filePath: string; suite: string }>;
-  activePlatform: string;
-  configuredBaseUrl: string;
-  cdpWsUrl: string;
-  driverServerUrl: string;
-  manifest?: Record<string, any>;
-  /** Target app package (Android). Paired with androidSerial/adbPath for on-demand adb actions. */
-  appPackage?: string;
-  /** Target adb device serial for this worker (Android only). */
-  androidSerial?: string;
-  /** Resolved `adb` binary path (Android only), paired with androidSerial above. */
-  adbPath?: string;
-  /** Host port this worker's own MobileMockProxyServer should listen on (Android only) — derived
-   * per-device the same way androidSerial/the driver-server port already are, so each device in
-   * a multi-device run gets its own proxy instead of every worker racing for one shared port. */
-  mockProxyPort?: number;
-  implicitWaitMs?: number;
-  timeoutMs?: number;
-  stepDelayMs?: number;
-  /** Mirrors `spectra.config.ts`'s `executionConfig.networkMonitoringEnabled` (default: true). */
-  networkMonitoringEnabled?: boolean;
-  /** Mirrors `spectra.config.ts`'s `executionConfig.monitoredDomains`. Empty/absent = capture all. */
-  monitoredDomains?: { domain: string; enabled: boolean }[];
-  /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
-  environmentVariables?: Record<string, string>;
-}
+export type RuntimeWorkerConfig = TestSpectraWorkerConfig;
 
 /**
  * Cross-cutting shared runtime state injected into the assembled worker script.
@@ -181,6 +154,7 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
   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>;
+  upload(selector: string | ScopedSelector, files: unknown, index?: number | null): Promise<void>;
 
   // --- Element State Inspection ---
   getText(selector: string | ScopedSelector, index?: number | null): Promise<string>;
@@ -216,8 +190,3 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
   consoleErrors: string[];
   recordedNetwork: CDPNetworkEntry[];
 }
-
-declare global {
-  // eslint-disable-next-line no-var
-  var __TS_RUNTIME__: RuntimeContext;
-}

package/src/index.ts

@@ -6,5 +6,6 @@
  */
 
 export * from './types.js';
+export * from './worker_config.js';
 export * from './contract.js';
 export * from './proto.js';

package/src/proto.ts

@@ -33,3 +33,5 @@ declare global {
     interface Browser extends SpectraBrowserBridge {}
   }
 }
+
+export type SpectraEnv = globalThis.SpectraEnv;

package/src/types.ts

@@ -17,6 +17,7 @@ export type ActionKey =
   | 'doubleClick'
   | 'hover'
   | 'dragDrop'
+  | 'upload'
   | 'back'
   | 'refresh';
 
@@ -855,6 +856,30 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
    */
   clear(): Promise<void>;
 
+  /**
+   * Uploads one or more files to this file input element (`<input type="file">`).
+   * Accepts a file path string, fixture object/path (e.g. `Fixture.sampleImage`), `File` instance, or an array of them.
+   *
+   * @param files File path, fixture path, or File instance to attach.
+   * @example
+   * ```ts
+   * await Spectra.get('#file-upload').upload(Fixture.sampleImage);
+   * await Spectra.get('input[type="file"]').upload('fixtures/sample.pdf');
+   * ```
+   */
+  upload(files: unknown): Promise<void>;
+
+  /**
+   * Uploads one or more files to this file input element (alias to `upload()`).
+   *
+   * @param files File path, fixture path, or File instance to attach.
+   * @example
+   * ```ts
+   * await Spectra.get('#file-upload').uploadFile(Fixture.sampleImage);
+   * ```
+   */
+  uploadFile(files: unknown): Promise<void>;
+
   /**
    * Selects an option in a `<select>` element by its visible text or value.
    *
@@ -1204,6 +1229,18 @@ export interface QueuedMockResponse {
   delayMs?: number;
 }
 
+/**
+ * A transport-agnostic selected mock response: the next `respondOnce` queue item wins (FIFO),
+ * otherwise the rule default. Produced by the shared `consumeMockResponse` helper; each
+ * transport (CDP `Fetch.fulfillRequest`, in-page `Response`, mobile mock proxy) renders it.
+ */
+export interface ConsumedMockResponse {
+  body: unknown;
+  statusCode: number;
+  headers: Record<string, string>;
+  delayMs?: number;
+}
+
 /**
  * Mock rule configuration for CDP & Mobile network request interception.
  */