browser-debugger-cli 0.0.1-alpha.0 → 0.1.0-alpha.1

package/dist/__testutils__/FakeClock.d.ts

@@ -0,0 +1,67 @@
+/**
+ * FakeClock - Deterministic timer control for tests
+ *
+ * Simulates setTimeout/setInterval and queueMicrotask to enable
+ * deterministic testing of async code with timeouts.
+ *
+ * Key features:
+ * - Separate macrotask (timers) and microtask (promise callbacks) queues
+ * - Loop-based flush() drains microtasks until completely empty
+ * - tick() advances timers without draining microtasks
+ * - tickAsync() advances timers AND drains microtasks (for timeout tests)
+ */
+export declare class FakeClock {
+    private currentTime;
+    private nextTimerId;
+    private timerTasks;
+    private microtaskQueue;
+    /**
+     * Get current fake time in milliseconds
+     */
+    now(): number;
+    /**
+     * Schedule a one-time timer (setTimeout)
+     */
+    setTimeout(callback: () => void, delay: number): NodeJS.Timeout;
+    /**
+     * Schedule a repeating timer (setInterval)
+     */
+    setInterval(callback: () => void, interval: number): NodeJS.Timeout;
+    /**
+     * Cancel a timer (clearTimeout/clearInterval)
+     */
+    clearTimer(id: NodeJS.Timeout): void;
+    /**
+     * Queue a microtask (queueMicrotask, promise callbacks)
+     */
+    queueMicrotask(callback: () => void): void;
+    /**
+     * Advance time and execute all timers that should fire
+     * Does NOT drain microtasks - use flush() or tickAsync() for that
+     */
+    tick(ms: number): void;
+    /**
+     * Drain the microtask queue completely
+     * CRITICAL: Loops until queue is empty to handle cascading microtasks
+     * (e.g., rejection handler that schedules another microtask)
+     */
+    flush(): void;
+    /**
+     * Advance time AND drain all microtasks
+     * Use this for timeout tests where rejections propagate via microtasks
+     */
+    tickAsync(ms: number): Promise<void>;
+    /**
+     * Get number of pending timers
+     */
+    getPendingTimers(): number;
+    /**
+     * Get number of queued microtasks
+     */
+    getPendingMicrotasks(): number;
+    /**
+     * Reset clock to initial state
+     */
+    reset(): void;
+}
+//# sourceMappingURL=FakeClock.d.ts.map

package/dist/__testutils__/FakeClock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeClock.d.ts","sourceRoot":"","sources":["../../src/__testutils__/FakeClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,qBAAa,SAAS;IACpB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,cAAc,CAAyB;IAE/C;;OAEG;IACH,GAAG,IAAI,MAAM;IAIb;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO;IAW/D;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO;IAYnE;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI;IAIpC;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAI1C;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAuBtB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAUb;;;OAGG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAI9B;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd"}

package/dist/__testutils__/FakeClock.js

