e2e-pilot 0.0.69

package/src/cdp-session.ts

@@ -0,0 +1,203 @@
+import WebSocket from 'ws'
+import type { Page } from 'playwright-core'
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js'
+import type { CDPResponseBase, CDPEventBase } from './cdp-types.js'
+
+/**
+ * Common interface for CDP sessions that works with both our CDPSession
+ * and Playwright's CDPSession. Use this type when you want to accept either.
+ *
+ * Uses loose types so Playwright's CDPSession (which uses Protocol.Events)
+ * is assignable to this interface.
+ */
+export interface ICDPSession {
+  send(method: string, params?: object): Promise<unknown>
+  on(event: string, callback: (params: any) => void): unknown
+  off(event: string, callback: (params: any) => void): unknown
+  detach(): Promise<void>
+}
+
+interface PendingRequest {
+  resolve: (result: unknown) => void
+  reject: (error: Error) => void
+}
+
+export class CDPSession implements ICDPSession {
+  private ws: WebSocket
+  private pendingRequests = new Map<number, PendingRequest>()
+  private eventListeners = new Map<string, Set<(params: unknown) => void>>()
+  private messageId = 0
+  private sessionId: string | null = null
+
+  constructor(ws: WebSocket) {
+    this.ws = ws
+    this.ws.on('message', (data) => {
+      try {
+        const message = JSON.parse(data.toString()) as CDPResponseBase | CDPEventBase
+
+        if ('id' in message) {
+          const response = message as CDPResponseBase
+          const pending = this.pendingRequests.get(response.id)
+          if (pending) {
+            this.pendingRequests.delete(response.id)
+            if (response.error) {
+              pending.reject(new Error(response.error.message))
+            } else {
+              pending.resolve(response.result)
+            }
+          }
+        } else if ('method' in message) {
+          const event = message as CDPEventBase
+          if (event.sessionId === this.sessionId || !event.sessionId) {
+            const listeners = this.eventListeners.get(event.method)
+            if (listeners) {
+              for (const listener of listeners) {
+                listener(event.params)
+              }
+            }
+          }
+        }
+      } catch (e) {
+        console.error('[CDPSession] Message handling error:', e)
+      }
+    })
+  }
+
+  setSessionId(sessionId: string) {
+    this.sessionId = sessionId
+  }
+
+  send<K extends keyof ProtocolMapping.Commands>(
+    method: K,
+    params?: ProtocolMapping.Commands[K]['paramsType'][0],
+  ): Promise<ProtocolMapping.Commands[K]['returnType']> {
+    const id = ++this.messageId
+    const message: Record<string, unknown> = { id, method, params }
+    if (this.sessionId) {
+      message.sessionId = this.sessionId
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(id)
+        reject(new Error(`CDP command timeout: ${method}`))
+      }, 30000)
+
+      this.pendingRequests.set(id, {
+        resolve: (result) => {
+          clearTimeout(timeout)
+          resolve(result as ProtocolMapping.Commands[K]['returnType'])
+        },
+        reject: (error) => {
+          clearTimeout(timeout)
+          reject(error)
+        },
+      })
+
+      try {
+        this.ws.send(JSON.stringify(message))
+      } catch (error) {
+        clearTimeout(timeout)
+        this.pendingRequests.delete(id)
+        reject(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+  }
+
+  on<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set())
+    }
+    this.eventListeners.get(event)!.add(callback as (params: unknown) => void)
+    return this
+  }
+
+  /** Alias for `on` - matches Playwright's CDPSession interface */
+  addListener<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): this {
+    return this.on(event, callback)
+  }
+
+  off<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
+    this.eventListeners.get(event)?.delete(callback as (params: unknown) => void)
+    return this
+  }
+
+  /** Alias for `off` - matches Playwright's CDPSession interface */
+  removeListener<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): this {
+    return this.off(event, callback)
+  }
+
+  /** Listen for an event once, then automatically remove the listener */
+  once<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
+    const onceCallback = (params: ProtocolMapping.Events[K][0]) => {
+      this.off(event, onceCallback)
+      callback(params)
+    }
+    return this.on(event, onceCallback)
+  }
+
+  /** Alias for `close` - matches Playwright's CDPSession interface */
+  detach(): Promise<void> {
+    this.close()
+    return Promise.resolve()
+  }
+
+  close() {
+    try {
+      for (const pending of this.pendingRequests.values()) {
+        pending.reject(new Error('CDPSession detached'))
+      }
+      this.pendingRequests.clear()
+      this.eventListeners.clear()
+      this.ws.close()
+    } catch (e) {
+      console.error('[CDPSession] WebSocket close error:', e)
+    }
+  }
+}
+
+export async function getCDPSessionForPage({ page, wsUrl }: { page: Page; wsUrl: string }): Promise<CDPSession> {
+  const ws = new WebSocket(wsUrl)
+
+  await new Promise<void>((resolve, reject) => {
+    ws.on('open', resolve)
+    ws.on('error', reject)
+  })
+
+  const cdp = new CDPSession(ws)
+
+  const pages = page.context().pages()
+  const pageIndex = pages.indexOf(page)
+  if (pageIndex === -1) {
+    cdp.close()
+    throw new Error('Page not found in context')
+  }
+
+  const { targetInfos } = await cdp.send('Target.getTargets')
+  const pageTargets = targetInfos.filter((t) => t.type === 'page')
+
+  if (pageIndex >= pageTargets.length) {
+    cdp.close()
+    throw new Error(`Page index ${pageIndex} out of bounds (${pageTargets.length} targets)`)
+  }
+
+  const target = pageTargets[pageIndex]
+  if (target.url !== page.url()) {
+    cdp.close()
+    throw new Error(`URL mismatch: page has "${page.url()}" but target has "${target.url}"`)
+  }
+
+  const { sessionId } = await cdp.send('Target.attachToTarget', {
+    targetId: target.targetId,
+    flatten: true,
+  })
+  cdp.setSessionId(sessionId)
+
+  return cdp
+}

