browser-debugger-cli 0.1.0 → 0.2.0

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

@@ -1,137 +0,0 @@
-import assert from 'node:assert/strict';
-import { describe, it, beforeEach, afterEach } from 'node:test';
-import { createMockTarget, mockCDPCreateTargetResponse, mockHTTPCreateResponse, } from '../../__testfixtures__/connectionTargets.js';
-import { createNewTab } from '../tabs.js';
-// Mock fetch globally for HTTP endpoints
-let originalFetch;
-let fetchMockResponses;
-let fetchCallCount;
-function setupFetchMock() {
-    originalFetch = global.fetch;
-    fetchMockResponses = [];
-    fetchCallCount = 0;
-    global.fetch = (() => {
-        const responseIndex = fetchCallCount++;
-        const response = fetchMockResponses[responseIndex];
-        if (response) {
-            return response;
-        }
-        return Promise.reject(new Error(`Unexpected fetch call ${responseIndex + 1}`));
-    });
-}
-function mockFetchResponse(response) {
-    fetchMockResponses.push(response);
-}
-function createSuccessResponse(data) {
-    return {
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve(data),
-    };
-}
-function createFailureResponse(status, statusText) {
-    return {
-        ok: false,
-        status,
-        statusText,
-    };
-}
-function createMockCDP(overrides = {}) {
-    return {
-        send: () => Promise.resolve(mockCDPCreateTargetResponse),
-        getPort: () => 9222,
-        isConnected: () => true,
-        ...overrides,
-    };
-}
-void describe('Tab Creation Contract', () => {
-    let mockCDP;
-    beforeEach(() => {
-        setupFetchMock();
-        mockCDP = createMockCDP();
-    });
-    afterEach(() => {
-        global.fetch = originalFetch;
-    });
-    void describe('createNewTab - Happy Path', () => {
-        void it('creates tab via CDP strategy and returns target', async () => {
-            // Arrange: Mock successful CDP creation and verification
-            const expectedTarget = createMockTarget({
-                id: mockCDPCreateTargetResponse.targetId,
-                url: 'http://localhost:3000/test',
-            });
-            // Mock verification endpoint returning the target immediately
-            mockFetchResponse(createSuccessResponse([expectedTarget]));
-            // Act
-            const result = await createNewTab('http://localhost:3000/test', mockCDP);
-            // Assert: Returns the created target
-            assert.equal(result.id, mockCDPCreateTargetResponse.targetId);
-            assert.equal(result.url, 'http://localhost:3000/test');
-        });
-        void it('handles URLs without protocol', async () => {
-            // Arrange: Mock successful CDP creation
-            let capturedUrl = '';
-            mockCDP.send = (...args) => {
-                const params = args[1];
-                const typedParams = params;
-                capturedUrl = typedParams?.url ?? '';
-                return Promise.resolve(mockCDPCreateTargetResponse);
-            };
-            const expectedTarget = createMockTarget({
-                id: mockCDPCreateTargetResponse.targetId,
-                url: 'http://localhost:3000', // Normalized with protocol
-            });
-            mockFetchResponse(createSuccessResponse([expectedTarget]));
-            // Act: Pass URL without protocol
-            const result = await createNewTab('localhost:3000', mockCDP);
-            // Assert: Works correctly with normalized URL
-            assert.equal(result.id, mockCDPCreateTargetResponse.targetId);
-            // Verify CDP was called with normalized URL (normalizeUrl should add http://)
-            assert.ok(capturedUrl.includes('localhost:3000'));
-        });
-    });
-    void describe('createNewTab - Error Handling', () => {
-        void it('falls back to HTTP when CDP fails', async () => {
-            // Arrange: CDP creation fails
-            mockCDP.send = () => Promise.reject(new Error('CDP connection lost'));
-            // Mock HTTP creation to succeed
-            mockFetchResponse(createSuccessResponse(mockHTTPCreateResponse));
-            // Act
-            const result = await createNewTab('http://localhost:3000/test', mockCDP);
-            // Assert: Falls back to HTTP and succeeds
-            assert.equal(result.id, mockHTTPCreateResponse.id);
-            assert.equal(result.url, mockHTTPCreateResponse.url);
-        });
-        void it('handles malformed CDP responses gracefully', async () => {
-            // Arrange: CDP returns malformed response (missing targetId)
-            mockCDP.send = () => Promise.reject(new Error('Malformed response'));
-            // Mock HTTP creation to succeed (fallback)
-            mockFetchResponse(createSuccessResponse(mockHTTPCreateResponse));
-            // Act
-            const result = await createNewTab('http://localhost:3000/test', mockCDP);
-            // Assert: Falls back to HTTP
-            assert.equal(result.id, mockHTTPCreateResponse.id);
-        });
-        void it('throws meaningful error when all strategies fail', async () => {
-            // Arrange: CDP creation fails
-            mockCDP.send = () => Promise.reject(new Error('CDP failed'));
-            // Mock HTTP creation to also fail
-            mockFetchResponse(createFailureResponse(500, 'Internal Server Error'));
-            // Act & Assert: Should throw after both strategies fail
-            await assert.rejects(() => createNewTab('http://localhost:3000/test', mockCDP), /Failed to create new tab/);
-        });
-    });
-});
-// NOTE: createOrFindTarget tests removed due to complex mocking requirements
-// This function combines target discovery with creation, making it difficult to test
-// in isolation without extensive mocking of the verification process.
-//
-// Coverage is provided indirectly through:
-// 1. Individual createNewTab tests (creation logic)
-// 2. Target validation tests in finder.contract.test.ts (discovery logic)
-// 3. Integration tests that exercise the full workflow
-//
-// This follows our testing philosophy of testing complex logic (createNewTab, validateTarget)
-// while avoiding testing of simple orchestration functions that primarily combine
-// other tested behaviors.
-//# sourceMappingURL=tabs.contract.test.js.map

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

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