@@ -0,0 +1,132 @@
+/**
+ * FakeClock - Deterministic timer control for tests
+ *
+ * Simulates setTimeout/setInterval and queueMicrotask to enable
+ * deterministic testing of async code with timeouts.
+ *
+ * Key features:
+ * - Separate macrotask (timers) and microtask (promise callbacks) queues
+ * - Loop-based flush() drains microtasks until completely empty
+ * - tick() advances timers without draining microtasks
+ * - tickAsync() advances timers AND drains microtasks (for timeout tests)
+ */
+export class FakeClock {
+    currentTime = 0;
+    nextTimerId = 1;
+    timerTasks = new Map();
+    microtaskQueue = [];
+    /**
+     * Get current fake time in milliseconds
+     */
+    now() {
+        return this.currentTime;
+    }
+    /**
+     * Schedule a one-time timer (setTimeout)
+     */
+    setTimeout(callback, delay) {
+        const id = this.nextTimerId++;
+        this.timerTasks.set(id, {
+            id,
+            callback,
+            triggerAt: this.currentTime + delay,
+            type: 'timeout',
+        });
+        return id;
+    }
+    /**
+     * Schedule a repeating timer (setInterval)
+     */
+    setInterval(callback, interval) {
+        const id = this.nextTimerId++;
+        this.timerTasks.set(id, {
+            id,
+            callback,
+            triggerAt: this.currentTime + interval,
+            interval,
+            type: 'interval',
+        });
+        return id;
+    }
+    /**
+     * Cancel a timer (clearTimeout/clearInterval)
+     */
+    clearTimer(id) {
+        this.timerTasks.delete(id);
+    }
+    /**
+     * Queue a microtask (queueMicrotask, promise callbacks)
+     */
+    queueMicrotask(callback) {
+        this.microtaskQueue.push(callback);
+    }
+    /**
+     * Advance time and execute all timers that should fire
+     * Does NOT drain microtasks - use flush() or tickAsync() for that
+     */
+    tick(ms) {
+        this.currentTime += ms;
+        // Find and execute all timers that should fire
+        const tasksToFire = Array.from(this.timerTasks.values())
+            .filter((task) => task.triggerAt <= this.currentTime)
+            .sort((a, b) => a.triggerAt - b.triggerAt);
+        for (const task of tasksToFire) {
+            // Remove one-time timers
+            if (task.type === 'timeout') {
+                this.timerTasks.delete(task.id);
+            }
+            // Reschedule intervals
+            else if (task.interval !== undefined) {
+                task.triggerAt = this.currentTime + task.interval;
+            }
+            // Execute callback
+            task.callback();
+        }
+    }
+    /**
+     * Drain the microtask queue completely
+     * CRITICAL: Loops until queue is empty to handle cascading microtasks
+     * (e.g., rejection handler that schedules another microtask)
+     */
+    flush() {
+        // Loop-based drainage handles cascading microtasks
+        while (this.microtaskQueue.length > 0) {
+            const task = this.microtaskQueue.shift();
+            if (task) {
+                task(); // May enqueue more microtasks - loop continues
+            }
+        }
+    }
+    /**
+     * Advance time AND drain all microtasks
+     * Use this for timeout tests where rejections propagate via microtasks
+     */
+    async tickAsync(ms) {
+        this.tick(ms);
+        this.flush();
+        // Allow Node's event loop to process any actual promises
+        await Promise.resolve();
+    }
+    /**
+     * Get number of pending timers
+     */
+    getPendingTimers() {
+        return this.timerTasks.size;
+    }
+    /**
+     * Get number of queued microtasks
+     */
+    getPendingMicrotasks() {
+        return this.microtaskQueue.length;
+    }
+    /**
+     * Reset clock to initial state
+     */
+    reset() {
+        this.currentTime = 0;
+        this.nextTimerId = 1;
+        this.timerTasks.clear();
+        this.microtaskQueue = [];
+    }
+}
+//# sourceMappingURL=FakeClock.js.map

package/dist/__testutils__/FakeClock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeClock.js","sourceRoot":"","sources":["../../src/__testutils__/FakeClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,MAAM,OAAO,SAAS;IACZ,WAAW,GAAG,CAAC,CAAC;IAChB,WAAW,GAAG,CAAC,CAAC;IAChB,UAAU,GAA2B,IAAI,GAAG,EAAE,CAAC;IAC/C,cAAc,GAAsB,EAAE,CAAC;IAE/C;;OAEG;IACH,GAAG;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,QAAoB,EAAE,KAAa;QAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC9B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE;YACtB,EAAE;YACF,QAAQ;YACR,SAAS,EAAE,IAAI,CAAC,WAAW,GAAG,KAAK;YACnC,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,OAAO,EAA+B,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,QAAoB,EAAE,QAAgB;QAChD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC9B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE;YACtB,EAAE;YACF,QAAQ;YACR,SAAS,EAAE,IAAI,CAAC,WAAW,GAAG,QAAQ;YACtC,QAAQ;YACR,IAAI,EAAE,UAAU;SACjB,CAAC,CAAC;QACH,OAAO,EAA+B,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,EAAkB;QAC3B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAuB,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,QAAoB;QACjC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,EAAU;QACb,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;QAEvB,+CAA+C;QAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;aACrD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,WAAW,CAAC;aACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;QAE7C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,yBAAyB;YACzB,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClC,CAAC;YACD,uBAAuB;iBAClB,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACrC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC;YACpD,CAAC;YAED,mBAAmB;YACnB,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,mDAAmD;QACnD,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;YACzC,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,EAAE,CAAC,CAAC,+CAA+C;YACzD,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,EAAU;QACxB,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,yDAAyD;QACzD,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/__testutils__/FakeWebSocket.d.ts