package/src/cdp-timing.md

@@ -0,0 +1,128 @@
+# CDP Event Timing and Synchronization
+
+This document describes the timing issues we discovered and fixed in the CDP relay server, and outlines potential future improvements.
+
+## The Problem
+
+When Playwright connects to Chrome via our CDP relay, there's a race condition between:
+1. **Target attachment** - Extension attaches to a tab and sends `Target.attachedToTarget`
+2. **Runtime initialization** - Playwright calls `Runtime.enable` to set up JavaScript execution contexts
+3. **Page visibility** - `context.pages()` returns pages that are fully ready
+
+### Symptom
+Tests or MCP calls that run immediately after toggling the extension would fail with "page not found" because `context.pages()` didn't include the newly attached page yet.
+
+### Root Cause
+The `Runtime.enable` CDP command triggers `Runtime.executionContextCreated` events that tell Playwright the page's JavaScript context is ready. Without these events, pages aren't fully visible to `context.pages()`.
+
+Previously, the extension had an arbitrary `sleep(200ms)` in the `Runtime.enable` handler to work around this. When this was increased to 400ms, tests started failing due to timing mismatches.
+
+## The Fix
+
+We replaced the arbitrary sleep with **event-based synchronization** in the relay server:
+
+```typescript
+case 'Runtime.enable': {
+  // Set up listener for executionContextCreated
+  const contextCreatedPromise = new Promise<void>((resolve) => {
+    const handler = ({ event }) => {
+      if (event.method === 'Runtime.executionContextCreated' && 
+          event.sessionId === sessionId) {
+        clearTimeout(timeout)
+        emitter.off('cdp:event', handler)
+        resolve()
+      }
+    }
+    const timeout = setTimeout(() => {
+      emitter.off('cdp:event', handler)
+      logger?.log('IMPORTANT: Runtime.enable timed out...')
+      resolve()
+    }, 3000)
+    emitter.on('cdp:event', handler)
+  })
+
+  // Forward command to extension
+  const result = await sendToExtension(...)
+  
+  // Wait for the event before returning
+  await contextCreatedPromise
+  
+  return result
+}
+```
+
+### Why This Works
+- When Playwright calls `Runtime.enable`, we forward it to the extension
+- The extension enables Runtime on the Chrome tab
+- Chrome sends `Runtime.executionContextCreated` events
+- We wait for at least one such event before returning
+- By the time `Runtime.enable` returns, the page's context is ready
+
+## Event Flow
+
+```
+Test toggles extension
+       ↓
+Extension attaches to tab
+       ↓
+Extension sends Target.attachedToTarget to relay
+       ↓
+Relay broadcasts to Playwright clients
+       ↓
+Playwright calls Runtime.enable ──────────────────┐
+       ↓                                          │
+Relay forwards to extension                       │
+       ↓                                          │
+Extension enables Runtime on Chrome tab           │
+       ↓                                          │
+Chrome sends Runtime.executionContextCreated      │
+       ↓                                          │
+Relay receives event, resolves promise ───────────┘
+       ↓
+Runtime.enable returns to Playwright
+       ↓
+Page is now visible in context.pages()
+```
+
+## Future Improvements
+
+### 1. Wait for Target Attachment
+
+Currently, tests still need small waits after `toggleExtensionForActiveTab()` because the MCP's Playwright browser needs time to process `Target.attachedToTarget`. 
+
+A potential improvement: Track "pending" vs "ready" targets in the relay server:
+- When `Target.attachedToTarget` arrives → mark as pending
+- When `Runtime.executionContextCreated` arrives → mark as ready
+- Expose an endpoint or mechanism for MCP to wait for all targets to be ready
+
+### 2. Extension-Level Confirmation
+
+The extension could wait for confirmation from the relay server before returning from `attachTab()`:
+- Extension sends `Target.attachedToTarget`
+- Relay waits for `Runtime.executionContextCreated`
+- Relay sends acknowledgment back to extension
+- Extension's `attachTab()` returns
+- `toggleExtensionForActiveTab()` returns with page fully ready
+
+This would eliminate the need for any waits in test code.
+
+### 3. MCP-Level Page Readiness Check
+
+The MCP could check page readiness before executing code:
+- Before running user code, verify each page in `context.pages()` has a ready execution context
+- Use Playwright's `page.evaluate()` with a simple expression to confirm the page is responsive
+
+## Test Implications
+
+The current test waits (100ms after toggle) exist for multiple reasons:
+1. **Target attachment** - Waiting for `Target.attachedToTarget` to be processed
+2. **Navigation completion** - Waiting for page loads/navigations
+3. **State cleanup** - Ensuring previous test state is cleared
+4. **Debugger synchronization** - Waiting for breakpoints/pause states
+
+The `Runtime.enable` fix addresses reason #1 at the CDP level, but test waits are still needed for the other reasons.
+
+## Files Changed
+
+- `e2e-pilot/src/cdp-relay.ts` - Added event-based wait in `Runtime.enable` handler
+- `extension/src/background.ts` - Removed arbitrary `sleep(200)` from `Runtime.enable` handler

