browser-debugger-cli 0.6.0 → 0.6.1

package/dist/connection/__tests__/pageReadiness.contract.test.js

@@ -0,0 +1,382 @@
+/**
+ * Contract tests for page readiness detection
+ *
+ * Tests the contract: wait for load → network stable → DOM stable OR timeout
+ *
+ * Philosophy: Test the state machine behavior using a mock CDP connection.
+ * We don't test timing-sensitive behavior (exact ms), we test the sequence
+ * of operations and state transitions.
+ *
+ * These are contract tests because they validate the multi-phase readiness
+ * detection contract without caring about internal implementation.
+ */
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { waitForPageReady } from '../../connection/pageReadiness.js';
+describe('Page Readiness - Happy Path', () => {
+    test('waits through all three phases (load → network → DOM)', async () => {
+        const phases = [];
+        const mockCDP = createMockCDP({
+            onSend: (method) => {
+                phases.push(method);
+            },
+            loadEventAlreadyFired: false,
+            networkQuiet: true,
+            domStable: true,
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should enable Page and Network domains
+        assert.ok(phases.includes('Page.enable'), 'Should enable Page domain');
+        assert.ok(phases.includes('Network.enable'), 'Should enable Network domain');
+        // Contract: should check document.readyState
+        assert.ok(phases.some((p) => p.includes('Runtime.evaluate')), 'Should check document readiness');
+    });
+    test('handles page where load event already fired', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+        });
+        // Contract: should not wait for load event if already complete
+        await waitForPageReady(mockCDP);
+        // Should complete without error
+        assert.ok(true, 'Should handle already-loaded page');
+    });
+    test('proceeds when network stabilizes', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+        });
+        await waitForPageReady(mockCDP);
+        // Should complete network phase
+        assert.ok(true, 'Should proceed when network is stable');
+    });
+    test('proceeds when DOM stabilizes', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+        });
+        await waitForPageReady(mockCDP);
+        // Should complete DOM phase
+        assert.ok(true, 'Should proceed when DOM is stable');
+    });
+});
+describe('Page Readiness - Timeout Behavior', () => {
+    test('proceeds on timeout without throwing', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: false,
+            networkQuiet: false, // Never becomes quiet
+            domStable: false, // Never stabilizes
+            delayLoadEvent: true, // Delay to trigger timeout
+        });
+        // Contract: should NOT throw on timeout, should proceed anyway
+        await assert.doesNotReject(async () => {
+            await waitForPageReady(mockCDP, { maxWaitMs: 100 });
+        }, 'Should not throw on timeout');
+    });
+    test('respects custom maxWaitMs option', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: false,
+            networkQuiet: false,
+            domStable: false,
+            delayLoadEvent: true,
+        });
+        const start = Date.now();
+        await waitForPageReady(mockCDP, { maxWaitMs: 200 });
+        const duration = Date.now() - start;
+        // Should timeout around 200ms (with some tolerance for scheduling)
+        assert.ok(duration >= 150 && duration < 400, 'Should respect custom timeout');
+    });
+    test('uses default 5000ms timeout when not specified', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+        });
+        const start = Date.now();
+        await waitForPageReady(mockCDP); // No options
+        const duration = Date.now() - start;
+        // Should complete quickly when stable (not wait full 5s)
+        assert.ok(duration < 1000, 'Should not wait unnecessarily when page is ready');
+    });
+});
+describe('Page Readiness - Load Event Phase', () => {
+    test('waits for Page.loadEventFired when not already loaded', async () => {
+        let loadEventFired = false;
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: false,
+            networkQuiet: true,
+            domStable: true,
+            onEventRegistered: (event) => {
+                if (event === 'Page.loadEventFired') {
+                    // Simulate load event firing after a delay
+                    setTimeout(() => {
+                        loadEventFired = true;
+                        mockCDP.emit('Page.loadEventFired', {});
+                    }, 50);
+                }
+            },
+        });
+        await waitForPageReady(mockCDP, { maxWaitMs: 500 });
+        assert.ok(loadEventFired, 'Should wait for and receive load event');
+    });
+    test('skips waiting for load event when document.readyState is complete', async () => {
+        const events = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+            onEventRegistered: (event) => {
+                events.push(event);
+            },
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should not register for Page.loadEventFired if already complete
+        // (though it's okay if it does register and immediately continues)
+        assert.ok(true, 'Should handle pre-loaded page');
+    });
+    test('handles Runtime.evaluate errors gracefully', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: false,
+            networkQuiet: true,
+            domStable: true,
+            evaluateThrows: true,
+        });
+        // Contract: should proceed even if readyState check fails
+        await assert.doesNotReject(async () => {
+            await waitForPageReady(mockCDP, { maxWaitMs: 200 });
+        }, 'Should handle evaluate errors gracefully');
+    });
+});
+describe('Page Readiness - Network Stability Phase', () => {
+    test('detects network activity via requestWillBeSent events', async () => {
+        const events = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: false,
+            domStable: true,
+            onEventRegistered: (event) => {
+                events.push(event);
+            },
+        });
+        await waitForPageReady(mockCDP, { maxWaitMs: 200 });
+        // Contract: should listen for network events
+        assert.ok(events.includes('Network.requestWillBeSent'), 'Should listen for network requests');
+        assert.ok(events.includes('Network.loadingFinished'), 'Should listen for loading finished');
+        assert.ok(events.includes('Network.loadingFailed'), 'Should listen for loading failed');
+    });
+    test('tracks active requests (requestWillBeSent increases, responses decrease)', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: false,
+            domStable: true,
+            onEventRegistered: (event) => {
+                if (event === 'Network.requestWillBeSent') {
+                    // Simulate request/response cycle
+                    setTimeout(() => {
+                        mockCDP.emit('Network.requestWillBeSent', {});
+                        setTimeout(() => {
+                            mockCDP.emit('Network.loadingFinished', {});
+                        }, 50);
+                    }, 30);
+                }
+            },
+        });
+        await waitForPageReady(mockCDP, { maxWaitMs: 500 });
+        // Network phase should have completed
+        assert.ok(true, 'Should track network request lifecycle');
+    });
+    test('waits for 200ms of network idle before proceeding', async () => {
+        // This test verifies the threshold concept but not exact timing
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should wait for network stability (implementation uses 200ms threshold)
+        assert.ok(true, 'Should wait for network stability threshold');
+    });
+});
+describe('Page Readiness - DOM Stability Phase', () => {
+    test('injects MutationObserver into page', async () => {
+        const evaluations = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+            onSend: (method, params) => {
+                if (method === 'Runtime.evaluate' && params?.['expression']) {
+                    evaluations.push(params['expression']);
+                }
+            },
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should inject MutationObserver
+        const hasObserver = evaluations.some((expr) => expr.includes('MutationObserver'));
+        assert.ok(hasObserver, 'Should inject MutationObserver for DOM tracking');
+    });
+    test('cleans up MutationObserver after detection', async () => {
+        const evaluations = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+            onSend: (method, params) => {
+                if (method === 'Runtime.evaluate' && params?.['expression']) {
+                    evaluations.push(params['expression']);
+                }
+            },
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should clean up observer
+        const hasCleanup = evaluations.some((expr) => expr.includes('disconnect') || expr.includes('delete window.__bdg'));
+        assert.ok(hasCleanup, 'Should clean up MutationObserver after detection');
+    });
+    test('waits for 300ms of DOM stability before proceeding', async () => {
+        // This test verifies the threshold concept but not exact timing
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should wait for DOM stability threshold (implementation uses 300ms)
+        assert.ok(true, 'Should wait for DOM stability threshold');
+    });
+    test('handles missing document.body gracefully', async () => {
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+            evaluateThrows: true, // Simulate errors injecting observer
+        });
+        // Contract: should handle observer injection failures
+        await assert.doesNotReject(async () => {
+            await waitForPageReady(mockCDP, { maxWaitMs: 200 });
+        }, 'Should handle missing document.body');
+    });
+});
+describe('Page Readiness - Event Handler Cleanup', () => {
+    test('removes load event listener after phase completes', async () => {
+        const offCalls = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: false,
+            networkQuiet: true,
+            domStable: true,
+            onOff: (event) => {
+                offCalls.push(event);
+            },
+        });
+        // Fire load event to complete phase
+        setTimeout(() => mockCDP.emit('Page.loadEventFired', {}), 50);
+        await waitForPageReady(mockCDP, { maxWaitMs: 500 });
+        // Contract: should clean up load event listener
+        assert.ok(offCalls.includes('Page.loadEventFired'), 'Should remove Page.loadEventFired listener');
+    });
+    test('removes network event listeners after phase completes', async () => {
+        const offCalls = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: true,
+            networkQuiet: true,
+            domStable: true,
+            onOff: (event) => {
+                offCalls.push(event);
+            },
+        });
+        await waitForPageReady(mockCDP);
+        // Contract: should clean up all network listeners
+        assert.ok(offCalls.includes('Network.requestWillBeSent'), 'Should remove requestWillBeSent listener');
+        assert.ok(offCalls.includes('Network.loadingFinished'), 'Should remove loadingFinished listener');
+        assert.ok(offCalls.includes('Network.loadingFailed'), 'Should remove loadingFailed listener');
+    });
+    test('cleans up even when timeout occurs', async () => {
+        const offCalls = [];
+        const mockCDP = createMockCDP({
+            loadEventAlreadyFired: false,
+            networkQuiet: false,
+            domStable: false,
+            delayLoadEvent: true,
+            onOff: (event) => {
+                offCalls.push(event);
+            },
+        });
+        await waitForPageReady(mockCDP, { maxWaitMs: 100 });
+        // Contract: should clean up even on timeout
+        assert.ok(offCalls.length > 0, 'Should clean up listeners even on timeout');
+    });
+});
+/**
+ * Create a mock CDPConnection for testing page readiness
+ */
+function createMockCDP(options = {}) {
+    const { loadEventAlreadyFired = false, domStable = true, delayLoadEvent = false, evaluateThrows = false, onSend, onEventRegistered, onOff, } = options;
+    const handlers = new Map();
+    let handlerId = 0;
+    const mock = {
+        send(method, params) {
+            onSend?.(method, params);
+            if (method === 'Page.enable' || method === 'Network.enable') {
+                return Promise.resolve({});
+            }
+            if (method === 'Runtime.evaluate') {
+                if (evaluateThrows) {
+                    throw new Error('Evaluation failed');
+                }
+                const expression = params?.['expression'];
+                // Mock document.readyState check
+                if (expression?.includes('document.readyState')) {
+                    return Promise.resolve({
+                        result: {
+                            value: loadEventAlreadyFired ? 'complete' : 'loading',
+                        },
+                    });
+                }
+                // Mock MutationObserver injection
+                if (expression?.includes('MutationObserver')) {
+                    return Promise.resolve({ result: {} });
+                }
+                // Mock DOM stability check
+                if (expression?.includes('__bdg_lastMutation')) {
+                    const timeSinceLastMutation = domStable ? 500 : 0; // 500ms > 300ms threshold
+                    return Promise.resolve({
+                        result: {
+                            value: timeSinceLastMutation,
+                        },
+                    });
+                }
+                return Promise.resolve({ result: {} });
+            }
+            return Promise.resolve({});
+        },
+        on(event, handler) {
+            onEventRegistered?.(event);
+            if (!handlers.has(event)) {
+                handlers.set(event, new Map());
+            }
+            const id = handlerId++;
+            handlers.get(event)?.set(id, handler);
+            // Auto-fire load event if configured
+            if (event === 'Page.loadEventFired' && !delayLoadEvent) {
+                setTimeout(() => {
+                    handler({});
+                }, 10);
+            }
+            return () => this.off(event, id);
+        },
+        off(event, id) {
+            onOff?.(event);
+            handlers.get(event)?.delete(id);
+        },
+        emit(event, params) {
+            const eventHandlers = handlers.get(event);
+            if (eventHandlers) {
+                eventHandlers.forEach((handler) => handler(params));
+            }
+        },
+    };
+    return mock;
+}
+//# sourceMappingURL=pageReadiness.contract.test.js.map