@@ -0,0 +1,106 @@
+/**
+ * FakeWebSocket - Complete WebSocket boundary fake for testing
+ *
+ * Mimics the `ws` library API to enable contract testing of CDPConnection
+ * without network I/O.
+ *
+ * Key features:
+ * - Full ws API compatibility (readyState, ping, pong, send, close, terminate)
+ * - Event emitters (open, message, close, error, ping, pong)
+ * - Test control methods (simulate*) for driving state from tests
+ * - Defensive copies in verification methods (getSentMessages) prevent mutation
+ */
+import { EventEmitter } from 'node:events';
+export declare const CONNECTING = 0;
+export declare const OPEN = 1;
+export declare const CLOSING = 2;
+export declare const CLOSED = 3;
+type ReadyState = typeof CONNECTING | typeof OPEN | typeof CLOSING | typeof CLOSED;
+export declare class FakeWebSocket extends EventEmitter {
+    readyState: ReadyState;
+    private sentMessages;
+    private pingSentCount;
+    private pongSentCount;
+    private closeCode;
+    private closeReason;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    constructor();
+    /**
+     * ws API - Send a message
+     * Throws if connection is not OPEN
+     */
+    send(data: string, callback?: (err?: Error) => void): void;
+    /**
+     * ws API - Send a ping frame
+     */
+    ping(callback?: (err?: Error) => void): void;
+    /**
+     * ws API - Send a pong frame (usually in response to ping)
+     */
+    pong(callback?: (err?: Error) => void): void;
+    /**
+     * ws API - Close connection gracefully
+     * Transitions: OPEN \> CLOSING \> CLOSED
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * ws API - Forceful close without handshake
+     * Immediately transitions to CLOSED
+     */
+    terminate(): void;
+    /**
+     * TEST CONTROL - Simulate connection open
+     * Transitions: CONNECTING \> OPEN, emits 'open'
+     */
+    simulateOpen(): void;
+    /**
+     * TEST CONTROL - Simulate receiving a message
+     * Only valid in OPEN state
+     */
+    simulateMessage(data: string | Buffer): void;
+    /**
+     * TEST CONTROL - Simulate connection close
+     * Transitions to CLOSED and emits 'close'
+     */
+    simulateClose(code: number, reason: string): void;
+    /**
+     * TEST CONTROL - Simulate connection error
+     * Emits 'error' event
+     */
+    simulateError(error: Error): void;
+    /**
+     * TEST CONTROL - Simulate receiving a pong frame
+     * Emits 'pong' event (for keepalive tests)
+     */
+    simulatePong(data?: Buffer): void;
+    /**
+     * VERIFICATION - Get sent messages (defensive copy)
+     * Returns shallow copy to prevent accidental mutation between assertions
+     */
+    getSentMessages(): string[];
+    /**
+     * VERIFICATION - Get number of pings sent
+     */
+    getPingSent(): number;
+    /**
+     * VERIFICATION - Get number of pongs sent
+     */
+    getPongSent(): number;
+    /**
+     * VERIFICATION - Get close code (if closed)
+     */
+    getCloseCode(): number | null;
+    /**
+     * VERIFICATION - Get close reason (if closed)
+     */
+    getCloseReason(): string | null;
+    /**
+     * TEST CONTROL - Reset to initial state
+     */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=FakeWebSocket.d.ts.map

package/dist/__testutils__/FakeWebSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeWebSocket.d.ts","sourceRoot":"","sources":["../../src/__testutils__/FakeWebSocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,IAAI,IAAI,CAAC;AACtB,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,MAAM,IAAI,CAAC;AAExB,KAAK,UAAU,GAAG,OAAO,UAAU,GAAG,OAAO,IAAI,GAAG,OAAO,OAAO,GAAG,OAAO,MAAM,CAAC;AAEnF,qBAAa,aAAc,SAAQ,YAAY;IAEtC,UAAU,EAAE,UAAU,CAAc;IAG3C,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAuB;IAG1C,MAAM,CAAC,QAAQ,CAAC,UAAU,KAAc;IACxC,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAQ;IAC5B,MAAM,CAAC,QAAQ,CAAC,OAAO,KAAW;IAClC,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAU;;IAMhC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAiB1D;;OAEG;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAgB5C;;OAEG;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAe5C;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAe3C;;;OAGG;IACH,SAAS,IAAI,IAAI;IAWjB;;;OAGG;IACH,YAAY,IAAI,IAAI;IASpB;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQ5C;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWjD;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIjC;;;OAGG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAQjC;;;OAGG;IACH,eAAe,IAAI,MAAM,EAAE;IAI3B;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,KAAK,IAAI,IAAI;CASd"}

package/dist/__testutils__/FakeWebSocket.js

@@ -0,0 +1,213 @@
+/**
+ * FakeWebSocket - Complete WebSocket boundary fake for testing
+ *
+ * Mimics the `ws` library API to enable contract testing of CDPConnection
+ * without network I/O.
+ *
+ * Key features:
+ * - Full ws API compatibility (readyState, ping, pong, send, close, terminate)
+ * - Event emitters (open, message, close, error, ping, pong)
+ * - Test control methods (simulate*) for driving state from tests
+ * - Defensive copies in verification methods (getSentMessages) prevent mutation
+ */
+import { EventEmitter } from 'node:events';
+// ws library readyState constants
+export const CONNECTING = 0;
+export const OPEN = 1;
+export const CLOSING = 2;
+export const CLOSED = 3;
+export class FakeWebSocket extends EventEmitter {
+    // ws API - readyState property
+    readyState = CONNECTING;
+    // Internal state
+    sentMessages = [];
+    pingSentCount = 0;
+    pongSentCount = 0;
+    closeCode = null;
+    closeReason = null;
+    // ws API constants
+    static CONNECTING = CONNECTING;
+    static OPEN = OPEN;
+    static CLOSING = CLOSING;
+    static CLOSED = CLOSED;
+    constructor() {
+        super();
+    }
+    /**
+     * ws API - Send a message
+     * Throws if connection is not OPEN
+     */
+    send(data, callback) {
+        if (this.readyState !== OPEN) {
+            const err = new Error('WebSocket is not open: readyState ' + this.readyState);
+            if (callback) {
+                callback(err);
+            }
+            else {
+                throw err;
+            }
+            return;
+        }
+        this.sentMessages.push(data);
+        if (callback) {
+            callback();
+        }
+    }
+    /**
+     * ws API - Send a ping frame
+     */
+    ping(callback) {
+        if (this.readyState !== OPEN) {
+            const err = new Error('WebSocket is not open');
+            if (callback) {
+                callback(err);
+            }
+            return;
+        }
+        this.pingSentCount++;
+        this.emit('ping');
+        if (callback) {
+            callback();
+        }
+    }
+    /**
+     * ws API - Send a pong frame (usually in response to ping)
+     */
+    pong(callback) {
+        if (this.readyState !== OPEN) {
+            const err = new Error('WebSocket is not open');
+            if (callback) {
+                callback(err);
+            }
+            return;
+        }
+        this.pongSentCount++;
+        if (callback) {
+            callback();
+        }
+    }
+    /**
+     * ws API - Close connection gracefully
+     * Transitions: OPEN \> CLOSING \> CLOSED
+     */
+    close(code, reason) {
+        if (this.readyState === CLOSED || this.readyState === CLOSING) {
+            return;
+        }
+        this.readyState = CLOSING;
+        this.closeCode = code ?? null;
+        this.closeReason = reason ?? null;
+        // Immediately transition to CLOSED and emit close event
+        // In real ws, there's a handshake, but for tests we can be immediate
+        this.readyState = CLOSED;
+        this.emit('close', code ?? 1000, reason ?? '');
+    }
+    /**
+     * ws API - Forceful close without handshake
+     * Immediately transitions to CLOSED
+     */
+    terminate() {
+        if (this.readyState === CLOSED) {
+            return;
+        }
+        this.readyState = CLOSED;
+        this.closeCode = 1006;
+        this.closeReason = 'Connection terminated';
+        this.emit('close', 1006, 'Connection terminated');
+    }
+    /**
+     * TEST CONTROL - Simulate connection open
+     * Transitions: CONNECTING \> OPEN, emits 'open'
+     */
+    simulateOpen() {
+        if (this.readyState !== CONNECTING) {
+            throw new Error('Can only open from CONNECTING state');
+        }
+        this.readyState = OPEN;
+        this.emit('open');
+    }
+    /**
+     * TEST CONTROL - Simulate receiving a message
+     * Only valid in OPEN state
+     */
+    simulateMessage(data) {
+        if (this.readyState !== OPEN) {
+            throw new Error('Cannot receive message when not OPEN');
+        }
+        this.emit('message', data);
+    }
+    /**
+     * TEST CONTROL - Simulate connection close
+     * Transitions to CLOSED and emits 'close'
+     */
+    simulateClose(code, reason) {
+        if (this.readyState === CLOSED) {
+            return;
+        }
+        this.readyState = CLOSED;
+        this.closeCode = code;
+        this.closeReason = reason;
+        this.emit('close', code, reason);
+    }
+    /**
+     * TEST CONTROL - Simulate connection error
+     * Emits 'error' event
+     */
+    simulateError(error) {
+        this.emit('error', error);
+    }
+    /**
+     * TEST CONTROL - Simulate receiving a pong frame
+     * Emits 'pong' event (for keepalive tests)
+     */
+    simulatePong(data) {
+        if (this.readyState !== OPEN) {
+            throw new Error('Cannot receive pong when not OPEN');
+        }
+        this.emit('pong', data);
+    }
+    /**
+     * VERIFICATION - Get sent messages (defensive copy)
+     * Returns shallow copy to prevent accidental mutation between assertions
+     */
+    getSentMessages() {
+        return [...this.sentMessages];
+    }
+    /**
+     * VERIFICATION - Get number of pings sent
+     */
+    getPingSent() {
+        return this.pingSentCount;
+    }
+    /**
+     * VERIFICATION - Get number of pongs sent
+     */
+    getPongSent() {
+        return this.pongSentCount;
+    }
+    /**
+     * VERIFICATION - Get close code (if closed)
+     */
+    getCloseCode() {
+        return this.closeCode;
+    }
+    /**
+     * VERIFICATION - Get close reason (if closed)
+     */
+    getCloseReason() {
+        return this.closeReason;
+    }
+    /**
+     * TEST CONTROL - Reset to initial state
+     */
+    reset() {
+        this.readyState = CONNECTING;
+        this.sentMessages = [];
+        this.pingSentCount = 0;
+        this.pongSentCount = 0;
+        this.closeCode = null;
+        this.closeReason = null;
+        this.removeAllListeners();
+    }
+}
+//# sourceMappingURL=FakeWebSocket.js.map

package/dist/__testutils__/FakeWebSocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeWebSocket.js","sourceRoot":"","sources":["../../src/__testutils__/FakeWebSocket.ts"],"names":[],"mappings":"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"}

package/dist/__testutils__/assertions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * assertions - Custom assertion helpers for contract tests
+ *
+ * Provides ergonomic assertions for common test patterns.
+ */
+import type { CDPMessage } from '@/types.js';
+/**
+ * Poll a condition until it becomes true or timeout
+ * Useful for eventually-consistent assertions
+ *
+ * @example
+ * ```ts
+ * await assertEventually(() => ws.getSentMessages().length > 0, 1000);
+ * ```
+ */
+export declare function assertEventually(fn: () => boolean, timeoutMs: number, message?: string): Promise<void>;
+/**
+ * Assert deep equality for CDP messages
+ * Handles partial matching for convenience
+ */
+export declare function assertCDPMessage(actual: CDPMessage, expected: Partial<CDPMessage>): void;
+/**
+ * Assert that async function throws with specific pattern
+ * @example
+ * ```ts
+ * await assertThrowsAsync(
+ *   () => cdp.send('Invalid.method'),
+ *   /timeout/
+ * );
+ * ```
+ */
+export declare function assertThrowsAsync(fn: () => Promise<unknown>, pattern: RegExp | string, message?: string): Promise<void>;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/__testutils__/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../src/__testutils__/assertions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,OAAO,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAKxF;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC1B,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/__testutils__/assertions.js

@@ -0,0 +1,57 @@
+/**
+ * assertions - Custom assertion helpers for contract tests
+ *
+ * Provides ergonomic assertions for common test patterns.
+ */
+import assert from 'node:assert/strict';
+/**
+ * Poll a condition until it becomes true or timeout
+ * Useful for eventually-consistent assertions
+ *
+ * @example
+ * ```ts
+ * await assertEventually(() => ws.getSentMessages().length > 0, 1000);
+ * ```
+ */
+export async function assertEventually(fn, timeoutMs, message) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (fn()) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error(message ?? `Condition not met within ${timeoutMs}ms`);
+}
+/**
+ * Assert deep equality for CDP messages
+ * Handles partial matching for convenience
+ */
+export function assertCDPMessage(actual, expected) {
+    const actualRecord = actual;
+    for (const [key, value] of Object.entries(expected)) {
+        assert.deepEqual(actualRecord[key], value, `CDP message field '${key}' mismatch`);
+    }
+}
+/**
+ * Assert that async function throws with specific pattern
+ * @example
+ * ```ts
+ * await assertThrowsAsync(
+ *   () => cdp.send('Invalid.method'),
+ *   /timeout/
+ * );
+ * ```
+ */
+export async function assertThrowsAsync(fn, pattern, message) {
+    try {
+        await fn();
+        throw new Error(message ?? `Expected function to throw matching ${pattern}`);
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+        assert.match(errorMessage, regex, message);
+    }
+}
+//# sourceMappingURL=assertions.js.map