package/dist/connection/tabs.d.ts

@@ -1,82 +0,0 @@
-import type { CDPConnection } from './cdp.js';
-import type { CDPTarget } from '../types.js';
-/**
- * Find the best matching target from a list of tabs.
- *
- * Filters to page-type targets only because other target types (extensions,
- * service workers, etc.) cannot be navigated to user URLs. The scoring
- * system handles ambiguous matches by warning users when multiple tabs
- * have identical non-perfect scores, helping debug URL matching issues.
- *
- * @param normalizedUrl - Target URL to find (must be pre-normalized)
- * @param targets - List of available targets
- * @returns Best matching target or null if no match found
- */
-export declare function findBestTarget(normalizedUrl: string, targets: CDPTarget[]): CDPTarget | null;
-/**
- * Create a new tab with the specified URL using CDP.
- *
- * Uses a two-phase approach with enhanced error handling:
- * - CDP command failures → HTTP fallback (prevents total failure)
- * - Verification timeouts → Fail fast with targeted error (prevents duplicate tabs)
- *
- * Configurable verification timeout via BDG_TARGET_VERIFY_TIMEOUT environment
- * variable to handle slow Chrome registration in enterprise/headless environments.
- *
- * @param normalizedUrl - URL to open in the new tab (must be pre-normalized)
- * @param cdp - CDP connection instance
- * @returns Target information for the new tab
- * @throws Error if tab creation fails or verification times out
- */
-export declare function createNewTab(normalizedUrl: string, cdp: CDPConnection): Promise<CDPTarget>;
-/**
- * Navigate an existing tab to a new URL using CDP.
- *
- * Requires attaching to the target first because Page.navigate commands
- * must be sent within a target session context. The flatten:true option
- * simplifies session management by avoiding nested session hierarchies
- * that can complicate cleanup and event handling.
- *
- * @param targetId - CDP target ID to navigate
- * @param normalizedUrl - URL to navigate to (must be pre-normalized)
- * @param cdp - CDP connection instance
- * @throws Error if navigation fails (e.g., network error, invalid URL, blocked by browser)
- */
-export declare function navigateToUrl(targetId: string, normalizedUrl: string, cdp: CDPConnection): Promise<void>;
-/**
- * Wait for a target to be ready (URL matches expected).
- *
- * Polling is necessary because tab navigation is asynchronous and Chrome
- * may report intermediate states (like about:blank) before the final URL
- * loads. The 500ms additional wait for about:blank handles the common case
- * where Chrome briefly shows a blank page before starting navigation.
- *
- * Uses HTTP endpoint instead of CDP for target status because the HTTP
- * interface provides more reliable target state information during
- * navigation transitions.
- *
- * @param targetId - CDP target ID to wait for
- * @param normalizedUrl - Expected URL (must be pre-normalized)
- * @param cdp - CDP connection instance
- * @param maxWaitMs - Maximum time to wait in milliseconds
- * @throws Error if target doesn't become ready within maxWaitMs timeout
- */
-export declare function waitForTargetReady(targetId: string, normalizedUrl: string, cdp: CDPConnection, maxWaitMs?: number): Promise<void>;
-/**
- * Create a new tab or find existing tab with the target URL.
- *
- * This is the main entry point for tab management with a clear workflow:
- * when reuseTab=true, attempts to find and navigate existing tabs to avoid
- * creating unnecessary browser tabs. When reuseTab=false or no suitable
- * tab exists, creates a new tab for isolated testing scenarios.
- *
- * URL normalization happens once at entry to ensure consistent matching
- * and navigation behavior throughout the entire workflow.
- *
- * @param url - Target URL (will be normalized once at entry)
- * @param cdp - CDP connection instance
- * @param reuseTab - If true, navigate existing tab instead of creating new one
- * @returns Target information
- */
-export declare function createOrFindTarget(url: string, cdp: CDPConnection, reuseTab?: boolean): Promise<CDPTarget>;
-//# sourceMappingURL=tabs.d.ts.map

package/dist/connection/tabs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/connection/tabs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAgBzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAsJzC;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CA+B5F;AA0MD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAkChG;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,aAAa,EAClB,SAAS,SAAkC,GAC1C,OAAO,CAAC,IAAI,CAAC,CA0Bf;AA+HD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,EAClB,QAAQ,UAAoB,GAC3B,OAAO,CAAC,SAAS,CAAC,CAgCpB"}