test-proxy-recorder 0.3.5 → 0.3.8

package/README.md

@@ -5,9 +5,9 @@
 
 Fast, deterministic Playwright tests without maintaining manual mocks.
 
-An HTTP proxy that records real API responses during test runs and replays them on CI -- no backend required. Instead of hand-writing mock fixtures, just run your tests once against the real API and commit the recordings. Supports Next.js and SSR.
+Records real API responses during test runs and replays them on CI — no backend required. Supports two recording mechanisms depending on where your requests originate:
 
-```
+```text
                         Record mode                          Replay mode
 
   Browser/App ──> Proxy ──> Real API        Browser/App ──> Proxy ──> Disk
@@ -16,83 +16,202 @@ An HTTP proxy that records real API responses during test runs and replays them
                          (.mock.json)                              (.mock.json)
 ```
 
+| Mechanism | What it records | Use case |
+| --------- | --------------- | -------- |
+| **Proxy** (`.mock.json`) | Server-side requests (SSR fetches from Next.js etc.) | Full-stack apps where the server calls the API |
+| **HAR** (`.har`) | Browser-side requests (browser `fetch`, extensions, SPAs) | SPAs, Chrome extensions, 3rd-party APIs |
+
+Both can be used together or independently.
+
+```text
+  Server-side (proxy)                    Browser-side (HAR)
+
+  Next.js SSR ──> Proxy ──> Real API     Browser ──> HAR intercept ──> Real API
+                    │                                      │
+                    └──> .mock.json                        └──> .har
+```
+
+## Contents
+
+- [Why](#why)
+- [Full-stack (SSR + browser) Quick Start](#full-stack-ssr--browser-quick-start)
+- [Browser-only / SPA / Extension Quick Start](#browser-only--spa--extension-quick-start)
+- [CLI](#cli)
+- [Example Apps](#example-apps)
+- [Playwright Integration](#playwright-integration)
+- [Next.js Integration](#nextjs-integration)
+- [Control Endpoint](#control-endpoint)
+- [API Reference](#api-reference)
+- [Next.js 16](#nextjs-16)
+- [FAQ](#faq)
+- [AI Agent Skills](#ai-agent-skills)
+- [Roadmap](#roadmap)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Why
 
-- **No backend on CI** -- record once against the real API, replay on every CI run
-- **No manual mocks** -- capture real interactions instead of hand-writing fixtures
-- **SSR support** -- records server-side requests from Next.js and similar frameworks
-- **Deterministic** -- same responses every time, no flaky network
-- **WebSocket support** -- records and replays WebSocket connections
+- **No backend on CI** — record once against the real API, replay on every CI run
+- **No manual mocks** — capture real interactions instead of hand-writing fixtures
+- **SSR support** — records server-side requests from Next.js and similar frameworks
+- **Browser-side support** — records browser `fetch` calls, Chrome extension API calls, analytics, etc.
+- **Deterministic** — same responses every time, no flaky network
+- **WebSocket support** — records and replays WebSocket connections
 
-## Quick Start
+---
 
-### 1. Install
+## Full-stack (SSR + browser) Quick Start
 
-```bash
-npm install --save-dev test-proxy-recorder
-```
+For apps like Next.js where both the server AND the browser make API calls, use both mechanisms together.
 
-### 2. Add scripts to `package.json`
+### 1. Add scripts to `package.json`
 
 ```json
 {
   "scripts": {
-    "proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --dir ./e2e/recordings"
+    "proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --dir ./e2e/recordings",
+    "dev:proxy": "concurrently \"npm run proxy\" \"INTERNAL_API_URL=http://localhost:8100 npm run dev\"",
+    "serve:proxy": "concurrently \"npm run proxy\" \"INTERNAL_API_URL=http://localhost:8100 npm run serve\""
   }
 }
 ```
 
-> **Tip:** Use `concurrently` to run proxy + app together.
-> `INTERNAL_API_URL` is the env var your app uses for the API base URL -- point it at the proxy instead of the real backend. Use proxy address for dev/test and real backend for production environment.
-> Replace it with whatever env var your app uses (e.g. `API_URL`, `NEXT_PUBLIC_API_URL`).
->
-> ```json
-> {
->   "scripts": {
->     "proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --dir ./e2e/recordings",
->     "dev:proxy": "concurrently \"npm run proxy\" \"INTERNAL_API_URL=http://localhost:8100 npm run dev\"",
->     "serve:proxy": "concurrently \"npm run proxy\" \"INTERNAL_API_URL=http://localhost:8100 npm run serve\""
->   }
-> }
-> ```
+> `INTERNAL_API_URL` is the env var your app uses for the API base URL — point it at the proxy instead of the real backend. Replace it with whatever env var your app uses (e.g. `API_URL`, `NEXT_PUBLIC_API_URL`).
 >
 > **Next.js note:** Prefer `build` + `serve` over `dev` for recording/replaying tests. The Next.js dev server is slow and can cause timeouts or flaky recordings.
 
-### 3. Write a test
+### 2. Write a test
 
 ```typescript
 import { test, expect } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-test('homepage loads', async ({ page }, testInfo) => {
-  await playwrightProxy.before(page, testInfo, 'record'); // first run: record
-  // await playwrightProxy.before(page, testInfo, 'replay'); // later: replay
+// SSR requests (server → proxy) are recorded to .mock.json.
+// Browser requests to the proxy URL are also covered.
+const CLIENT_SIDE_URL = /localhost:8100/;
 
+// Change to 'record' to update recordings.
+const MODE = 'replay' as const;
+
+test.beforeEach(async ({ page }, testInfo) => {
+  await playwrightProxy.before(page, testInfo, MODE, { url: CLIENT_SIDE_URL });
+});
+
+test('homepage loads', async ({ page }) => {
   await page.goto('/');
   await expect(page.getByText('Welcome')).toBeVisible();
 });
 ```
 
-### 4. Run
-
-Start the proxy + app first (e.g. `npm run serve:proxy`), then run tests in a separate terminal:
+### 3. Record
 
 ```bash
-# Terminal 1 -- start proxy and app
+# Terminal 1
 npm run serve:proxy
 
-# Terminal 2 -- run tests
+# Terminal 2 — .mock.json and .har files are written automatically
 npx playwright test
 ```
 
-### 5. Commit recordings to git
+### 4. Switch to replay and commit
 
 ```bash
-# .gitattributes -- collapse long mock files in PR diffs
-/e2e/recordings/** binary
+git add e2e/recordings/
+git commit -m "add e2e recordings"
 ```
 
+---
+
+## Browser-only / SPA / Extension Quick Start
+
+If your app or extension makes API calls entirely from the browser (no SSR), you only need the HAR mechanism. No proxy backend is required for the actual recording — the proxy process just provides session management.
+
+### 1. Install
+
+```bash
+npm install --save-dev test-proxy-recorder
+```
+
+### 2. Add the proxy to `playwright.config.ts`
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  webServer: {
+    command: 'test-proxy-recorder https://api.example.com --port 8100 --dir ./e2e/recordings',
+    url: 'http://localhost:8100/__control',
+    reuseExistingServer: true,
+  },
+});
+```
+
+> The proxy target (`https://api.example.com`) does not matter for browser-only recording — it is only used if server-side (SSR) requests also need to be proxied. The proxy process must run so its `/__control` endpoint is available for session management.
+
+### 3. Write a fixture
+
+```typescript
+// e2e/fixtures.ts
+import { test as base, type Page, type BrowserContext } from '@playwright/test';
+import { playwrightProxy } from 'test-proxy-recorder';
+
+// Match the external API domain your browser makes requests to.
+// In record mode these requests go to the real API and are saved.
+// In replay mode they are served from disk — no network needed.
+const CLIENT_SIDE_URL = /api\.example\.com/;
+
+// Change to 'record' to hit the real API and update recordings.
+const MODE = 'replay' as const;
+
+export const test = base.extend<{ page: Page }>({
+  page: async ({ context }, use, testInfo) => {
+    const page = await context.newPage();
+    await playwrightProxy.before(page, testInfo, MODE, { url: CLIENT_SIDE_URL });
+    await use(page);
+  },
+});
+```
+
+### 4. Write a test
+
+```typescript
+// e2e/my.test.ts
+import { test, expect } from './fixtures';
+
+test('homepage loads', async ({ page }) => {
+  await page.goto('https://myapp.com/');
+  await expect(page.getByText('Welcome')).toBeVisible();
+});
+```
+
+### 5. Record — run once against the real API
+
+```bash
+# In fixtures.ts: const MODE = 'record' as const;
+npx playwright test
+# .har files are written to e2e/recordings/ automatically
+```
+
+### 6. Switch to replay and commit
+
+```bash
+# In fixtures.ts: const MODE = 'replay' as const;
+git add e2e/recordings/
+git commit -m "add e2e recordings"
+```
+
+CI now runs without any network access.
+
 > Do **not** add `e2e/recordings` to `.gitignore`. Recordings must be in git for CI replay.
+>
+> Add this to `.gitattributes` to collapse large recording files in PR diffs:
+>
+> ```text
+> /e2e/recordings/** binary
+> ```
 
 ---
 
@@ -114,21 +233,49 @@ test-proxy-recorder http://localhost:8000
 test-proxy-recorder http://localhost:8000 --port 8100 --dir ./mocks
 ```
 
+---
+
+## Example Apps
+
+Two full working examples live in [`apps/`](https://github.com/asmyshlyaev177/test-proxy-recorder/tree/master/apps) — one for each recording mechanism. Each has its own README with the full setup and record/replay workflow.
+
+### Next.js 16 — server-side (proxy / `.mock.json`)
+
+[`apps/example-nextjs16`](https://github.com/asmyshlyaev177/test-proxy-recorder/tree/master/apps/example-nextjs16) — a Next.js 16 todo app with a mock backend, proxy, and Playwright e2e tests. Records both SSR fetches (`.mock.json`) and browser fetches (`.har`). See its [README](https://github.com/asmyshlyaev177/test-proxy-recorder/blob/master/apps/example-nextjs16/README.md).
+
+### Chrome extension — browser-side (HAR / `.har`)
+
+[`apps/example-extension`](https://github.com/asmyshlyaev177/test-proxy-recorder/tree/master/apps/example-extension) — a real Chrome extension that calls X/Twitter's API from a content script; browser requests are recorded to `.har` and replayed offline, with no live API or account needed on CI. See its [README](https://github.com/asmyshlyaev177/test-proxy-recorder/blob/master/apps/example-extension/README.md).
+
+---
+
 ## Playwright Integration
 
-### Basic pattern
+<details>
+<summary>Show details</summary>
 
-```typescript
-import { test } from '@playwright/test';
-import { playwrightProxy } from 'test-proxy-recorder';
+### `playwrightProxy.before(page, testInfo, mode, options?)`
 
-test('my test', async ({ page }, testInfo) => {
-  await playwrightProxy.before(page, testInfo, 'replay');
-  // ... test code
+Call this at the start of each test (or in a `beforeEach` / page fixture). It sets the proxy mode for the session and, if `url` is provided, sets up HAR recording for browser-side requests.
+
+```typescript
+await playwrightProxy.before(page, testInfo, 'replay', {
+  // url: pattern for browser-side requests to record/replay via HAR.
+  //
+  // Use the ACTUAL external API domain — not the proxy URL.
+  // Examples:
+  //   /api\.example\.com/           — your own API
+  //   /x\.com/                      — record all x.com browser traffic (Chrome extension tests)
+  //   /cognito-.*amazonaws\.com/    — 3rd-party auth
+  url: /api\.example\.com/,
 });
 ```
 
-`playwrightProxy.before()` sets the proxy mode, attaches a session header (`x-test-rcrd-id`), and registers cleanup on page close. Recording filenames are derived from test names (`"create a user"` -> `create-a-user.mock.json`).
+**`url` pattern:** matches the real external domain that the browser calls. In record mode requests go to the real API and are saved to a `.har` file. In replay mode they are served from that file — no network needed. This pattern does **not** point to the proxy (`localhost:8100`).
+
+**Exception — full-stack apps:** when the browser also calls `localhost:8100` (because the frontend is configured with the proxy URL as its API base), use `/localhost:8100/` as the pattern.
+
+Recording filenames are derived from test names (`"create a user"` → `create-a-user.mock.json` / `.har`).
 
 ### Global teardown (recommended)
 
@@ -148,27 +295,26 @@ export default defineConfig({
 });
 ```
 
-### Client-side recording (3rd party APIs)
+### Recording files
 
-For browser-side requests that don't go through the proxy (e.g. AWS Cognito, analytics), use HAR recording:
-
-```typescript
-await playwrightProxy.before(page, testInfo, 'replay', {
-  url: /cognito-.*amazonaws\.com|\.stream-io-api\.com/,
-});
+```text
+e2e/recordings/
+  my-test.mock.json   # server-side (proxy) — SSR fetches
+  my-test.har         # client-side (HAR)   — browser fetches
 ```
 
-Recordings are stored alongside server-side files:
+</details>
 
-```
-e2e/recordings/
-  my-test.mock.json   # server-side (proxy)
-  my-test.har         # client-side (HAR)
-```
+---
 
 ## Next.js Integration
 
-The proxy identifies sessions via a custom header. For SSR requests to carry this header, use one of:
+<details>
+<summary>Show details</summary>
+
+SSR frameworks like Next.js make server-side `fetch` calls that go through the proxy without a browser context. The proxy identifies which session those requests belong to via the `x-test-rcrd-id` header — the same header `playwrightProxy.before()` sets on the browser `page`. This header is **only required for SSR** — for browser-only tests the proxy falls back to the globally set session automatically.
+
+For SSR requests to carry this header, use one of:
 
 ### Middleware (recommended)
 
@@ -198,8 +344,15 @@ const res = await fetch('http://localhost:8100/api/data', {
 });
 ```
 
+</details>
+
+---
+
 ## Control Endpoint
 
+<details>
+<summary>Show details</summary>
+
 The proxy exposes `/__control` for programmatic mode switching.
 
 ```bash
@@ -220,8 +373,15 @@ interface ControlRequest {
 }
 ```
 
+</details>
+
+---
+
 ## API Reference
 
+<details>
+<summary>Show details</summary>
+
 ### `playwrightProxy`
 
 ```typescript
@@ -230,7 +390,7 @@ const playwrightProxy: {
     page: Page,
     testInfo: TestInfo,
     mode: 'record' | 'replay' | 'transparent',
-    options?: number | { url?: string | RegExp; timeout?: number }
+    options?: { url?: string | RegExp; timeout?: number }
   ): Promise<void>;
 
   teardown(): Promise<void>;
@@ -258,17 +418,15 @@ function createHeadersWithRecordingId(
 ): Record<string, string>;
 ```
 
-## Typical Workflow
+</details>
 
-```
-1. Record       start proxy + app + backend, run tests with 'record' mode
-2. Commit       git add e2e/recordings/
-3. Replay       start proxy + app (no backend), run tests with 'replay' mode
-4. Update       re-record when API changes, commit new recordings
-```
+---
 
 ## Next.js 16
 
+<details>
+<summary>Show details</summary>
+
 Next.js 16 uses `proxy.ts` as the middleware entry point (replaces `middleware.ts`). Place it at the project root alongside `next.config.ts`:
 
 ```typescript
@@ -277,7 +435,7 @@ import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
 import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
 
-export function middleware(request: NextRequest) {
+export function proxy(request: NextRequest) {
   const response = NextResponse.next();
   setNextProxyHeaders(request, response);
   return response;
@@ -300,62 +458,99 @@ export const config = {
 }
 ```
 
-## Example App
+</details>
+
+---
 
-[`apps/example-nextjs16`](apps/example-nextjs16) is a full working example: a Next.js 16 todo app wired up with a mock backend, proxy, and Playwright e2e tests in record/replay mode.
+## FAQ
 
-```text
-apps/example-nextjs16/
-  app/                  Next.js pages and components
-  mock-backend/         Standalone Node.js HTTP server (port 3002)
-  e2e/                  Playwright tests + recordings
-  proxy.ts              Next.js 16 middleware — forwards session headers to SSR fetches
+<details>
+<summary><strong>My parallel replay tests sometimes hit the real backend — why?</strong></summary>
+
+You're likely calling `playwrightProxy.teardown()` in a per-test hook. It sets the **global** proxy mode to `transparent`, and with `fullyParallel: true` each Playwright worker runs its own `test.afterAll`. If a fast test finishes and calls `teardown()` while a slower test is still running, the proxy flips to transparent mid-test and the remaining requests are forwarded to the real backend instead of being replayed.
+
+```typescript
+// ❌ breaks parallel replay — teardown() affects all sessions globally
+test.afterAll(async () => {
+  await playwrightProxy.teardown();
+});
 ```
 
-**Three-service architecture:**
+**Fix:** omit `test.afterAll`. Session cleanup is automatic via `context.on('close')` → `cleanupSession()`. Use a [global teardown](https://playwright.dev/docs/test-global-setup-teardown) only if you need to reset the proxy after the entire run.
+
+</details>
+
+<details>
+<summary><strong>Should I commit recordings to git?</strong></summary>
+
+Yes. Recordings must be in git so CI can replay them with no network — do **not** add `e2e/recordings` to `.gitignore`. To keep large recording files from bloating PR diffs, mark them binary in `.gitattributes`:
 
 ```text
-Browser  ──> Proxy (8100) ──> Mock Backend (3002)
-Next.js SSR ──> Proxy (8100) ──> Mock Backend (3002)
+/e2e/recordings/** binary
 ```
 
-Start everything and run the record/replay cycle:
+</details>
 
-```bash
-# Start all services (mock backend + proxy + Next.js)
-pnpm --filter example-nextjs16 start:all
+<details>
+<summary><strong>Does the proxy <code>&lt;target-url&gt;</code> matter for browser-only (HAR) recording?</strong></summary>
 
-# Record tests (run against live services, save to e2e/recordings/)
-pnpm --filter example-nextjs16 test:e2e:record
+No. For browser-only recording the target is irrelevant — the proxy process just needs to run so its `/__control` endpoint is available for session management. The target only matters when server-side (SSR) requests are also routed through the proxy.
 
-# Replay tests (no backend needed — served from recordings)
-pnpm --filter example-nextjs16 test:e2e
-```
+</details>
 
-## Parallel Replay: Do Not Call `teardown()` Per-Test
+<details>
+<summary><strong>Can I record against the Next.js dev server?</strong></summary>
 
-`playwrightProxy.teardown()` sets the **global** proxy mode to `transparent`. With `fullyParallel: true`, each Playwright worker runs its own `test.afterAll`. If a fast test completes and calls `teardown()` while a slower test (e.g., one with more interaction steps) is still running, the proxy switches to transparent mid-test. The remaining requests are forwarded to the real backend instead of being replayed, causing failures.
+Prefer `next build` + `next start` over `next dev` for recording and replaying. The dev server is slow and can cause timeouts or flaky recordings.
 
-**Wrong:**
+</details>
 
-```typescript
-// ❌ breaks parallel replay — teardown() affects all sessions globally
-test.afterAll(async () => {
-  await playwrightProxy.teardown();
-});
+<details>
+<summary><strong>How do I update a recording?</strong></summary>
+
+Re-run in record mode (set `MODE = 'record'` in your fixture, or `RECORD_MODE=1`) against the real API, then switch back to replay and commit the updated files in `e2e/recordings/`.
+
+</details>
+
+---
+
+## AI Agent Skills
+
+If you use an AI coding agent (Claude Code, Cursor, Copilot, etc.), install the skills for this library so the agent generates correct setup code:
+
+```bash
+npx @tanstack/intent@latest install
 ```
 
-**Correct:** omit `test.afterAll`. Session cleanup is automatic via `context.on('close')` → `cleanupSession()`. Use a [global teardown](https://playwright.dev/docs/test-global-setup-teardown) if you need to reset the proxy after a full test run.
+This adds `test-proxy-recorder` skills to your project. The agent will then know the correct proxy/fixture setup, record vs. replay workflow, and Next.js SSR header patterns without needing guidance.
+
+---
+
+## Roadmap
+
+First-class integrations on the way:
+
+- **TanStack Start**
+- **Remix**
+- **Vite + SSR**
+
+Need one sooner, or a different framework? [Open an issue](https://github.com/asmyshlyaev177/test-proxy-recorder/issues).
+
+---
 
 ## Requirements
 
-- Node.js >= 22.0.0
+- Node.js >= 20.0.0
 - @playwright/test >= 1.0.0 (peer dependency)
 
+---
+
 ## Contributing
 
 Contributions welcome! Please submit a Pull Request.
 
+---
+
 ## License
 
 MIT

package/dist/{index-BlBWqSE4.d.cts → index-BloXCw69.d.cts}

@@ -42,6 +42,10 @@ interface WebSocketRecording {
     messages: WebSocketMessage[];
     timestamp: string;
     key: string;
+    /** Client handshake headers (minus WebSocket internals like sec-websocket-key) */
+    headers?: http.IncomingHttpHeaders;
+    /** Subprotocol negotiated with the backend (from Sec-WebSocket-Protocol) */
+    protocol?: string;
 }
 interface RecordingSession {
     id: string;

package/dist/{index-BlBWqSE4.d.ts → index-BloXCw69.d.ts}

@@ -42,6 +42,10 @@ interface WebSocketRecording {
     messages: WebSocketMessage[];
     timestamp: string;
     key: string;
+    /** Client handshake headers (minus WebSocket internals like sec-websocket-key) */
+    headers?: http.IncomingHttpHeaders;
+    /** Subprotocol negotiated with the backend (from Sec-WebSocket-Protocol) */
+    protocol?: string;
 }
 interface RecordingSession {
     id: string;