playwriter 0.0.25 → 0.0.29

package/src/cdp-session.ts

@@ -101,7 +101,7 @@ export class CDPSession {
     this.eventListeners.get(event)?.delete(callback as (params: unknown) => void)
   }
 
-  detach() {
+  close() {
     try {
       for (const pending of this.pendingRequests.values()) {
         pending.reject(new Error('CDPSession detached'))
@@ -128,7 +128,7 @@ export async function getCDPSessionForPage({ page, wsUrl }: { page: Page; wsUrl:
   const pages = page.context().pages()
   const pageIndex = pages.indexOf(page)
   if (pageIndex === -1) {
-    cdp.detach()
+    cdp.close()
     throw new Error('Page not found in context')
   }
 
@@ -136,13 +136,13 @@ export async function getCDPSessionForPage({ page, wsUrl }: { page: Page; wsUrl:
   const pageTargets = targetInfos.filter((t) => t.type === 'page')
 
   if (pageIndex >= pageTargets.length) {
-    cdp.detach()
+    cdp.close()
     throw new Error(`Page index ${pageIndex} out of bounds (${pageTargets.length} targets)`)
   }
 
   const target = pageTargets[pageIndex]
   if (target.url !== page.url()) {
-    cdp.detach()
+    cdp.close()
     throw new Error(`URL mismatch: page has "${page.url()}" but target has "${target.url}"`)
   }
 

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
+
+- `playwriter/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/cli.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { cac } from 'cac'
+import { startPlayWriterCDPRelayServer } from './cdp-relay.js'
+import { createFileLogger } from './create-logger.js'
+import { VERSION } from './utils.js'
+
+const RELAY_PORT = 19988
+
+const cli = cac('playwriter')
+
+cli
+  .command('', 'Start the MCP server (default)')
+  .option('--host <host>', 'Remote relay server host to connect to (or use PLAYWRITER_HOST env var)')
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
+  .action(async (options: { host?: string; token?: string }) => {
+    const { startMcp } = await import('./mcp.js')
+    await startMcp({
+      host: options.host,
+      token: options.token,
+    })
+  })
+
+cli
+  .command('serve', 'Start the CDP relay server for remote MCP connections')
+  .option('--host <host>', 'Host to bind to', { default: '0.0.0.0' })
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
+  .action(async (options: { host: string; token?: string }) => {
+    const token = options.token || process.env.PLAYWRITER_TOKEN
+    if (!token) {
+      console.error('Error: Authentication token is required.')
+      console.error('Provide --token <token> or set PLAYWRITER_TOKEN environment variable.')
+      process.exit(1)
+    }
+
+    const logger = createFileLogger()
+
+    process.title = 'playwriter-serve'
+
+    process.on('uncaughtException', async (err) => {
+      await logger.error('Uncaught Exception:', err)
+      process.exit(1)
+    })
+
+    process.on('unhandledRejection', async (reason) => {
+      await logger.error('Unhandled Rejection:', reason)
+      process.exit(1)
+    })
+
+    const server = await startPlayWriterCDPRelayServer({
+      port: RELAY_PORT,
+      host: options.host,
+      token,
+      logger,
+    })
+
+    console.log('Playwriter CDP relay server started')
+    console.log(`  Host: ${options.host}`)
+    console.log(`  Port: ${RELAY_PORT}`)
+    console.log(`  Token: (configured)`)
+    console.log(`  Logs: ${logger.logFilePath}`)
+    console.log('')
+    console.log('Endpoints:')
+    console.log(`  Extension: ws://${options.host}:${RELAY_PORT}/extension`)
+    console.log(`  CDP:       ws://${options.host}:${RELAY_PORT}/cdp/<client-id>?token=<token>`)
+    console.log('')
+    console.log('Press Ctrl+C to stop.')
+
+    process.on('SIGINT', () => {
+      console.log('\nShutting down...')
+      server.close()
+      process.exit(0)
+    })
+
+    process.on('SIGTERM', () => {
+      console.log('\nShutting down...')
+      server.close()
+      process.exit(0)
+    })
+  })
+
+cli.help()
+cli.version(VERSION)
+
+cli.parse()

package/src/create-logger.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import util from 'node:util'
+import stripAnsi from 'strip-ansi'
 import { LOG_FILE_PATH } from './utils.js'
 
 export type Logger = {
@@ -23,7 +24,7 @@ export function createFileLogger({ logFilePath }: { logFilePath?: string } = {})
     const message = args.map(arg =>
       typeof arg === 'string' ? arg : util.inspect(arg, { depth: null, colors: false })
     ).join(' ')
-    queue = queue.then(() => fs.promises.appendFile(resolvedLogFilePath, message + '\n'))
+    queue = queue.then(() => fs.promises.appendFile(resolvedLogFilePath, stripAnsi(message) + '\n'))
     return queue
   }
 

package/src/debugger-examples-types.ts

@@ -0,0 +1,10 @@
+import type { Page } from 'playwright-core'
+import type { CDPSession } from './cdp-session.js'
+import type { Debugger } from './debugger.js'
+import type { Editor } from './editor.js'
+
+export declare const page: Page
+export declare const getCDPSession: (options: { page: Page }) => Promise<CDPSession>
+export declare const createDebugger: (options: { cdp: CDPSession }) => Debugger
+export declare const createEditor: (options: { cdp: CDPSession }) => Editor
+export declare const console: { log: (...args: unknown[]) => void }

package/src/debugger-examples.ts

@@ -0,0 +1,66 @@
+import { page, getCDPSession, createDebugger, console } from './debugger-examples-types.js'
+
+// Example: List available scripts and set a breakpoint
+async function listScriptsAndSetBreakpoint() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  const scripts = await dbg.listScripts({ search: 'app' })
+  console.log(scripts)
+
+  if (scripts.length > 0) {
+    const bpId = await dbg.setBreakpoint({ file: scripts[0].url, line: 100 })
+    console.log('Breakpoint set:', bpId)
+  }
+}
+
+// Example: Inspect state when paused at a breakpoint
+async function inspectWhenPaused() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  if (dbg.isPaused()) {
+    const loc = await dbg.getLocation()
+    console.log('Paused at:', loc.url, 'line', loc.lineNumber)
+    console.log('Source:', loc.sourceContext)
+
+    const vars = await dbg.inspectLocalVariables()
+    console.log('Variables:', vars)
+
+    const result = await dbg.evaluate({ expression: 'myVar.length' })
+    console.log('myVar.length =', result.value)
+
+    await dbg.stepOver()
+  }
+}
+
+// Example: Step through code
+async function stepThroughCode() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 })
+
+  if (dbg.isPaused()) {
+    await dbg.stepOver()
+    await dbg.stepInto()
+    await dbg.stepOut()
+    await dbg.resume()
+  }
+}
+
+// Example: Cleanup all breakpoints
+async function cleanupBreakpoints() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+
+  const breakpoints = dbg.listBreakpoints()
+  for (const bp of breakpoints) {
+    await dbg.deleteBreakpoint({ breakpointId: bp.id })
+  }
+}
+
+export { listScriptsAndSetBreakpoint, inspectWhenPaused, stepThroughCode, cleanupBreakpoints }