package/src/cdp-types.ts

@@ -0,0 +1,155 @@
+import type { Protocol } from 'devtools-protocol';
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
+
+export type CDPCommandFor<T extends keyof ProtocolMapping.Commands> = {
+  id: number;
+  sessionId?: string;
+  method: T;
+  params?: ProtocolMapping.Commands[T]['paramsType'][0];
+};
+
+export type CDPCommand = {
+  [K in keyof ProtocolMapping.Commands]: CDPCommandFor<K>;
+}[keyof ProtocolMapping.Commands];
+
+export type CDPResponseFor<T extends keyof ProtocolMapping.Commands> = {
+  id: number;
+  sessionId?: string;
+  result?: ProtocolMapping.Commands[T]['returnType'];
+  error?: { code?: number; message: string };
+};
+
+export type CDPResponse = {
+  [K in keyof ProtocolMapping.Commands]: CDPResponseFor<K>;
+}[keyof ProtocolMapping.Commands];
+
+export type CDPEventFor<T extends keyof ProtocolMapping.Events> = {
+  method: T;
+  sessionId?: string;
+  params?: ProtocolMapping.Events[T][0];
+};
+
+export type CDPEvent = {
+  [K in keyof ProtocolMapping.Events]: CDPEventFor<K>;
+}[keyof ProtocolMapping.Events];
+
+export type CDPResponseBase = {
+  id: number;
+  sessionId?: string;
+  result?: unknown;
+  error?: { code?: number; message: string };
+};
+
+export type CDPEventBase = {
+  method: string;
+  sessionId?: string;
+  params?: unknown;
+};
+
+export type CDPMessage = CDPCommand | CDPResponse | CDPEvent;
+
+export type RelayServerEvents = {
+  'cdp:command': (data: { clientId: string; command: CDPCommand }) => void
+  'cdp:event': (data: { event: CDPEventBase; sessionId?: string }) => void
+  'cdp:response': (data: { clientId: string; response: CDPResponseBase; command: CDPCommand }) => void
+}
+
+export { Protocol, ProtocolMapping };
+
+// types tests. to see if types are right with some simple examples
+if (false as any) {
+  const browserVersionCommand = {
+    id: 1,
+    method: 'Browser.getVersion',
+  } satisfies CDPCommand;
+
+  const browserVersionResponse = {
+    id: 1,
+    result: {
+      protocolVersion: '1.3',
+      product: 'Chrome',
+      revision: '123',
+      userAgent: 'Mozilla/5.0',
+      jsVersion: 'V8',
+    }
+  } satisfies CDPResponse;
+
+  const targetAttachCommand = {
+    id: 2,
+    method: 'Target.setAutoAttach',
+    params: {
+      autoAttach: true,
+      waitForDebuggerOnStart: false,
+    }
+  } satisfies CDPCommand;
+
+  const targetAttachResponse = {
+    id: 2,
+    result: undefined,
+  } satisfies CDPResponse;
+
+  const attachedToTargetEvent = {
+    method: 'Target.attachedToTarget',
+    params: {
+      sessionId: 'session-1',
+      targetInfo: {
+        targetId: 'target-1',
+        type: 'page',
+        title: 'Example',
+        url: 'https://example.com',
+        attached: true,
+        canAccessOpener: false,
+      },
+      waitingForDebugger: false,
+    }
+  } satisfies CDPEvent;
+
+  const consoleMessageEvent = {
+    method: 'Runtime.consoleAPICalled',
+    params: {
+      type: 'log',
+      args: [],
+      executionContextId: 1,
+      timestamp: 123456789,
+    }
+  } satisfies CDPEvent;
+
+  const pageNavigateCommand = {
+    id: 3,
+    method: 'Page.navigate',
+    params: {
+      url: 'https://example.com',
+    }
+  } satisfies CDPCommand;
+
+  const pageNavigateResponse = {
+    id: 3,
+    result: {
+      frameId: 'frame-1',
+    }
+  } satisfies CDPResponse;
+
+  const networkRequestEvent = {
+    method: 'Network.requestWillBeSent',
+    sessionId: 'session-1',
+    params: {
+      requestId: 'req-1',
+      loaderId: 'loader-1',
+      documentURL: 'https://example.com',
+      request: {
+        url: 'https://example.com/api',
+        method: 'GET',
+        headers: {},
+        initialPriority: 'High',
+        referrerPolicy: 'no-referrer',
+      },
+      timestamp: 123456789,
+      wallTime: 123456789,
+      initiator: {
+        type: 'other',
+      },
+      redirectHasExtraInfo: false,
+      type: 'XHR',
+    }
+  } satisfies CDPEvent;
+}