@testspectra/matchers 1.0.69 → 1.1.0

package/LICENSE.md

@@ -0,0 +1,48 @@
+# TestSpectra Commercial Software License Agreement
+
+Copyright (c) 2026 TestSpectra. All rights reserved.
+
+IMPORTANT NOTICE: This software is NOT open-source. Although distribution archives,
+npm packages, and editor extensions are publicly downloadable, installation,
+execution, and use of the Software are strictly conditioned upon obtaining a valid
+Commercial License or an authorized Evaluation/Trial License from TestSpectra.
+
+1. GRANT OF LICENSE
+   Subject to payment of applicable license fees or an active authorized evaluation
+   period, TestSpectra grants you a non-exclusive, non-transferable, revocable license
+   to install and execute the Software solely for authoring, debugging, and executing
+   automated software tests.
+
+2. LICENSE ACTIVATION & ENFORCEMENT
+   - Use of the Software requires activation via a valid License Key, authorized CI token,
+     or active TestSpectra Cloud account.
+   - Any attempt to circumvent, disable, modify, reverse engineer, or tamper with the
+     license verification mechanisms, cryptographic signatures, or binary checks is
+     a material breach of this Agreement and automatically terminates your license.
+
+3. RESTRICTIONS
+   You shall not, and shall not permit any third party to:
+   - Decompile, disassemble, reverse engineer, or derive source code from the binaries,
+     compiled scripts, or libraries of the Software.
+   - Sublicense, sell, rent, lease, distribute, or host the Software as a service for third parties.
+   - Re-brand, white-label, or package the Software or any of its components as part of a
+     competing commercial QA, testing, or developer tooling product.
+   - Modify, alter, or remove any proprietary notices, copyright labels, or license headers.
+
+4. INTELLECTUAL PROPERTY
+   The Software, including its source code, architecture, Rust core engine, algorithms,
+   matchers, extensions, interfaces, and documentation, represents valuable intellectual
+   property and trade secrets of TestSpectra.
+
+5. TERMINATION
+   This license is effective until terminated. Your rights under this license will terminate
+   automatically without notice if you fail to comply with any of its terms, or upon expiration
+   of your active subscription or trial term. Upon termination, you must cease all use of
+   the Software and delete all copies in your possession.
+
+6. DISCLAIMER OF WARRANTY & LIMITATION OF LIABILITY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+   INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+   PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   ARISING FROM THE USE OF OR INABILITY TO USE THE SOFTWARE.

package/dist/__tests__/intercept.test.d.ts

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

package/dist/__tests__/intercept.test.js

