@testspectra/matchers 1.1.11-rc.5 → 1.1.13

package/dist/__tests__/matcher-contracts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/matcher-contracts.test.js

@@ -0,0 +1,498 @@
+import { describe, it, expect, vi } from 'vitest';
+// Helper polling simulation resembling worker.ts pollCondition
+async function pollCondition(fn, timeoutMs = 100, intervalMs = 10) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            if (await fn())
+                return true;
+        }
+        catch { }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    try {
+        return await fn();
+    }
+    catch {
+        return false;
+    }
+}
+// Factory to create a test SingleElementProxy backed by simulated DOM element state
+function createTestElementProxy(selector, state) {
+    const proxy = {
+        selector,
+        async isDisplayed() {
+            return state.displayed ?? true;
+        },
+        async isExisting() {
+            return state.existing ?? true;
+        },
+        async isEnabled() {
+            return state.enabled ?? true;
+        },
+        async isSelected() {
+            return state.selected ?? false;
+        },
+        async isFocused() {
+            return state.focused ?? false;
+        },
+        async getText() {
+            return state.text ?? '';
+        },
+        async getValue() {
+            return state.value ?? '';
+        },
+        async getAttribute(name) {
+            return state.attributes?.[name] ?? null;
+        },
+        async getCSSProperty(property) {
+            return { property, value: state.css?.[property] ?? '', parsed: {} };
+        },
+        async click() { },
+        async doubleClick() { },
+        async rightClick() { },
+        async hover() { },
+        async focus() { },
+        async clear() { },
+        async type(_text) { },
+        async select(_option) { },
+        async selectByAttribute(_attribute, _value) { },
+        async selectByValue(_value) { },
+        async selectByIndex(_index) { },
+        async selectByVisibleText(_text) { },
+        async dragDrop(_destination) { },
+        async scrollIntoView() { },
+        async swipe(_options) { },
+        async longPress(_options) { },
+        async waitForElement(_timeoutMs) { },
+        async waitForExist(_timeoutMs) { },
+        async waitForDisplayed(_timeoutMs) { },
+        async waitForEnabled(_timeoutMs) { },
+        // Matcher implementations identical to worker.ts logic
+        async shouldBeVisible() {
+            const ok = await pollCondition(async () => await this.isDisplayed());
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to be visible`);
+        },
+        async shouldNotBeVisible() {
+            const ok = await pollCondition(async () => !(await this.isDisplayed()));
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to be visible`);
+        },
+        async shouldExist() {
+            const ok = await pollCondition(async () => await this.isExisting());
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to exist in DOM`);
+        },
+        async shouldNotExist() {
+            const ok = await pollCondition(async () => !(await this.isExisting()));
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to exist in DOM`);
+        },
+        async shouldBeEnabled() {
+            const ok = await pollCondition(async () => await this.isEnabled());
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to be enabled`);
+        },
+        async shouldBeDisabled() {
+            const ok = await pollCondition(async () => !(await this.isEnabled()));
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to be disabled`);
+        },
+        async shouldBeChecked() {
+            const ok = await pollCondition(async () => await this.isSelected());
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to be checked`);
+        },
+        async shouldNotBeChecked() {
+            const ok = await pollCondition(async () => !(await this.isSelected()));
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to be checked`);
+        },
+        async shouldBeFocused() {
+            const ok = await pollCondition(async () => await this.isFocused());
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to be focused`);
+        },
+        async shouldNotBeFocused() {
+            const ok = await pollCondition(async () => !(await this.isFocused()));
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to be focused`);
+        },
+        async shouldHaveText(expected) {
+            let actual = '';
+            const ok = await pollCondition(async () => {
+                actual = await this.getText();
+                if (expected instanceof RegExp)
+                    return expected.test(actual);
+                return actual === String(expected) || actual.trim() === String(expected).trim();
+            });
+            if (!ok) {
+                if (expected instanceof RegExp)
+                    throw new Error(`Expected element "${selector}" text to match ${expected}, but got "${actual}"`);
+                throw new Error(`Expected element "${selector}" to have text "${expected}", but got "${actual}"`);
+            }
+        },
+        async shouldNotHaveText(expected) {
+            let actual = '';
+            const ok = await pollCondition(async () => {
+                actual = await this.getText();
+                if (expected instanceof RegExp)
+                    return !expected.test(actual);
+                return actual !== String(expected) && actual.trim() !== String(expected).trim();
+            });
+            if (!ok) {
+                if (expected instanceof RegExp)
+                    throw new Error(`Expected element "${selector}" text not to match ${expected}`);
+                throw new Error(`Expected element "${selector}" not to have text "${expected}"`);
+            }
+        },
+        async shouldContainText(substring) {
+            let actual = '';
+            const ok = await pollCondition(async () => {
+                actual = await this.getText();
+                return actual.includes(String(substring));
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to contain text "${substring}", but got "${actual}"`);
+        },
+        async shouldNotContainText(substring) {
+            let actual = '';
+            const ok = await pollCondition(async () => {
+                actual = await this.getText();
+                return !actual.includes(String(substring));
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to contain text "${substring}"`);
+        },
+        async shouldHaveValue(value) {
+            let actual = '';
+            const ok = await pollCondition(async () => {
+                actual = await this.getValue();
+                return actual === String(value);
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to have value "${value}", but got "${actual}"`);
+        },
+        async shouldNotHaveValue(value) {
+            const ok = await pollCondition(async () => {
+                const actual = await this.getValue();
+                return actual !== String(value);
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to have value "${value}"`);
+        },
+        async shouldContainValue(value) {
+            let actual = '';
+            const ok = await pollCondition(async () => {
+                actual = await this.getValue();
+                return actual.includes(String(value));
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to contain value "${value}", but got "${actual}"`);
+        },
+        async shouldNotContainValue(value) {
+            const ok = await pollCondition(async () => {
+                const actual = await this.getValue();
+                return !actual.includes(String(value));
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to contain value "${value}"`);
+        },
+        async shouldHaveClass(className) {
+            const ok = await pollCondition(async () => state.classes?.includes(className) ?? false);
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to have class "${className}"`);
+        },
+        async shouldNotHaveClass(className) {
+            const ok = await pollCondition(async () => !(state.classes?.includes(className) ?? false));
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to have class "${className}"`);
+        },
+        async shouldHaveAttribute(name, value) {
+            let actual = null;
+            const ok = await pollCondition(async () => {
+                actual = await this.getAttribute(name);
+                if (value !== undefined)
+                    return actual === String(value);
+                return actual !== null;
+            });
+            if (!ok) {
+                if (value !== undefined)
+                    throw new Error(`Expected element "${selector}" to have attribute "${name}" = "${value}", but got "${actual}"`);
+                throw new Error(`Expected element "${selector}" to have attribute "${name}"`);
+            }
+        },
+        async shouldNotHaveAttribute(name) {
+            const ok = await pollCondition(async () => {
+                const actual = await this.getAttribute(name);
+                return actual === null;
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to have attribute "${name}"`);
+        },
+        async shouldHaveCss(property, value) {
+            let actualCss = '';
+            const ok = await pollCondition(async () => {
+                const css = await this.getCSSProperty(property);
+                actualCss = css.value;
+                return actualCss === value;
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" to have CSS "${property}" = "${value}", but got "${actualCss}"`);
+        },
+        async shouldNotHaveCss(property, value) {
+            const ok = await pollCondition(async () => {
+                const css = await this.getCSSProperty(property);
+                return css.value !== value;
+            });
+            if (!ok)
+                throw new Error(`Expected element "${selector}" not to have CSS "${property}" = "${value}"`);
+        },
+    };
+    return proxy;
+}
+// Factory to create a test CollectionProxy backed by simulated count
+function createTestCollectionProxy(selector, itemsCount) {
+    return {
+        selector,
+        async count() {
+            return itemsCount;
+        },
+        get length() {
+            return this.count();
+        },
+        first() {
+            return createTestElementProxy(`${selector}:first-child`, {});
+        },
+        last() {
+            return createTestElementProxy(`${selector}:last-child`, {});
+        },
+        nth(index) {
+            return createTestElementProxy(`${selector}:nth-child(${index})`, {});
+        },
+        async shouldHaveLength(expected) {
+            let actual = 0;
+            const ok = await pollCondition(async () => {
+                actual = await this.count();
+                return actual === expected;
+            });
+            if (!ok)
+                throw new Error(`Expected collection "${selector}" count to equal ${expected}, but got ${actual}`);
+        },
+        async shouldNotHaveLength(expected) {
+            const ok = await pollCondition(async () => {
+                const actual = await this.count();
+                return actual !== expected;
+            });
+            if (!ok)
+                throw new Error(`Expected collection "${selector}" count not to equal ${expected}`);
+        },
+        async shouldHaveLengthGreaterThan(expected) {
+            let actual = 0;
+            const ok = await pollCondition(async () => {
+                actual = await this.count();
+                return actual > expected;
+            });
+            if (!ok)
+                throw new Error(`Expected collection "${selector}" count to be greater than ${expected}, but got ${actual}`);
+        },
+        async shouldHaveLengthLessThan(expected) {
+            let actual = 0;
+            const ok = await pollCondition(async () => {
+                actual = await this.count();
+                return actual < expected;
+            });
+            if (!ok)
+                throw new Error(`Expected collection "${selector}" count to be less than ${expected}, but got ${actual}`);
+        },
+        async shouldBeEmpty() {
+            let actual = 0;
+            const ok = await pollCondition(async () => {
+                actual = await this.count();
+                return actual === 0;
+            });
+            if (!ok)
+                throw new Error(`Expected collection "${selector}" to be empty, but got ${actual}`);
+        },
+        async shouldNotBeEmpty() {
+            const ok = await pollCondition(async () => {
+                const actual = await this.count();
+                return actual > 0;
+            });
+            if (!ok)
+                throw new Error(`Expected collection "${selector}" not to be empty`);
+        },
+    };
+}
+describe('Worker Matchers & Static Actions Verification Suite', () => {
+    describe('Single Element Visibility & Existence Matchers', () => {
+        it('passes shouldBeVisible when element is displayed, fails and throws when not displayed', async () => {
+            const visibleEl = createTestElementProxy('#btn-visible', { displayed: true });
+            await expect(visibleEl.shouldBeVisible()).resolves.toBeUndefined();
+            const hiddenEl = createTestElementProxy('#btn-hidden', { displayed: false });
+            await expect(hiddenEl.shouldBeVisible()).rejects.toThrow('Expected element "#btn-hidden" to be visible');
+        });
+        it('passes shouldNotBeVisible when element is hidden, fails and throws when displayed', async () => {
+            const hiddenEl = createTestElementProxy('#btn-hidden', { displayed: false });
+            await expect(hiddenEl.shouldNotBeVisible()).resolves.toBeUndefined();
+            const visibleEl = createTestElementProxy('#btn-visible', { displayed: true });
+            await expect(visibleEl.shouldNotBeVisible()).rejects.toThrow('Expected element "#btn-visible" not to be visible');
+        });
+        it('passes shouldExist when element is in DOM, fails and throws when missing', async () => {
+            const domEl = createTestElementProxy('#card', { existing: true });
+            await expect(domEl.shouldExist()).resolves.toBeUndefined();
+            const missingEl = createTestElementProxy('#missing-card', { existing: false });
+            await expect(missingEl.shouldExist()).rejects.toThrow('Expected element "#missing-card" to exist in DOM');
+        });
+        it('passes shouldNotExist when element is missing, fails and throws when element exists', async () => {
+            const missingEl = createTestElementProxy('#missing-card', { existing: false });
+            await expect(missingEl.shouldNotExist()).resolves.toBeUndefined();
+            const domEl = createTestElementProxy('#card', { existing: true });
+            await expect(domEl.shouldNotExist()).rejects.toThrow('Expected element "#card" not to exist in DOM');
+        });
+    });
+    describe('Single Element State Matchers (Enabled, Checked, Focused)', () => {
+        it('verifies shouldBeEnabled and shouldBeDisabled strictly', async () => {
+            const enabledEl = createTestElementProxy('#submit-btn', { enabled: true });
+            await expect(enabledEl.shouldBeEnabled()).resolves.toBeUndefined();
+            await expect(enabledEl.shouldBeDisabled()).rejects.toThrow('Expected element "#submit-btn" to be disabled');
+            const disabledEl = createTestElementProxy('#disabled-btn', { enabled: false });
+            await expect(disabledEl.shouldBeDisabled()).resolves.toBeUndefined();
+            await expect(disabledEl.shouldBeEnabled()).rejects.toThrow('Expected element "#disabled-btn" to be enabled');
+        });
+        it('verifies shouldBeChecked and shouldNotBeChecked strictly', async () => {
+            const checkedCheckbox = createTestElementProxy('#agree', { selected: true });
+            await expect(checkedCheckbox.shouldBeChecked()).resolves.toBeUndefined();
+            await expect(checkedCheckbox.shouldNotBeChecked()).rejects.toThrow('Expected element "#agree" not to be checked');
+            const uncheckedCheckbox = createTestElementProxy('#disagree', { selected: false });
+            await expect(uncheckedCheckbox.shouldNotBeChecked()).resolves.toBeUndefined();
+            await expect(uncheckedCheckbox.shouldBeChecked()).rejects.toThrow('Expected element "#disagree" to be checked');
+        });
+        it('verifies shouldBeFocused and shouldNotBeFocused strictly', async () => {
+            const focusedInput = createTestElementProxy('#email-input', { focused: true });
+            await expect(focusedInput.shouldBeFocused()).resolves.toBeUndefined();
+            await expect(focusedInput.shouldNotBeFocused()).rejects.toThrow('Expected element "#email-input" not to be focused');
+            const unfocusedInput = createTestElementProxy('#password-input', { focused: false });
+            await expect(unfocusedInput.shouldNotBeFocused()).resolves.toBeUndefined();
+            await expect(unfocusedInput.shouldBeFocused()).rejects.toThrow('Expected element "#password-input" to be focused');
+        });
+    });
+    describe('Content Matchers (Text, Value, Classes, Attributes, CSS)', () => {
+        it('strictly checks text equality and fails on mismatch', async () => {
+            const textEl = createTestElementProxy('#heading', { text: 'Welcome to TestSpectra' });
+            await expect(textEl.shouldHaveText('Welcome to TestSpectra')).resolves.toBeUndefined();
+            await expect(textEl.shouldHaveText(/Welcome to \w+/)).resolves.toBeUndefined();
+            await expect(textEl.shouldContainText('TestSpectra')).resolves.toBeUndefined();
+            // Negative assertions
+            await expect(textEl.shouldNotHaveText('Goodbye')).resolves.toBeUndefined();
+            await expect(textEl.shouldNotContainText('Cypress')).resolves.toBeUndefined();
+            // Failing conditions MUST throw and not falsely pass
+            await expect(textEl.shouldHaveText('Wrong Text')).rejects.toThrow('Expected element "#heading" to have text "Wrong Text", but got "Welcome to TestSpectra"');
+            await expect(textEl.shouldContainText('Selenium')).rejects.toThrow('Expected element "#heading" to contain text "Selenium", but got "Welcome to TestSpectra"');
+            await expect(textEl.shouldNotHaveText('Welcome to TestSpectra')).rejects.toThrow('Expected element "#heading" not to have text "Welcome to TestSpectra"');
+            await expect(textEl.shouldNotContainText('TestSpectra')).rejects.toThrow('Expected element "#heading" not to contain text "TestSpectra"');
+        });
+        it('strictly checks input values and fails on mismatch', async () => {
+            const inputEl = createTestElementProxy('#username', { value: 'admin_testspectra' });
+            await expect(inputEl.shouldHaveValue('admin_testspectra')).resolves.toBeUndefined();
+            await expect(inputEl.shouldContainValue('admin_')).resolves.toBeUndefined();
+            await expect(inputEl.shouldNotHaveValue('guest')).resolves.toBeUndefined();
+            await expect(inputEl.shouldNotContainValue('root')).resolves.toBeUndefined();
+            await expect(inputEl.shouldHaveValue('wrong_user')).rejects.toThrow('Expected element "#username" to have value "wrong_user", but got "admin_testspectra"');
+            await expect(inputEl.shouldNotHaveValue('admin_testspectra')).rejects.toThrow('Expected element "#username" not to have value "admin_testspectra"');
+        });
+        it('strictly checks classes and attributes', async () => {
+            const badge = createTestElementProxy('#status-badge', {
+                classes: ['badge', 'badge-success', 'active'],
+                attributes: { id: 'status-badge', 'data-role': 'indicator', disabled: 'false' },
+                css: { color: 'rgb(0, 128, 0)' },
+            });
+            await expect(badge.shouldHaveClass('badge-success')).resolves.toBeUndefined();
+            await expect(badge.shouldNotHaveClass('badge-danger')).resolves.toBeUndefined();
+            await expect(badge.shouldHaveAttribute('data-role', 'indicator')).resolves.toBeUndefined();
+            await expect(badge.shouldNotHaveAttribute('data-unknown')).resolves.toBeUndefined();
+            await expect(badge.shouldHaveCss('color', 'rgb(0, 128, 0)')).resolves.toBeUndefined();
+            // Fails when class/attribute is missing or incorrect
+            await expect(badge.shouldHaveClass('badge-danger')).rejects.toThrow('Expected element "#status-badge" to have class "badge-danger"');
+            await expect(badge.shouldNotHaveClass('badge-success')).rejects.toThrow('Expected element "#status-badge" not to have class "badge-success"');
+            await expect(badge.shouldHaveAttribute('data-role', 'wrong-val')).rejects.toThrow('Expected element "#status-badge" to have attribute "data-role" = "wrong-val", but got "indicator"');
+            await expect(badge.shouldNotHaveAttribute('data-role')).rejects.toThrow('Expected element "#status-badge" not to have attribute "data-role"');
+        });
+    });
+    describe('Collection Matchers ($$ / Spectra.getAll)', () => {
+        it('strictly checks collection lengths and emptiness', async () => {
+            const items = createTestCollectionProxy('.post-item', 5);
+            await expect(items.shouldHaveLength(5)).resolves.toBeUndefined();
+            await expect(items.shouldHaveLengthGreaterThan(3)).resolves.toBeUndefined();
+            await expect(items.shouldHaveLengthLessThan(10)).resolves.toBeUndefined();
+            await expect(items.shouldNotBeEmpty()).resolves.toBeUndefined();
+            // Failing conditions MUST throw
+            await expect(items.shouldHaveLength(0)).rejects.toThrow('Expected collection ".post-item" count to equal 0, but got 5');
+            await expect(items.shouldHaveLengthGreaterThan(10)).rejects.toThrow('Expected collection ".post-item" count to be greater than 10, but got 5');
+            await expect(items.shouldHaveLengthLessThan(3)).rejects.toThrow('Expected collection ".post-item" count to be less than 3, but got 5');
+            await expect(items.shouldBeEmpty()).rejects.toThrow('Expected collection ".post-item" to be empty, but got 5');
+            const emptyItems = createTestCollectionProxy('.empty-list', 0);
+            await expect(emptyItems.shouldBeEmpty()).resolves.toBeUndefined();
+            await expect(emptyItems.shouldNotBeEmpty()).rejects.toThrow('Expected collection ".empty-list" not to be empty');
+        });
+    });
+    describe('Spectra Static Automation API (Single Global Object)', () => {
+        it('correctly maps Spectra static methods to underlying actions without error', async () => {
+            const elementMock = createTestElementProxy('#test-btn', { text: 'Click Me', value: 'hello' });
+            const clickSpy = vi.spyOn(elementMock, 'click');
+            const typeSpy = vi.spyOn(elementMock, 'type');
+            const clearSpy = vi.spyOn(elementMock, 'clear');
+            const mockSpectra = {
+                get: (target) => (typeof target === 'string' ? elementMock : target),
+                getAll: (selector) => createTestCollectionProxy(selector, 2),
+                navigate: async (_url) => { },
+                back: async () => { },
+                forward: async () => { },
+                refresh: async () => { },
+                setViewport: async (_w, _h) => { },
+                wait: async (ms) => {
+                    await new Promise((r) => setTimeout(r, ms));
+                },
+                click: async (target) => {
+                    const el = typeof target === 'string' ? elementMock : target;
+                    await el.click();
+                },
+                doubleClick: async () => { },
+                rightClick: async () => { },
+                type: async (target, text) => {
+                    const el = typeof target === 'string' ? elementMock : target;
+                    await el.type(text);
+                },
+                clear: async (target) => {
+                    const el = typeof target === 'string' ? elementMock : target;
+                    await el.clear();
+                },
+                select: async () => { },
+                hover: async () => { },
+                dragDrop: async () => { },
+                scrollIntoView: async () => { },
+                scroll: async () => { },
+                swipe: async () => { },
+                longPress: async () => { },
+                pressKey: async () => { },
+                waitForElement: async () => { },
+                intercept: async () => ({ respondWith: async () => { }, callCount: () => 0 }),
+                clearMocks: () => { },
+                browser: {},
+            };
+            // Test actions call underlying proxy methods
+            await mockSpectra.click('#test-btn');
+            expect(clickSpy).toHaveBeenCalled();
+            await mockSpectra.type('#test-btn', 'Test input');
+            expect(typeSpy).toHaveBeenCalledWith('Test input');
+            await mockSpectra.clear('#test-btn');
+            expect(clearSpy).toHaveBeenCalled();
+            // Test wait execution timing
+            const start = Date.now();
+            await mockSpectra.wait(20);
+            const elapsed = Date.now() - start;
+            expect(elapsed).toBeGreaterThanOrEqual(15);
+        });
+    });
+});

package/dist/contract.d.ts

@@ -7,48 +7,13 @@
  * (`WebCdpDriverBridge`, `AndroidTcpDriverBridge`) implements this interface so that the
  * 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';
 /**
- * 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.
  *
@@ -139,6 +104,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>;
     getText(selector: string | ScopedSelector, index?: number | null): Promise<string>;
     getValue(selector: string | ScopedSelector, index?: number | null): Promise<string>;
     isDisplayed(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
@@ -168,6 +134,3 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
     consoleErrors: string[];
     recordedNetwork: CDPNetworkEntry[];
 }
-declare global {
-    var __TS_RUNTIME__: RuntimeContext;
-}

package/dist/index.d.ts

@@ -5,5 +5,6 @@
  * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
 export * from './types.js';
+export * from './worker_config.js';
 export * from './contract.js';
 export * from './proto.js';

package/dist/index.js

@@ -5,5 +5,6 @@
  * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
 export * from './types.js';
+export * from './worker_config.js';
 export * from './contract.js';
 export * from './proto.js';

package/dist/matchers.d.ts

@@ -6,9 +6,16 @@ import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from './type
  * @param target - Selector string or element instance.
  * @returns Resolved WebdriverIO.Element instance.
  */
-export declare function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element>;
 /**
- * Executes a single element matcher against the WebdriverIO browser / element context.
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, Playwright Locator, or ChainablePromiseElement)
+ * to an actionable element instance.
+ *
+ * @param target - Selector string or element instance.
+ * @returns Resolved element or locator instance.
+ */
+export declare function resolveElement(target: ElementTarget): Promise<any>;
+/**
+ * Executes a single element matcher against the active runner context (Playwright or WebdriverIO).
  *
  * @param target - Optional element target (not required for browser-level assertions).
  * @param matcher - Single element matcher string.
@@ -16,7 +23,7 @@ export declare function resolveElement(target: ElementTarget): Promise<Webdriver
  */
 export declare function executeSingleMatcher(target: ElementTarget | undefined, matcher: SingleElementMatcher, args: any[]): Promise<void>;
 /**
- * Executes a multi-element collection matcher against WebdriverIO $$.
+ * Executes a multi-element collection matcher against $$.
  *
  * @param selector - CSS/XPath selector for the collection.
  * @param matcher - Multi-element matcher string.