package/dist/connection/__tests__/pageReadiness.contract.test.js.map

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

package/dist/connection/__tests__/portReservation.contract.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Contract tests for port reservation
+ *
+ * Tests the contract: reserve port atomically OR throw ChromeLaunchError
+ *
+ * Philosophy: Test with real network sockets to validate actual behavior.
+ * Port reservation is an I/O operation that must work correctly in production,
+ * so we use real sockets rather than mocks.
+ *
+ * These are contract tests (not unit tests) because they test the contract
+ * between reservePort() and the Node.js net module.
+ */
+export {};
+//# sourceMappingURL=portReservation.contract.test.d.ts.map

package/dist/connection/__tests__/portReservation.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portReservation.contract.test.d.ts","sourceRoot":"","sources":["../../../src/connection/__tests__/portReservation.contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/connection/__tests__/portReservation.contract.test.js

@@ -0,0 +1,250 @@
+/**
+ * Contract tests for port reservation
+ *
+ * Tests the contract: reserve port atomically OR throw ChromeLaunchError
+ *
+ * Philosophy: Test with real network sockets to validate actual behavior.
+ * Port reservation is an I/O operation that must work correctly in production,
+ * so we use real sockets rather than mocks.
+ *
+ * These are contract tests (not unit tests) because they test the contract
+ * between reservePort() and the Node.js net module.
+ */
+import * as net from 'net';
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { ChromeLaunchError } from '../../connection/errors.js';
+import { reservePort } from '../../connection/portReservation.js';
+describe('Port Reservation - Success Cases', () => {
+    test('successfully reserves an available port', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        try {
+            // Contract: reservation should have release function
+            assert.ok(typeof reservation.release === 'function', 'Should return reservation with release()');
+        }
+        finally {
+            reservation.release();
+        }
+    });
+    test('release() frees the port for reuse', async () => {
+        const port = await findAvailablePort();
+        const reservation1 = await reservePort(port);
+        reservation1.release();
+        // Contract: after release, port should be available again
+        const reservation2 = await reservePort(port);
+        reservation2.release();
+        // If we got here without error, port was successfully reused
+        assert.ok(true, 'Port should be available after release');
+    });
+    test('can reserve multiple different ports simultaneously', async () => {
+        const port1 = await findAvailablePort();
+        const port2 = await findAvailablePort(port1 + 1);
+        const reservation1 = await reservePort(port1);
+        const reservation2 = await reservePort(port2);
+        try {
+            assert.ok(reservation1, 'First reservation should succeed');
+            assert.ok(reservation2, 'Second reservation should succeed');
+        }
+        finally {
+            reservation1.release();
+            reservation2.release();
+        }
+    });
+    test('release() can be called immediately after reservation', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        reservation.release(); // Immediate release
+        // Should not throw
+        assert.ok(true, 'Immediate release should be safe');
+    });
+});
+describe('Port Reservation - Failure Cases', () => {
+    test('throws ChromeLaunchError when port is already in use', async () => {
+        const port = await findAvailablePort();
+        // Occupy the port with a real server
+        const server = await createTestServer(port);
+        try {
+            // Contract: should throw ChromeLaunchError (not generic Error)
+            await assert.rejects(async () => {
+                await reservePort(port);
+            }, (error) => {
+                assert.ok(error instanceof ChromeLaunchError, 'Should throw ChromeLaunchError');
+                assert.ok(error.message.includes(`${port}`), 'Error message should mention port number');
+                assert.ok(error.message.includes('already in use'), 'Error message should indicate port is in use');
+                return true;
+            }, 'Should throw ChromeLaunchError when port is in use');
+        }
+        finally {
+            await closeServer(server);
+        }
+    });
+    test('fails when attempting to reserve same port twice', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        try {
+            // Contract: second reservation should fail with ChromeLaunchError
+            await assert.rejects(async () => {
+                await reservePort(port);
+            }, ChromeLaunchError, 'Should fail when port already reserved');
+        }
+        finally {
+            reservation.release();
+        }
+    });
+    test('error message includes helpful troubleshooting steps', async () => {
+        const port = await findAvailablePort();
+        const server = await createTestServer(port);
+        try {
+            await assert.rejects(async () => {
+                await reservePort(port);
+            }, (error) => {
+                // Contract: error message should help user troubleshoot
+                assert.ok(error.message.includes('bdg cleanup'), 'Should suggest cleanup command');
+                assert.ok(error.message.includes('lsof'), 'Should suggest checking processes');
+                assert.ok(error.message.includes(`--port ${port + 1}`), 'Should suggest alternative port');
+                return true;
+            }, 'Error message should include troubleshooting steps');
+        }
+        finally {
+            await closeServer(server);
+        }
+    });
+});
+describe('Port Reservation - Release Behavior', () => {
+    test('release() closes the server immediately', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        reservation.release();
+        // Port should be immediately available (not waiting for async cleanup)
+        const testServer = net.createServer();
+        const canBind = await new Promise((resolve) => {
+            testServer.once('error', () => resolve(false));
+            testServer.listen(port, '127.0.0.1', () => {
+                testServer.close();
+                resolve(true);
+            });
+        });
+        assert.ok(canBind, 'Port should be immediately available after release');
+    });
+    test('release() can be called multiple times safely', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        // Multiple releases should not throw
+        reservation.release();
+        reservation.release();
+        reservation.release();
+        assert.ok(true, 'Multiple release() calls should be safe');
+    });
+});
+describe('Port Reservation - Edge Cases', () => {
+    test('handles port number at lower boundary (1024)', async () => {
+        // Ports < 1024 require root, so we test 1024 (first non-privileged port)
+        // This may fail in environments where 1024 is in use - that's expected
+        try {
+            const reservation = await reservePort(1024);
+            reservation.release();
+            assert.ok(true, 'Should handle port 1024');
+        }
+        catch (error) {
+            // If port is in use, verify it's the expected error type
+            assert.ok(error instanceof ChromeLaunchError, 'Should throw ChromeLaunchError for in-use port 1024');
+        }
+    });
+    test('handles port number at upper boundary (65535)', async () => {
+        try {
+            const reservation = await reservePort(65535);
+            reservation.release();
+            assert.ok(true, 'Should handle port 65535');
+        }
+        catch (error) {
+            // If port is in use, verify it's the expected error type
+            assert.ok(error instanceof ChromeLaunchError, 'Should throw ChromeLaunchError for in-use port 65535');
+        }
+    });
+    test('binds to localhost (127.0.0.1) only, not all interfaces', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        try {
+            // Contract: should bind to 127.0.0.1, not 0.0.0.0
+            // This means we can still bind to the same port on other interfaces
+            // We verify by checking we can't bind to 127.0.0.1 but this is implicit
+            // in the reservation working at all
+            assert.ok(true, 'Reservation binds to localhost interface');
+        }
+        finally {
+            reservation.release();
+        }
+    });
+});
+describe('Port Reservation - Atomicity', () => {
+    test('reservation is atomic (prevents race conditions)', async () => {
+        const port = await findAvailablePort();
+        // Attempt two simultaneous reservations
+        const results = await Promise.allSettled([reservePort(port), reservePort(port)]);
+        // Contract: exactly one should succeed, one should fail
+        const successes = results.filter((r) => r.status === 'fulfilled');
+        const failures = results.filter((r) => r.status === 'rejected');
+        assert.equal(successes.length, 1, 'Exactly one reservation should succeed');
+        assert.equal(failures.length, 1, 'Exactly one reservation should fail');
+        // Cleanup successful reservation
+        const success = successes[0];
+        if (success?.status === 'fulfilled') {
+            success.value.release();
+        }
+        // Verify failure is ChromeLaunchError
+        const failure = failures[0];
+        if (failure?.status === 'rejected') {
+            assert.ok(failure.reason instanceof ChromeLaunchError, 'Failed reservation should throw ChromeLaunchError');
+        }
+    });
+});
+// Test Helpers
+/**
+ * Find an available port starting from a base port
+ *
+ * @param startPort - Port to start searching from (default: 9000)
+ * @returns Available port number
+ */
+async function findAvailablePort(startPort = 9000) {
+    for (let port = startPort; port < 65535; port++) {
+        const server = net.createServer();
+        const available = await new Promise((resolve) => {
+            server.once('error', () => resolve(false));
+            server.listen(port, '127.0.0.1', () => {
+                server.close();
+                resolve(true);
+            });
+        });
+        if (available) {
+            return port;
+        }
+    }
+    throw new Error('No available ports found');
+}
+/**
+ * Create a test server on a specific port
+ *
+ * @param port - Port to bind to
+ * @returns Server instance
+ */
+async function createTestServer(port) {
+    const server = net.createServer();
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            resolve(server);
+        });
+    });
+}
+/**
+ * Close a server gracefully
+ *
+ * @param server - Server to close
+ */
+async function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}
+//# sourceMappingURL=portReservation.contract.test.js.map