@@ -0,0 +1,183 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Spectra } from '../spectra.js';
+import { CdpHandler } from '../intercept/cdp-handler.js';
+import { MockRegistry } from '../intercept/mock-registry.js';
+describe('Spectra.intercept Custom Command & Deflaking Architecture (docs/v2/cli/matchers-interception-reliability.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-intercept-test-'));
+        Spectra.clearMocks();
+        MockRegistry.getInstance().clearRecordedResources();
+    });
+    afterEach(() => {
+        Spectra.clearMocks();
+        MockRegistry.getInstance().clearRecordedResources();
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('correctly shifts respondOnce FIFO queue before falling back to respondWith', async () => {
+        const mock = await Spectra.intercept({
+            url: '**/api/v1/export/status',
+            method: 'GET',
+        });
+        mock.respondOnce({ status: 200, body: { status: 'pending' } });
+        mock.respondOnce({ status: 200, body: { status: 'processing' } });
+        mock.respondWith({ status: 200, body: { status: 'completed', downloadUrl: '/file.pdf' } });
+        // Call 1: should return pending
+        const call1 = {
+            id: 'req-1',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res1 = await CdpHandler.dispatchIncomingRequest(call1);
+        expect(res1.response?.body).toEqual({ status: 'pending' });
+        // Call 2: should return processing
+        const call2 = {
+            id: 'req-2',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res2 = await CdpHandler.dispatchIncomingRequest(call2);
+        expect(res2.response?.body).toEqual({ status: 'processing' });
+        // Call 3: should fall back to default completed
+        const call3 = {
+            id: 'req-3',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res3 = await CdpHandler.dispatchIncomingRequest(call3);
+        expect(res3.response?.body).toEqual({ status: 'completed', downloadUrl: '/file.pdf' });
+        // Call 4: still completed
+        const call4 = {
+            id: 'req-4',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res4 = await CdpHandler.dispatchIncomingRequest(call4);
+        expect(res4.response?.body).toEqual({ status: 'completed', downloadUrl: '/file.pdf' });
+        expect(mock.callCount).toBe(4);
+        expect(mock.calls.length).toBe(4);
+    });
+    it('simulates network abort with specified error code', async () => {
+        const mock = await Spectra.intercept({
+            url: '**/api/v1/sync',
+            method: 'POST',
+        });
+        mock.abort('ConnectionReset');
+        const req = {
+            id: 'req-sync',
+            url: 'https://example.com/api/v1/sync',
+            method: 'POST',
+            body: { data: 'sync-payload' },
+            timestamp: Date.now(),
+        };
+        const fulfill = await CdpHandler.dispatchIncomingRequest(req);
+        expect(fulfill.aborted).toBe('ConnectionReset');
+        expect(mock.callCount).toBe(1);
+    });
+    it('supports waitForCall to await asynchronous incoming requests', async () => {
+        const mock = await Spectra.intercept({
+            url: '**/api/v1/async-task',
+            method: 'POST',
+            response: { status: 202, body: { ok: true } },
+        });
+        const waitPromise = mock.waitForCall({ timeout: 2000 });
+        // Dispatch after a brief async delay
+        setTimeout(() => {
+            CdpHandler.dispatchIncomingRequest({
+                id: 'req-async',
+                url: 'https://example.com/api/v1/async-task',
+                method: 'POST',
+                body: { started: true },
+                timestamp: Date.now(),
+            });
+        }, 50);
+        const receivedCall = await waitPromise;
+        expect(receivedCall.id).toBe('req-async');
+        expect(receivedCall.body).toEqual({ started: true });
+        expect(mock.callCount).toBe(1);
+    });
+    it('prevents mock bleeding across test cases via Spectra.clearMocks()', async () => {
+        // Step 1: Register mock in test case A
+        const mockA = await Spectra.intercept({
+            url: '**/api/v1/user/profile',
+            method: 'GET',
+            response: { status: 200, body: { user: 'Alice' } },
+        });
+        await CdpHandler.dispatchIncomingRequest({
+            id: 'req-user',
+            url: 'https://example.com/api/v1/user/profile',
+            method: 'GET',
+            timestamp: Date.now(),
+        });
+        expect(mockA.callCount).toBe(1);
+        // Step 2: Clear mocks as done in afterEach hook
+        Spectra.clearMocks();
+        // Step 3: Verify registry is clean and no mock bleeds
+        const registry = MockRegistry.getInstance();
+        const matched = registry.findMatchingHandle('GET', 'https://example.com/api/v1/user/profile');
+        expect(matched).toBeUndefined();
+    });
+    it('runs 50 consecutive iterations of mock tests with 0% flakiness', async () => {
+        for (let i = 1; i <= 50; i++) {
+            Spectra.clearMocks();
+            const mock = await Spectra.intercept({
+                url: `**/api/v1/item/${i}`,
+                method: 'GET',
+                response: { status: 200, body: { iteration: i } },
+            });
+            const req = {
+                id: `iter-${i}`,
+                url: `https://example.com/api/v1/item/${i}`,
+                method: 'GET',
+                timestamp: Date.now(),
+            };
+            const result = await CdpHandler.dispatchIncomingRequest(req);
+            expect(result.response?.body).toEqual({ iteration: i });
+            expect(mock.callCount).toBe(1);
+        }
+    });
+    it('records network traffic and exports to network-resources.json in spec format', async () => {
+        await Spectra.intercept({
+            url: '**/v1/users/me',
+            method: 'GET',
+            response: {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+                body: { id: 'usr-1', name: 'Admin' },
+            },
+        });
+        const req = {
+            id: 'req-001',
+            url: 'https://api.testspectra.dev/v1/users/me',
+            method: 'GET',
+            headers: { authorization: 'Bearer test-token' },
+            timestamp: Date.now(),
+        };
+        await CdpHandler.dispatchIncomingRequest(req);
+        const reportPath = path.join(tmpDir, 'runs', 'run-001', 'network-resources.json');
+        MockRegistry.getInstance().exportNetworkResources(reportPath);
+        expect(fs.existsSync(reportPath)).toBe(true);
+        const content = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+        expect(Array.isArray(content)).toBe(true);
+        expect(content.length).toBe(1);
+        const entry = content[0];
+        expect(entry.id).toBe('req-001');
+        expect(entry.url).toBe('https://api.testspectra.dev/v1/users/me');
+        expect(entry.method).toBe('GET');
+        expect(entry.status).toBe(200);
+        expect(entry.resourceType).toBe('fetch');
+        expect(entry.timing).toBeDefined();
+        expect(entry.timing.total).toBeGreaterThan(0);
+        expect(entry.responseBody).toEqual({ id: 'usr-1', name: 'Admin' });
+    });
+});

package/dist/__tests__/matchers.test.d.ts

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

package/dist/__tests__/matchers.test.js

@@ -0,0 +1,161 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Spectra, SingleElementRunner, MultiElementRunner, installPrototypes } from '../index.js';
+describe('Matchers Assertion Library & Receiver API', () => {
+    describe('SingleElementRunner - 26 Receiver Assertion Methods', () => {
+        it('should queue visibility and DOM existence assertions', () => {
+            const runner = new SingleElementRunner('#hero');
+            runner.shouldBeVisible().shouldNotBeVisible().shouldExist().shouldNotExist();
+            const assertions = runner._assertions;
+            expect(assertions).toHaveLength(4);
+            expect(assertions[0].matcher).toBe('be.visible');
+            expect(assertions[1].matcher).toBe('not.be.visible');
+            expect(assertions[2].matcher).toBe('exist');
+            expect(assertions[3].matcher).toBe('not.exist');
+        });
+        it('should queue interactivity and state assertions', () => {
+            const runner = new SingleElementRunner('#btn');
+            runner
+                .shouldBeClickable()
+                .shouldNotBeClickable()
+                .shouldBeEnabled()
+                .shouldBeDisabled()
+                .shouldBeChecked()
+                .shouldNotBeChecked()
+                .shouldBeFocused()
+                .shouldNotBeFocused();
+            const assertions = runner._assertions;
+            expect(assertions).toHaveLength(8);
+            expect(assertions[0].matcher).toBe('be.clickable');
+            expect(assertions[1].matcher).toBe('not.be.clickable');
+            expect(assertions[2].matcher).toBe('be.enabled');
+            expect(assertions[3].matcher).toBe('be.disabled');
+            expect(assertions[4].matcher).toBe('be.checked');
+            expect(assertions[5].matcher).toBe('not.be.checked');
+            expect(assertions[6].matcher).toBe('be.focused');
+            expect(assertions[7].matcher).toBe('not.be.focused');
+        });
+        it('should queue text and value assertions with arguments', () => {
+            const runner = new SingleElementRunner('#input');
+            runner
+                .shouldHaveText('Welcome')
+                .shouldNotHaveText('Goodbye')
+                .shouldContainText('come')
+                .shouldNotContainText('bye')
+                .shouldHaveValue('admin')
+                .shouldNotHaveValue('guest')
+                .shouldContainValue('adm')
+                .shouldNotContainValue('gst');
+            const assertions = runner._assertions;
+            expect(assertions).toHaveLength(8);
+            expect(assertions[0]).toEqual({ target: '#input', matcher: 'have.text', args: ['Welcome'] });
+            expect(assertions[1]).toEqual({ target: '#input', matcher: 'not.have.text', args: ['Goodbye'] });
+            expect(assertions[2]).toEqual({ target: '#input', matcher: 'contain.text', args: ['come'] });
+            expect(assertions[3]).toEqual({ target: '#input', matcher: 'not.contain.text', args: ['bye'] });
+            expect(assertions[4]).toEqual({ target: '#input', matcher: 'have.value', args: ['admin'] });
+            expect(assertions[5]).toEqual({ target: '#input', matcher: 'not.have.value', args: ['guest'] });
+            expect(assertions[6]).toEqual({ target: '#input', matcher: 'contain.value', args: ['adm'] });
+            expect(assertions[7]).toEqual({ target: '#input', matcher: 'not.contain.value', args: ['gst'] });
+        });
+        it('should queue attribute, class, and CSS assertions', () => {
+            const runner = new SingleElementRunner('#card');
+            runner
+                .shouldHaveAttribute('data-testid', 'test-card')
+                .shouldNotHaveAttribute('disabled')
+                .shouldHaveClass('active')
+                .shouldNotHaveClass('hidden')
+                .shouldHaveCss('color', 'red')
+                .shouldNotHaveCss('display', 'none');
+            const assertions = runner._assertions;
+            expect(assertions).toHaveLength(6);
+            expect(assertions[0]).toEqual({ target: '#card', matcher: 'have.attr', args: ['data-testid', 'test-card'] });
+            expect(assertions[1]).toEqual({ target: '#card', matcher: 'not.have.attr', args: ['disabled'] });
+            expect(assertions[2]).toEqual({ target: '#card', matcher: 'have.class', args: ['active'] });
+            expect(assertions[3]).toEqual({ target: '#card', matcher: 'not.have.class', args: ['hidden'] });
+            expect(assertions[4]).toEqual({ target: '#card', matcher: 'have.css', args: ['color', 'red'] });
+            expect(assertions[5]).toEqual({ target: '#card', matcher: 'not.have.css', args: ['display', 'none'] });
+        });
+    });
+    describe('SingleElementRunner - Actions', () => {
+        it('should support action method chaining and label assignment', () => {
+            const runner = new SingleElementRunner('#target');
+            expect(runner.click()).toBe(runner);
+            expect(runner._actionPayload.key).toBe('click');
+            expect(runner.doubleClick()).toBe(runner);
+            expect(runner._actionPayload.key).toBe('doubleClick');
+            expect(runner.rightClick()).toBe(runner);
+            expect(runner._actionPayload.key).toBe('rightClick');
+            expect(runner.scrollIntoView()).toBe(runner);
+            expect(runner._actionPayload.key).toBe('scrollIntoView');
+            expect(runner.dragDrop('#dest')).toBe(runner);
+            expect(runner._actionPayload.key).toBe('dragDrop');
+        });
+        it('should support action to semantic assertion chaining', () => {
+            const runner = new SingleElementRunner('#login-btn');
+            runner.click().shouldNotBeVisible();
+            expect(runner._actionPayload.key).toBe('click');
+            const assertions = runner._assertions;
+            expect(assertions).toHaveLength(1);
+            expect(assertions[0].matcher).toBe('not.be.visible');
+        });
+    });
+    describe('MultiElementRunner - 6 Collection Receiver Assertions', () => {
+        it('should queue all 6 collection assertions', () => {
+            const runner = new MultiElementRunner('.product-item');
+            runner
+                .shouldHaveLength(4)
+                .shouldNotHaveLength(0)
+                .shouldHaveLengthGreaterThan(2)
+                .shouldHaveLengthLessThan(10)
+                .shouldBeEmpty()
+                .shouldNotBeEmpty();
+            const assertions = runner._assertions;
+            expect(assertions).toHaveLength(6);
+            expect(assertions[0]).toEqual({ matcher: 'have.length', args: [4] });
+            expect(assertions[1]).toEqual({ matcher: 'not.have.length', args: [0] });
+            expect(assertions[2]).toEqual({ matcher: 'have.length.greaterThan', args: [2] });
+            expect(assertions[3]).toEqual({ matcher: 'have.length.lessThan', args: [10] });
+            expect(assertions[4]).toEqual({ matcher: 'be.empty', args: [] });
+            expect(assertions[5]).toEqual({ matcher: 'not.be.empty', args: [] });
+        });
+        it('should navigate collection items with first, last, eq', () => {
+            const collection = Spectra.getAll('.list-item');
+            const first = collection.first();
+            const last = collection.last();
+            const second = collection.eq(1);
+            expect(first).toBeInstanceOf(SingleElementRunner);
+            expect(last).toBeInstanceOf(SingleElementRunner);
+            expect(second).toBeInstanceOf(SingleElementRunner);
+        });
+    });
+    describe('Spectra.browser - Context Assertions & Utilities', () => {
+        it('should expose all browser assertions and utilities', () => {
+            expect(typeof Spectra.browser.shouldHaveUrl).toBe('function');
+            expect(typeof Spectra.browser.shouldContainUrl).toBe('function');
+            expect(typeof Spectra.browser.shouldHaveTitle).toBe('function');
+            expect(typeof Spectra.browser.shouldContainTitle).toBe('function');
+            expect(typeof Spectra.browser.shouldBePageLoaded).toBe('function');
+            expect(typeof Spectra.browser.shouldHaveNoConsoleErrors).toBe('function');
+            expect(typeof Spectra.browser.clearCookies).toBe('function');
+            expect(typeof Spectra.browser.clearLocalStorage).toBe('function');
+        });
+    });
+    describe('Prototypes & Promise Unwrapping', () => {
+        it('should install receiver methods on mock WebdriverIO browser', () => {
+            const addedCommands = {};
+            const mockBrowser = {
+                addCommand: vi.fn((name, fn) => {
+                    addedCommands[name] = fn;
+                }),
+            };
+            installPrototypes(mockBrowser);
+            expect(mockBrowser.addCommand).toHaveBeenCalled();
+            expect(addedCommands['should']).toBeUndefined();
+            expect(addedCommands['shouldBeVisible']).toBeDefined();
+            expect(addedCommands['shouldHaveText']).toBeDefined();
+            expect(addedCommands['shouldHaveLength']).toBeUndefined(); // collection only
+            expect(addedCommands['shouldHaveUrl']).toBeDefined();
+            // Check Promise.prototype has shouldBeVisible attached
+            expect(typeof Promise.prototype.shouldBeVisible).toBe('function');
+        });
+    });
+});

package/dist/index.d.ts

@@ -2,25 +2,7 @@
  * @packageDocumentation
  * # @testspectra/matchers
  *
- * Cross-platform action commands, fluent runners, and callable assertion matchers for TestSpectra.
- *
- * ## Features:
- * - **`Spectra`**: Unified automation API (`Spectra.get()`, `Spectra.getAll()`, `Spectra.click()`, `Spectra.type()`, etc.)
- * - **`SingleElementRunner`**: Fluent interaction & assertion runner for single element targets
- * - **`MultiElementRunner`**: Fluent assertion & traversal runner for multi-element collections
- * - **Callable Matchers**: Ambient prototypes for WebdriverIO Element & Browser (`.shouldBeVisible()`, `.shouldHaveText()`, etc.)
- *
- * @example
- * ```ts
- * import { Spectra } from "@testspectra/matchers";
- *
- * await Spectra.get("#login-btn").click().should("not.be.visible");
- * await Spectra.getAll(".list-item").should("have.length.greaterThan", 0);
- * ```
+ * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
-export * from "./types.js";
-export * from "./matchers.js";
-export * from "./runner/single.js";
-export * from "./runner/collection.js";
-export * from "./spectra.js";
-export * from "./proto.js";
+export * from './types.js';
+export * from './proto.js';

package/dist/index.js

@@ -2,25 +2,7 @@
  * @packageDocumentation
  * # @testspectra/matchers
  *
- * Cross-platform action commands, fluent runners, and callable assertion matchers for TestSpectra.
- *
- * ## Features:
- * - **`Spectra`**: Unified automation API (`Spectra.get()`, `Spectra.getAll()`, `Spectra.click()`, `Spectra.type()`, etc.)
- * - **`SingleElementRunner`**: Fluent interaction & assertion runner for single element targets
- * - **`MultiElementRunner`**: Fluent assertion & traversal runner for multi-element collections
- * - **Callable Matchers**: Ambient prototypes for WebdriverIO Element & Browser (`.shouldBeVisible()`, `.shouldHaveText()`, etc.)
- *
- * @example
- * ```ts
- * import { Spectra } from "@testspectra/matchers";
- *
- * await Spectra.get("#login-btn").click().should("not.be.visible");
- * await Spectra.getAll(".list-item").should("have.length.greaterThan", 0);
- * ```
+ * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
-export * from "./types.js";
-export * from "./matchers.js";
-export * from "./runner/single.js";
-export * from "./runner/collection.js";
-export * from "./spectra.js";
-export * from "./proto.js";
+export * from './types.js';
+export * from './proto.js';

package/dist/intercept/cdp-handler.d.ts

@@ -0,0 +1,22 @@
+import { MockHandle } from './mock-handle.js';
+import { InterceptedRequest, InterceptRule } from './types.js';
+export declare class CdpHandler {
+    private static cdpEnabled;
+    private static cdpPromise;
+    /**
+     * Ensures Chrome DevTools Protocol Fetch domain is enabled and listening.
+     * Awaits confirmation from CDP Fetch.enable before resolving.
+     */
+    static enableFetchDomain(): Promise<void>;
+    /**
+     * Atomically registers rule and awaits CDP Fetch.enable before returning the handle.
+     */
+    static registerRule(rule: InterceptRule): Promise<MockHandle>;
+    /**
+     * Dispatches an intercepted request through the MockRegistry, records metrics, and returns fulfillment.
+     */
+    static dispatchIncomingRequest(req: InterceptedRequest): Promise<{
+        aborted?: string;
+        response?: any;
+    }>;
+}

package/dist/intercept/cdp-handler.js

@@ -0,0 +1,123 @@
+import { MockRegistry } from './mock-registry.js';
+export class CdpHandler {
+    static cdpEnabled = false;
+    static cdpPromise = null;
+    /**
+     * Ensures Chrome DevTools Protocol Fetch domain is enabled and listening.
+     * Awaits confirmation from CDP Fetch.enable before resolving.
+     */
+    static async enableFetchDomain() {
+        if (this.cdpEnabled)
+            return;
+        if (this.cdpPromise)
+            return this.cdpPromise;
+        this.cdpPromise = (async () => {
+            // Check if running inside real WebdriverIO browser with CDP
+            const b = globalThis.browser;
+            if (b && typeof b.getPuppeteer === 'function') {
+                try {
+                    const puppeteer = await b.getPuppeteer();
+                    const pages = await puppeteer.pages();
+                    const page = pages[0];
+                    if (page) {
+                        const client = await page.target().createCDPSession();
+                        await client.send('Fetch.enable', {
+                            patterns: [{ urlPattern: '*' }],
+                        });
+                        client.on('Fetch.requestPaused', async (event) => {
+                            const req = {
+                                id: event.requestId,
+                                url: event.request.url,
+                                method: event.request.method,
+                                headers: event.request.headers,
+                                body: event.request.postData,
+                                timestamp: Date.now(),
+                            };
+                            const fulfill = await CdpHandler.dispatchIncomingRequest(req);
+                            if (fulfill.aborted) {
+                                await client.send('Fetch.failRequest', {
+                                    requestId: event.requestId,
+                                    errorReason: fulfill.aborted,
+                                });
+                            }
+                            else if (fulfill.response) {
+                                const bodyStr = typeof fulfill.response.body === 'object'
+                                    ? JSON.stringify(fulfill.response.body)
+                                    : String(fulfill.response.body || '');
+                                const base64Body = Buffer.from(bodyStr).toString('base64');
+                                const responseHeaders = Object.entries(fulfill.response.headers || {}).map(([name, value]) => ({
+                                    name,
+                                    value,
+                                }));
+                                await client.send('Fetch.fulfillRequest', {
+                                    requestId: event.requestId,
+                                    responseCode: fulfill.response.status || 200,
+                                    responseHeaders,
+                                    body: base64Body,
+                                });
+                            }
+                            else {
+                                await client.send('Fetch.continueRequest', {
+                                    requestId: event.requestId,
+                                });
+                            }
+                        });
+                    }
+                }
+                catch {
+                    // Graceful fallback in non-CDP environments (e.g. mobile Appium or test runners)
+                }
+            }
+            this.cdpEnabled = true;
+        })();
+        return this.cdpPromise;
+    }
+    /**
+     * Atomically registers rule and awaits CDP Fetch.enable before returning the handle.
+     */
+    static async registerRule(rule) {
+        await this.enableFetchDomain();
+        const registry = MockRegistry.getInstance();
+        return registry.register(rule);
+    }
+    /**
+     * Dispatches an intercepted request through the MockRegistry, records metrics, and returns fulfillment.
+     */
+    static async dispatchIncomingRequest(req) {
+        const startTime = Date.now();
+        const registry = MockRegistry.getInstance();
+        const handle = registry.findMatchingHandle(req.method, req.url);
+        let result = {};
+        if (handle) {
+            const fulfill = await handle.matchAndFulfill(req);
+            result = fulfill;
+        }
+        // Record network traffic
+        const duration = Date.now() - startTime;
+        const status = result.aborted ? 0 : result.response?.status || 200;
+        const statusText = result.aborted ? result.aborted : status === 200 ? 'OK' : 'Mocked';
+        const recorded = {
+            id: req.id,
+            url: req.url,
+            method: req.method,
+            status,
+            statusText,
+            resourceType: 'fetch',
+            requestHeaders: req.headers,
+            responseHeaders: result.response?.headers,
+            requestBody: req.body,
+            responseBody: result.response?.body,
+            timing: {
+                dns: 1.0,
+                tcp: 1.5,
+                ssl: 2.0,
+                ttfb: duration,
+                download: 0.5,
+                total: duration + 5.0,
+            },
+            transferSize: result.response?.body ? JSON.stringify(result.response.body).length : 0,
+        };
+        registry.recordResource(recorded);
+        return result;
+    }
+}

package/dist/intercept/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './mock-handle.js';
+export * from './mock-registry.js';
+export * from './cdp-handler.js';

package/dist/intercept/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './mock-handle.js';
+export * from './mock-registry.js';
+export * from './cdp-handler.js';

package/dist/intercept/mock-handle.d.ts

@@ -0,0 +1,49 @@
+import { InterceptedRequest, InterceptRule, MockResponse, NetworkAbortReason } from './types.js';
+export interface FulfillResult {
+    aborted?: NetworkAbortReason;
+    response?: MockResponse;
+}
+export declare class MockHandle {
+    readonly rule: InterceptRule;
+    private onceQueue;
+    private defaultResponse;
+    private abortReason;
+    private interceptedCalls;
+    private waitingCallers;
+    constructor(rule: InterceptRule);
+    /**
+     * Updates the default mock response for all subsequent matching requests.
+     */
+    respondWith(response: MockResponse): this;
+    /**
+     * Queues a one-time mock response for the next matching request (FIFO queue for polling/retries).
+     */
+    respondOnce(response: MockResponse): this;
+    /**
+     * Simulates a network failure or connection abort.
+     */
+    abort(errorCode?: NetworkAbortReason): this;
+    /**
+     * Total matching requests intercepted so far.
+     */
+    get callCount(): number;
+    /**
+     * Historical array of intercepted requests.
+     */
+    get calls(): InterceptedRequest[];
+    /**
+     * Awaits until a matching request arrives or times out.
+     */
+    waitForCall(options?: {
+        timeout?: number;
+        count?: number;
+    }): Promise<InterceptedRequest>;
+    /**
+     * Internal fulfillment method called when a request matches this rule.
+     */
+    matchAndFulfill(req: InterceptedRequest): Promise<FulfillResult>;
+    /**
+     * Resets local state and queued responses.
+     */
+    clear(): void;
+}