@agent-scope/playwright 1.17.0 → 1.17.2

package/README.md

@@ -0,0 +1,416 @@
+# `@agent-scope/playwright`
+
+Playwright fixture + browser-entry bundle for capturing React component trees in end-to-end tests. Extends `@playwright/test` with a `scope.capture()` fixture method that serialises the live React fibre tree into a `PageReport` — no source maps, no instrumented builds required beyond the Babel plugin.
+
+## Installation
+
+```bash
+npm install @agent-scope/playwright
+# or
+bun add @agent-scope/playwright
+```
+
+Peer dependencies: `@playwright/test`.
+
+**Prerequisites**: The package ships a pre-built browser IIFE bundle (`browser-bundle.iife.js`). Build it first if it doesn't exist:
+
+```bash
+bun run build  # in packages/playwright
+```
+
+---
+
+## What it does / when to use
+
+| Use case | What to use |
+|---|---|
+| Capture React tree in a Playwright test | `test` + `scope.capture()` fixture |
+| Navigate then capture in one call | `scope.captureUrl(url)` |
+| Capture from a second page object | `scope.capture(otherPage)` |
+| Wait for async data to finish loading | `scope.capture({ waitForStable: true })` |
+| Inject the browser script manually (Vite/custom setup) | `getBrowserEntryScript()` |
+| Load a `PageReport` from JSON | `loadTrace(rawJson)` |
+| Generate a Playwright test skeleton from a trace | `generateTest(trace)` |
+
+---
+
+## Architecture
+
+```
+Browser (page)                        Node.js (test)
+─────────────────────────────────     ───────────────────────────
+page.addInitScript(bundle)            fixture.ts
+  └── browser-entry.ts (IIFE)    ←    BrowserPool / SatoriRenderer
+       1. installHook()               scope.capture()
+       2. Vite react-refresh compat    └── evaluateCapture(page)
+       3. await firstCommit                └── page.evaluate(
+       4. window.__SCOPE_CAPTURE__()             __SCOPE_CAPTURE_JSON__()
+       5. window.__SCOPE_CAPTURE_JSON__()    )
+                                          → JSON string
+                                          → JSON.parse()
+                                          → PageReport
+```
+
+### Browser-entry injection pattern
+
+The fixture calls `page.addInitScript({ path: bundlePath })` before any navigation. This ensures the bundle runs in the browser before React initialises — critical because the DevTools hook (`installHook()`) must be installed before React evaluates its own bootstrap code.
+
+### Vite react-refresh compatibility
+
+Vite's `react-refresh` preamble (`injectIntoGlobalHook`) accesses `hook.renderers.forEach(...)` (a `Map<number, RendererObj>`). The Scope devtools hook stores renderers in `_renderers` (with wrapper objects). `browser-entry.ts` creates a proxy `renderers` Map that exposes only the raw renderer objects, patching `inject()` to keep it in sync. Without this, the preamble throws mid-execution and React commits never reach the hook.
+
+### Async React 18 first-commit
+
+React 18's concurrent scheduler may call `inject()` before the first `onCommitFiberRoot`. The browser entry wraps `onCommitFiberRoot` to set `hasCommitted = true` and resolve a `firstCommit` Promise. `window.__SCOPE_CAPTURE__()` awaits this promise if `hasCommitted` is false — preventing "Execution context was destroyed" races in SPAs that navigate before the first render completes.
+
+### CDP structured-clone bypass
+
+`window.__SCOPE_CAPTURE_JSON__()` serialises the `PageReport` to a JSON string inside the browser, bypassing Playwright's CDP structured-clone limit. `evaluateCapture()` prefers `__SCOPE_CAPTURE_JSON__` and falls back to `__SCOPE_CAPTURE__` for older runtime versions.
+
+---
+
+## API Reference
+
+### `test` and `expect`
+
+Drop-in replacements for `@playwright/test`'s `test` and `expect` that add the `scope` fixture.
+
+```typescript
+import { test, expect } from '@agent-scope/playwright';
+
+test('captures React tree', async ({ scope, page }) => {
+  await page.goto('http://localhost:5173');
+  const report = await scope.capture();
+  expect(report.tree.name).toBeTruthy();
+});
+```
+
+---
+
+### `ScopeFixture`
+
+The `scope` object available inside tests.
+
+```typescript
+interface ScopeFixture {
+  scope: {
+    capture(options?: CaptureOptions): Promise<PageReport>;
+    capture(targetPage: Page, options?: CaptureOptions): Promise<PageReport>;
+    captureUrl(url: string): Promise<PageReport>;
+  };
+}
+```
+
+#### `scope.capture(options?)`
+
+Captures the React component tree from the fixture's default `page`. Safe to call immediately after `page.goto()` — the browser bundle awaits the first React commit internally.
+
+```typescript
+const report = await scope.capture();
+const report = await scope.capture({ waitForStable: true, stableMs: 500 });
+```
+
+#### `scope.capture(targetPage, options?)`
+
+Captures from an alternative Playwright `Page` object. The browser bundle is injected into `targetPage` automatically.
+
+```typescript
+const secondPage = await context.newPage();
+await secondPage.goto('http://localhost:5173/modal');
+const report = await scope.capture(secondPage);
+```
+
+#### `scope.captureUrl(url)`
+
+Navigates to `url` on the fixture page then immediately captures.
+
+```typescript
+const report = await scope.captureUrl('http://localhost:5173');
+```
+
+---
+
+### `CaptureOptions`
+
+```typescript
+interface CaptureOptions {
+  /**
+   * Poll until component count is stable for `stableMs` ms.
+   * Use when the page performs async data loading after initial render.
+   * Default: false.
+   */
+  waitForStable?: boolean;
+
+  /**
+   * How long (ms) component count must remain unchanged before capture
+   * is considered stable. Only used with waitForStable: true.
+   * Default: 1000.
+   */
+  stableMs?: number;
+
+  /**
+   * Maximum time (ms) to spend polling before returning the last
+   * successful capture. Does NOT throw on timeout.
+   * Only used with waitForStable: true.
+   * Default: 15000.
+   */
+  timeoutMs?: number;
+
+  /**
+   * Use lightweight captures (structure only, no props/state/hooks) during
+   * stability polling. A single full capture is performed once stability
+   * is confirmed. Reduces CDP payload cost per poll tick.
+   * Only used with waitForStable: true.
+   * Default: false.
+   */
+  lightweight?: boolean;
+}
+```
+
+---
+
+### `PageReport`
+
+The return type of `scope.capture()` — defined in `@agent-scope/core`.
+
+```typescript
+interface PageReport {
+  url: string;
+  route: null;
+  timestamp: number;
+  capturedIn: number;          // ms to capture
+  tree: ComponentNode;         // root of the React component tree
+  errors: unknown[];
+  suspenseBoundaries: unknown[];
+  consoleEntries: unknown[];
+}
+
+interface ComponentNode {
+  id: number;
+  name: string;
+  type: 'function' | 'class' | 'other';
+  source: SourceLocation | null;
+  props: SerializedValue;
+  state: SerializedValue[];
+  context: SerializedValue[];
+  renderCount: number;
+  renderDuration: number;
+  children: ComponentNode[];
+}
+```
+
+---
+
+### `getBrowserEntryScript()`
+
+Returns the pre-built browser IIFE bundle as a string. Use this to inject the Scope runtime into a Playwright page manually — useful in Vite-based setups or when you need to inject it outside of the fixture.
+
+```typescript
+import { getBrowserEntryScript } from '@agent-scope/playwright';
+
+// In a Playwright globalSetup or a manual test:
+const script = getBrowserEntryScript();
+await page.addInitScript({ content: script });
+```
+
+The bundle is searched in:
+1. `dist/browser-bundle.iife.js` (relative to the package's dist directory, when running from an installed package)
+2. `../dist/browser-bundle.iife.js` (when running from source)
+
+Throws with a clear message if the bundle is not found, instructing you to run `bun run build`.
+
+**Why use this instead of `{ path: bundlePath }` directly?**
+
+`getBrowserEntryScript()` returns the bundle content as a string, which is required when:
+- You cannot resolve the bundle file path reliably (e.g. in bundled test environments)
+- You need to modify or prefix the script before injection
+- You want to inject into multiple pages without file-path resolution per page
+
+---
+
+### `evaluateCapture(page)` / `captureUntilStable(page, stableMs, timeoutMs, lightweight?)`
+
+Low-level capture utilities (exported from `capture-utils.ts`).
+
+```typescript
+import { evaluateCapture, captureUntilStable, countNodes } from '@agent-scope/playwright';
+```
+
+**`evaluateCapture(page)`** — single capture with retry logic.
+
+Calls `page.evaluate(() => window.__SCOPE_CAPTURE_JSON__())`. Retries up to `MAX_RETRIES` (3) times on "Execution context was destroyed" errors (caused by navigations racing with `evaluate`). Each retry waits `RETRY_DELAY_MS` (500 ms). Non-retriable errors are re-thrown immediately.
+
+```typescript
+// Succeeds after 1 context-destroyed error:
+let callCount = 0;
+const page = makePage(async () => {
+  if (++callCount === 1) throw new Error('Execution context was destroyed');
+  return JSON.stringify(report);
+});
+const result = await evaluateCapture(page); // callCount === 2
+```
+
+**`captureUntilStable(page, stableMs, timeoutMs, lightweight?)`** — stability polling.
+
+Polls `evaluateCapture` every `POLL_INTERVAL_MS` (300 ms). Returns when the component node count (via `countNodes(report.tree)`) has been unchanged for `stableMs` ms. On timeout, returns the last successful capture instead of throwing.
+
+```typescript
+// Tree grows then stabilises at 5 nodes:
+const result = await captureUntilStable(page, 500, 10000);
+// countNodes(result.tree) === 5
+```
+
+When `lightweight: true`, polls with `evaluateLightweightCapture` (calls `__SCOPE_CAPTURE_JSON__({ lightweight: true })`) and performs a single full capture once stability is confirmed.
+
+**`countNodes(node)`** — recursive node counter.
+
+```typescript
+countNodes(makeNode(1));
+// → 1
+
+countNodes(makeNode(1, [makeNode(2, [makeNode(4), makeNode(5)]), makeNode(3)]));
+// → 5
+```
+
+---
+
+### `loadTrace(rawJson)` / `generateTest(trace, options?)`
+
+```typescript
+import { loadTrace, generateTest } from '@agent-scope/playwright';
+
+// Parse a raw PageReport JSON string into a CaptureTrace:
+const trace = loadTrace(fs.readFileSync('capture.json', 'utf-8'));
+// trace.report: PageReport
+// trace.capturedAt: number (Date.now() at load time)
+
+// Generate a Playwright test skeleton:
+const source = generateTest(trace, {
+  description: 'Button renders in primary variant',
+  outputPath: 'button.spec.ts',
+});
+// Returns a TypeScript test file string
+```
+
+---
+
+## Real test payloads
+
+### Basic capture (from `fixture.test.ts`)
+
+```typescript
+test('captures React tree from basic-tree fixture', async ({ scope, page }) => {
+  await page.goto('http://localhost:5173');
+  const report = await scope.capture();
+
+  expect(report.url).toContain('localhost:5173');
+  expect(typeof report.timestamp).toBe('number');
+  expect(report.tree.name).toBeTruthy();
+  expect(Array.isArray(report.errors)).toBe(true);
+  expect(report.errors).toHaveLength(0);  // no intentional errors in basic-tree fixture
+  expect(report.route).toBeNull();
+});
+```
+
+### `captureUrl` shorthand (from `fixture.test.ts`)
+
+```typescript
+test('captureUrl navigates and captures', async ({ scope }) => {
+  const report = await scope.captureUrl('http://localhost:5173');
+  expect(report.url).toContain('localhost:5173');
+  expect(report.tree.children.length).toBeGreaterThanOrEqual(0);
+});
+```
+
+### Context-destroyed retry (from `capture-utils.test.ts`)
+
+```typescript
+// evaluateCapture retries once on context-destroyed, then succeeds:
+let callCount = 0;
+const page = makePage(async () => {
+  if (++callCount === 1) {
+    throw new Error('Execution context was destroyed, most likely because of a navigation.');
+  }
+  return JSON.stringify(report);
+});
+
+const result = await evaluateCapture(page);
+// callCount === 2
+expect(result.url).toBe(report.url);
+```
+
+### Stability polling (from `capture-utils.test.ts`)
+
+```typescript
+// Tree grows across captures then stabilises at 5 nodes:
+const reports = [
+  makeReport(makeNode(1)),                                          // 1 node
+  makeReport(makeNode(1, [makeNode(2), makeNode(3)])),             // 3 nodes
+  makeReport(makeNode(1, [makeNode(2, [makeNode(4)]),
+                          makeNode(3, [makeNode(5)])])),           // 5 nodes
+  // ... same 5-node tree repeats → stable
+];
+
+const result = await captureUntilStable(page, 500, 10000);
+// countNodes(result.tree) === 5
+```
+
+### Timeout: returns last capture without throwing (from `capture-utils.test.ts`)
+
+```typescript
+// stableMs > timeoutMs: forced timeout
+const resultPromise = captureUntilStable(page, 5000, 500);
+await vi.advanceTimersByTimeAsync(2000);
+// resolves (not rejects) with a PageReport
+await expect(resultPromise).resolves.toBeDefined();
+```
+
+---
+
+## Configuration examples
+
+### Standard Playwright config
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: { baseURL: 'http://localhost:5173' },
+  webServer: { command: 'bun run dev', port: 5173 },
+});
+```
+
+```typescript
+// tests/scope.spec.ts
+import { test, expect } from '@agent-scope/playwright';
+
+test('component tree is stable after data load', async ({ scope, page }) => {
+  await page.goto('/dashboard');
+  const report = await scope.capture({ waitForStable: true, stableMs: 1000 });
+  expect(report.tree.name).toBe('App');
+});
+```
+
+### Manual injection (no fixture)
+
+```typescript
+import { getBrowserEntryScript } from '@agent-scope/playwright';
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.addInitScript({ content: getBrowserEntryScript() });
+await page.goto('http://localhost:5173');
+
+const json = await page.evaluate(() => window.__SCOPE_CAPTURE_JSON__());
+const report = JSON.parse(json);
+await browser.close();
+```
+
+---
+
+## Used by
+
+- `@agent-scope/cli` — uses `getBrowserEntryScript()` to inject the browser bundle into Vite dev-server pages during `scope capture` runs
+- CI E2E test suites — `test` and `expect` replace the base Playwright exports for all Scope integration tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-scope/playwright",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "description": "Playwright integration for Scope — replay traces and generate tests",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,8 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -31,8 +32,8 @@
   },
   "dependencies": {
     "@playwright/test": "^1.58.2",
-    "@agent-scope/core": "1.17.0",
-    "@agent-scope/runtime": "1.17.0"
+    "@agent-scope/core": "1.17.2",
+    "@agent-scope/runtime": "1.17.2"
   },
   "devDependencies": {
     "@types/node": "*",