package/dist/__testutils__/assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.js","sourceRoot":"","sources":["../../src/__testutils__/assertions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAIxC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAiB,EACjB,SAAiB,EACjB,OAAgB;IAEhB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QACtC,IAAI,EAAE,EAAE,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,4BAA4B,SAAS,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB,EAAE,QAA6B;IAChF,MAAM,YAAY,GAAG,MAA4C,CAAC;IAClE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAA0B,EAC1B,OAAwB,EACxB,OAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,EAAE,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,uCAAuC,OAAO,EAAE,CAAC,CAAC;IAC/E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,YAAY,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtE,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1E,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/__testutils__/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Test utilities - Re-export all test helpers
+ *
+ * Single import point for all test utilities:
+ * ```ts
+ * import { FakeClock, FakeWebSocket, useFakeClock, ... } from '../__testutils__/index.js';
+ * ```
+ */
+export { FakeClock } from './FakeClock.js';
+export { FakeWebSocket, CONNECTING, OPEN, CLOSING, CLOSED } from './FakeWebSocket.js';
+export { useFakeClock, type ClockHelper } from './testClock.js';
+export { mockProcessAlive, restoreProcessAlive, isProcessMocked } from './testProcess.js';
+export { assertEventually, assertCDPMessage, assertThrowsAsync } from './assertions.js';
+export { createMockCDPMessage, createMockWebSocketUrl } from './testFixtures.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/__testutils__/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/__testutils__/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/__testutils__/index.js

@@ -0,0 +1,15 @@
+/**
+ * Test utilities - Re-export all test helpers
+ *
+ * Single import point for all test utilities:
+ * ```ts
+ * import { FakeClock, FakeWebSocket, useFakeClock, ... } from '../__testutils__/index.js';
+ * ```
+ */
+export { FakeClock } from './FakeClock.js';
+export { FakeWebSocket, CONNECTING, OPEN, CLOSING, CLOSED } from './FakeWebSocket.js';
+export { useFakeClock } from './testClock.js';
+export { mockProcessAlive, restoreProcessAlive, isProcessMocked } from './testProcess.js';
+export { assertEventually, assertCDPMessage, assertThrowsAsync } from './assertions.js';
+export { createMockCDPMessage, createMockWebSocketUrl } from './testFixtures.js';
+//# sourceMappingURL=index.js.map