test-proxy-recorder 0.3.4 → 0.3.6

package/README.md

@@ -3,702 +3,553 @@
 [![npm](https://img.shields.io/npm/v/test-proxy-recorder.svg)](https://www.npmjs.com/package/test-proxy-recorder)
 [![license](https://img.shields.io/github/license/asmyshlyaev177/test-proxy-recorder.svg?style=flat-square)](https://github.com/asmyshlyaev177/test-proxy-recorder/blob/master/LICENSE)
 
-HTTP proxy server for recording and replaying network requests in testing. Works seamlessly with Playwright and other testing frameworks.
+Fast, deterministic Playwright tests without maintaining manual mocks.
 
-## BETA VERSION
+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:
 
-## Features
-
-- **Fast CI/CD Tests**: Record API responses once with real backend, replay them on CI/CD without backend
-- **Fast Workflow**: Record real interactions with API instead of mocking every request manually
-- **Server Side Rendering**: Can record SSR requests from JS frameworks like Next.js
-- **Deterministic Tests**: Same responses every time, no flaky network issues, no need to wire up the whole Backend API for testing
-- **WebSocket Support**: Records and replays WebSocket connections
-
-## Table of Contents
+```text
+                        Record mode                          Replay mode
 
-- [How It Works](#how-it-works)
-- [Complete Setup Guide](#complete-setup-guide)
-- [CLI Usage](#cli-usage)
-- [Playwright Integration](#playwright-integration)
-- [Next.js Integration](#nextjs-integration)
-- [Control Endpoint](#control-endpoint)
-- [Typical Workflow](#typical-workflow)
-- [Recording Format](#recording-format)
-- [Troubleshooting](#troubleshooting)
-- [API Reference](#api-reference)
+  Browser/App ──> Proxy ──> Real API        Browser/App ──> Proxy ──> Disk
+                    │                                         │
+                    └──> saves to disk                        └──> serves saved responses
+                         (.mock.json)                              (.mock.json)
+```
 
-## How It Works
+| 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 |
 
-The proxy server runs continuously and can switch between three modes per test:
+Both can be used together or independently.
 
-### 1. Transparent Mode (Default)
+```text
+  Server-side (proxy)                    Browser-side (HAR)
 
-Passes requests through to the backend without recording or replaying.
+  Next.js SSR ──> Proxy ──> Real API     Browser ──> HAR intercept ──> Real API
+                    │                                      │
+                    └──> .mock.json                        └──> .har
+```
 
-### 2. Record Mode
+## Contents
 
-Captures all HTTP requests/responses and WebSocket messages to disk. Each test gets its own recording file based on the test name.
+- [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)
 
-### 3. Replay Mode
+---
 
-Replays previously recorded responses from disk instead of hitting the real API. Perfect for fast, deterministic tests.
+## Why
 
-## Complete Setup Guide
+- **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
 
-### Step 1: Install Package
+---
 
-```bash
-npm install --save-dev test-proxy-recorder
-```
+## Full-stack (SSR + browser) Quick Start
 
-### Step 2: Add NPM Scripts
+For apps like Next.js where both the server AND the browser make API calls, use both mechanisms together.
 
-Add 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\""
   }
 }
 ```
 
-**RECOMMENDED**: Use `concurrently` to run proxy and 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. 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.
 
-```bash
-npm install --save-dev concurrently
-```
+### 2. Write a test
 
-```json
-{
-  "scripts": {
-    "proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --dir ./e2e/recordings",
-    "dev:proxy": "concurrently -n \"proxy,app\" -c \"blue,green\" \"npm run proxy\" \"INTERNAL_API_URL=http://localhost:8100 npm run dev\""
-  }
-}
-```
+```typescript
+import { test, expect } from '@playwright/test';
+import { playwrightProxy } from 'test-proxy-recorder';
 
-### Step 3: Configure Git for Recordings
+// SSR requests (server → proxy) are recorded to .mock.json.
+// Browser requests to the proxy URL are also covered.
+const CLIENT_SIDE_URL = /localhost:8100/;
 
-**CRITICAL**: Recordings must be committed to git for CI/CD replay.
+// Change to 'record' to update recordings.
+const MODE = 'replay' as const;
 
-Create or update your `.gitattributes` file:
+test.beforeEach(async ({ page }, testInfo) => {
+  await playwrightProxy.before(page, testInfo, MODE, { url: CLIENT_SIDE_URL });
+});
 
-```gitattributes
-/e2e/recordings/** binary
+test('homepage loads', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.getByText('Welcome')).toBeVisible();
+});
 ```
 
-This marks recording files as binary, which causes long mock files to be collapsed/folded in Pull Request diffs for better readability.
+### 3. Record
 
-**DO NOT** add `e2e/recordings` to `.gitignore`. Recordings need to be versioned in git for CI/CD to use them.
+```bash
+# Terminal 1
+npm run serve:proxy
 
-**Note**: The recordings directory will be created automatically when you first record a test - no need to create it manually.
+# Terminal 2 — .mock.json and .har files are written automatically
+npx playwright test
+```
 
-### Step 4: Create Playwright Global Teardown (Recommended)
+### 4. Switch to replay and commit
 
-Create `e2e/global-teardown.ts`:
+```bash
+git add e2e/recordings/
+git commit -m "add e2e recordings"
+```
 
-```typescript
-import { playwrightProxy } from 'test-proxy-recorder';
+---
 
-async function globalTeardown() {
-  await playwrightProxy.teardown();
-}
+## 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.
 
-export default globalTeardown;
+### 1. Install
+
+```bash
+npm install --save-dev test-proxy-recorder
 ```
 
-Update `playwright.config.ts`:
+### 2. Add the proxy to `playwright.config.ts`
 
 ```typescript
 import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
-  testDir: './e2e',
-  globalTeardown: './e2e/global-teardown.ts',
-  // ... rest of config
+  webServer: {
+    command: 'test-proxy-recorder https://api.example.com --port 8100 --dir ./e2e/recordings',
+    url: 'http://localhost:8100/__control',
+    reuseExistingServer: true,
+  },
 });
 ```
 
-### Step 5: Create Example Test
+> 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.
 
-Create `e2e/example.spec.ts`:
+### 3. Write a fixture
 
 ```typescript
-import { test, expect } from '@playwright/test';
+// e2e/fixtures.ts
+import { test as base, type Page, type BrowserContext } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-test('example test with proxy', async ({ page }, testInfo) => {
-  // Set proxy mode: 'record' to capture, 'replay' to use recordings
-  // This automatically sets up page.on('close') for cleanup
-  await playwrightProxy.before(page, testInfo, 'replay');
+// 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/;
 
-  await page.goto('/');
-  await expect(page.getByText('Welcome')).toBeVisible();
+// 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);
+  },
 });
 ```
 
-### Step 6: Run Tests
-
-**First run (record mode)**:
+### 4. Write a test
 
 ```typescript
-await playwrightProxy.before(page, testInfo, 'record');
+// 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();
+});
 ```
 
-**Subsequent runs (replay mode)**:
+### 5. Record — run once against the real API
 
-```typescript
-await playwrightProxy.before(page, testInfo, 'replay');
+```bash
+# In fixtures.ts: const MODE = 'record' as const;
+npx playwright test
+# .har files are written to e2e/recordings/ automatically
 ```
 
-## CLI Usage
-
-### Basic Command
+### 6. Switch to replay and commit
 
 ```bash
-test-proxy-recorder <target-url> [options]
+# In fixtures.ts: const MODE = 'replay' as const;
+git add e2e/recordings/
+git commit -m "add e2e recordings"
 ```
 
-### CLI Options
+CI now runs without any network access.
 
-- `<target-url>` - Backend API URL (positional argument, required)
-- `--port, -p <number>` - Port to listen on (default: 8080)
-- `--dir, -d <path>` - Directory to store recordings (default: ./recordings)
-- `--help, -h` - Show help
+> 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
+> ```
 
-### Examples
-
-```bash
-# Basic usage
-test-proxy-recorder http://localhost:8000
+---
 
-# Custom port and recordings directory
-test-proxy-recorder http://localhost:8000 --port 8100 --dir ./mocks
+## CLI
 
-# Multiple targets (experimental)
-test-proxy-recorder http://localhost:8000 http://localhost:9000 --port 8100
+```bash
+test-proxy-recorder <target-url> [options]
 ```
 
-## Playwright Integration
+| Option         | Default        | Description                   |
+| -------------- | -------------- | ----------------------------- |
+| `<target-url>` | *(required)*   | Backend URL to proxy          |
+| `--port, -p`   | `8080`         | Proxy listen port             |
+| `--dir, -d`    | `./recordings` | Directory for recording files |
 
-### Session Identification
+```bash
+# Examples
+test-proxy-recorder http://localhost:8000
+test-proxy-recorder http://localhost:8000 --port 8100 --dir ./mocks
+```
 
-The proxy uses a **custom HTTP header** (`x-test-rcrd-id`) to identify recording sessions. This header is automatically set by the `playwrightProxy.before()` method and works seamlessly with Next.js and other server-side rendering frameworks.
+---
 
-**Cookie fallback**: For backward compatibility, the proxy also supports cookie-based session identification, but the custom header is preferred.
+## Example Apps
 
-### Basic Test Structure
+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.
 
-Every test using the proxy should follow this pattern:
+### Next.js 16 — server-side (proxy / `.mock.json`)
 
-```typescript
-import { test } from '@playwright/test';
-import { playwrightProxy } from 'test-proxy-recorder';
+[`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).
 
-test('test name', async ({ page }, testInfo) => {
-  // Set mode BEFORE test actions
-  // This automatically sets the recording ID header and cleanup handler
-  await playwrightProxy.before(page, testInfo, 'replay');
+### Chrome extension — browser-side (HAR / `.har`)
 
-  // Test code
-  await page.goto('/page');
-  // Test assertions...
-});
-```
+[`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).
 
-### Recording vs Replay
+---
 
-```typescript
-import { test } from '@playwright/test';
-import { playwrightProxy } from 'test-proxy-recorder';
+## Playwright Integration
 
-// Recording mode - captures API responses
-test('create user', async ({ page }, testInfo) => {
-  await playwrightProxy.before(page, testInfo, 'record');
+<details>
+<summary>Show details</summary>
 
-  await page.goto('/users/new');
-  await page.fill('[name="username"]', 'testuser');
-  await page.click('button[type="submit"]');
-});
+### `playwrightProxy.before(page, testInfo, mode, options?)`
 
-// Replay mode - uses recorded responses
-test('create user', async ({ page }, testInfo) => {
-  await playwrightProxy.before(page, testInfo, 'replay');
+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.
 
-  await page.goto('/users/new');
-  await page.fill('[name="username"]', 'testuser');
-  await page.click('button[type="submit"]');
+```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/,
 });
 ```
 
-### Test Naming
-
-Recording files are auto-generated from test names:
+**`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`).
 
-- Test: `"create a user"`
-- File: `create-a-user.mock.json`
+**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.
 
-**Important**: Keep test names stable for replay to work correctly.
+Recording filenames are derived from test names (`"create a user"` → `create-a-user.mock.json` / `.har`).
 
-### Global Teardown (Recommended)
-
-Create `e2e/global-teardown.ts`:
+### Global teardown (recommended)
 
 ```typescript
+// e2e/global-teardown.ts
 import { playwrightProxy } from 'test-proxy-recorder';
 
-async function globalTeardown() {
+export default async function globalTeardown() {
   await playwrightProxy.teardown();
 }
-
-export default globalTeardown;
 ```
 
-Update `playwright.config.ts`:
-
 ```typescript
-import { defineConfig } from '@playwright/test';
-
+// playwright.config.ts
 export default defineConfig({
-  testDir: './e2e',
   globalTeardown: './e2e/global-teardown.ts',
-  // ... rest of config
-});
-```
-
-### Client-Side Recording for 3rd Party APIs
-
-For applications that make client-side requests to 3rd party services (e.g., AWS Cognito, Stream.io, analytics services), you can use client-side recording to capture these requests directly in the browser using Playwright's HAR (HTTP Archive) format.
-
-**Why use client-side recording?**
-- Server-side proxy cannot intercept requests made directly from the browser to external services
-- HAR files are a standard format supported by Playwright and browser dev tools
-- Automatically handles CORS and other browser-specific request behaviors
-
-**Example:**
-
-```typescript
-import { test } from '@playwright/test';
-import { playwrightProxy } from 'test-proxy-recorder';
-
-test('authentication flow', async ({ page }, testInfo) => {
-  // Record both server-side (via proxy) and client-side (via HAR) requests
-  await playwrightProxy.before(
-    page,
-    testInfo,
-    'replay',
-    {
-      // Client-side URL pattern using Playwright's format
-      url: /cognito-.*amazonaws\.com|\.stream-io-api\.com/,
-      timeout: 60000 // Optional: custom timeout
-    }
-  );
-
-  await page.goto('/login');
-  // Cognito authentication requests are recorded to HAR files
-  await page.fill('[name="email"]', 'user@example.com');
-  await page.click('button[type="submit"]');
 });
 ```
 
-**URL Pattern Options:**
-```typescript
-// RegExp pattern (recommended for multiple domains)
-{ url: /cognito-.*amazonaws\.com|\.stream-io-api\.com/ }
-
-// String glob pattern
-{ url: 'https://api.example.com/**' }
+### Recording files
 
-// Specific domain
-{ url: /api\.external-service\.com/ }
-```
-
-**Storage:**
-Client-side recordings are stored as HAR files alongside server-side recordings:
-```
+```text
 e2e/recordings/
-├── my-test.mock.json  # Server-side recordings (proxy)
-└── my-test.har        # Client-side recordings (browser)
+  my-test.mock.json   # server-side (proxy) — SSR fetches
+  my-test.har         # client-side (HAR)   — browser fetches
 ```
 
-**Recording vs Replay:**
-- **Record mode**: Creates/updates HAR file with actual responses from 3rd party services
-- **Replay mode**: Uses recorded HAR file, no network requests made to 3rd party services
+</details>
 
-**Note:** The recordings directory is automatically retrieved from the proxy server, ensuring both server-side and client-side recordings are stored in the same location.
+---
 
 ## Next.js Integration
 
-When testing Next.js applications with server-side rendering (SSR) or API routes, you need to ensure the recording ID header is forwarded to the proxy. The package provides helpers for this.
+<details>
+<summary>Show details</summary>
 
-### Option 1: Using Next.js Middleware (Recommended)
+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.
 
-Create or update `middleware.ts` in your Next.js project root:
+For SSR requests to carry this header, use one of:
+
+### Middleware (recommended)
 
 ```typescript
+// middleware.ts
 import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
 import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
 
 export function middleware(request: NextRequest) {
   const response = NextResponse.next();
-
-  // Forward the recording ID header during tests
-  // Only runs in non-production or when TEST_PROXY_RECORDER_ENABLED=true
-  setNextProxyHeaders(request, response);
-
+  setNextProxyHeaders(request, response); // no-op in production
   return response;
 }
 ```
 
-**Environment Variables:**
-- Automatically skipped when `NODE_ENV=production`
-- Can be explicitly enabled in production with `TEST_PROXY_RECORDER_ENABLED=true`
-
-### Option 2: Manual Header Forwarding in API Routes
-
-For API routes or server components, manually include the header in fetch requests:
+### Manual header forwarding
 
 ```typescript
-// app/api/data/route.ts
 import { headers } from 'next/headers';
 import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';
 
-export async function GET() {
-  const requestHeaders = await headers();
-
-  const response = await fetch('http://localhost:8100/api/data', {
-    headers: createHeadersWithRecordingId(requestHeaders, {
-      'Content-Type': 'application/json',
-    })
-  });
-
-  return Response.json(await response.json());
-}
+const res = await fetch('http://localhost:8100/api/data', {
+  headers: createHeadersWithRecordingId(await headers(), {
+    'Content-Type': 'application/json',
+  }),
+});
 ```
 
-### Option 3: Using getRecordingId Helper
+</details>
 
-For more control, extract the recording ID and use it manually:
-
-```typescript
-import { headers } from 'next/headers';
-import { getRecordingId, RECORDING_ID_HEADER } from 'test-proxy-recorder/nextjs';
-
-export async function GET() {
-  const recordingId = getRecordingId(await headers());
-
-  const response = await fetch('http://localhost:8100/api/data', {
-    headers: {
-      'Content-Type': 'application/json',
-      ...(recordingId && { [RECORDING_ID_HEADER]: recordingId })
-    }
-  });
-
-  return Response.json(await response.json());
-}
-```
+---
 
 ## Control Endpoint
 
-The proxy exposes a control endpoint at `/__control` for programmatic mode switching and configuration retrieval.
-
-### GET - Retrieve Proxy Configuration
+<details>
+<summary>Show details</summary>
 
-Get the current proxy configuration including recordings directory, mode, and active session ID.
+The proxy exposes `/__control` for programmatic mode switching.
 
-**Via HTTP:**
 ```bash
+# Get current state
 curl http://localhost:8100/__control
-```
-
-**Response:**
-```json
-{
-  "recordingsDir": "/path/to/e2e/recordings",
-  "mode": "replay",
-  "id": "my-test-1"
-}
-```
-
-**Via JavaScript:**
-```javascript
-const config = await fetch('http://localhost:8100/__control').then(r => r.json());
-console.log(config.recordingsDir); // "/path/to/e2e/recordings"
-console.log(config.mode);          // "replay"
-console.log(config.id);            // "my-test-1"
-```
-
-### POST - Switch Proxy Mode
-
-**Via HTTP:**
-```bash
-# Switch to record mode
-curl -X POST http://localhost:8100/__control \
-  -H "Content-Type: application/json" \
-  -d '{"mode": "record", "id": "my-test-1", "timeout": 30000}'
-
-# Switch to replay mode
-curl -X POST http://localhost:8100/__control \
-  -H "Content-Type: application/json" \
-  -d '{"mode": "replay", "id": "my-test-1"}'
 
-# Switch to transparent mode
+# Switch modes
 curl -X POST http://localhost:8100/__control \
   -H "Content-Type: application/json" \
-  -d '{"mode": "transparent"}'
-```
-
-**Via JavaScript:**
-```javascript
-await fetch('http://localhost:8100/__control', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    mode: 'record',
-    id: 'my-test-1',
-    timeout: 30000 // Optional: auto-reset after 30s
-  })
-});
+  -d '{"mode": "record", "id": "my-test-1"}'
 ```
 
-### Control Request Interface
-
 ```typescript
 interface ControlRequest {
   mode: 'transparent' | 'record' | 'replay';
-  id?: string;      // Recording ID, required for record/replay
-  timeout?: number; // Auto-reset timeout in ms (default: 120000)
-}
-
-interface ControlResponse {
-  recordingsDir: string;
-  mode: string;
-  id?: string;
+  id?: string;       // required for record/replay
+  timeout?: number;  // auto-reset timeout in ms (default: 120000)
 }
 ```
 
-## Typical Workflow
+</details>
 
-### Initial Recording
+---
 
-1. Start backend API: `npm run api`
-2. Start proxy and app: `npm run dev:proxy`
-3. Set test to `'record'` mode
-4. Run test: Recordings saved to `./e2e/recordings/` (directory created automatically)
-5. Commit `.mock.json` files to git
-6. Change mode to `'replay'`
+## API Reference
 
-### Running with Replay
+<details>
+<summary>Show details</summary>
 
-1. Start proxy and app: `npm run dev:proxy` (no backend needed!)
-2. Set test to `'replay'` mode
-3. Run test: Uses recorded responses
-4. Tests run fast without backend
+### `playwrightProxy`
 
-### Updating Recordings
+```typescript
+const playwrightProxy: {
+  before(
+    page: Page,
+    testInfo: TestInfo,
+    mode: 'record' | 'replay' | 'transparent',
+    options?: { url?: string | RegExp; timeout?: number }
+  ): Promise<void>;
 
-1. Start backend API
-2. Set test to `'record'` mode
-3. Run test: Overwrites existing recording
-4. Commit updated `.mock.json` file
+  teardown(): Promise<void>;
+};
+```
 
-## Recording Format
+### `setProxyMode`
 
-Recordings are stored in two formats depending on the recording type:
+```typescript
+function setProxyMode(
+  mode: 'record' | 'replay' | 'transparent',
+  id?: string,
+  timeout?: number
+): Promise<void>;
+```
 
-**Server-side recordings** (via proxy): JSON files with `.mock.json` extension
-**Client-side recordings** (via HAR): HTTP Archive files with `.har` extension
+### Next.js helpers (`test-proxy-recorder/nextjs`)
 
-```text
-e2e/recordings/
-├── create-a-user.mock.json       # Server-side API calls
-├── create-a-user.har             # Client-side 3rd party requests
-├── fetch-users-list.mock.json
-└── delete-user.mock.json
+```typescript
+function setNextProxyHeaders(request: NextRequest, response: NextResponse): void;
+function getRecordingId(headers: NextRequest | Headers): string | null;
+function createHeadersWithRecordingId(
+  headers: NextRequest | Headers,
+  additional?: Record<string, string>
+): Record<string, string>;
 ```
 
-Both file types use the same naming convention based on the test name, making it easy to identify which recordings belong to which test.
+</details>
 
-## Troubleshooting
+---
 
-### Proxy not responding
+## Next.js 16
 
-**Check if proxy is running**:
+<details>
+<summary>Show details</summary>
 
-```bash
-curl http://localhost:8100/__control
+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
+// proxy.ts  (Next.js 16 middleware convention)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
+
+export function proxy(request: NextRequest) {
+  const response = NextResponse.next();
+  setNextProxyHeaders(request, response);
+  return response;
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
 ```
 
-**Check port availability**:
+**package.json scripts** — start services from scripts, not from `playwright.config.ts`:
 
-```bash
-lsof -i :8100
+```json
+{
+  "scripts": {
+    "mock": "node mock-backend/server.mjs",
+    "proxy": "test-proxy-recorder http://localhost:3002 -p 8100 -d ./e2e/recordings",
+    "start:all": "concurrently \"pnpm mock\" \"pnpm proxy\" \"pnpm build && next start --port 3000\""
+  }
+}
 ```
 
-### No recordings saved
+</details>
 
-- Verify proxy mode is `'record'`
-- Check app is using proxy URL (`http://localhost:8100`)
-- Verify write permissions on recordings directory
-- Check proxy server logs for errors
+---
 
-### Test fails in replay mode
+## FAQ
 
-- Ensure recording exists for this test
-- Check test name hasn't changed
-- Verify recording file matches expected format
-- Re-record if API responses changed
+<details>
+<summary><strong>My parallel replay tests sometimes hit the real backend — why?</strong></summary>
 
-### Recordings not matching requests
+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.
 
-- Request URLs must match exactly
-- Headers may affect matching (configurable)
-- Query parameters must be in same order
-- Re-record to capture current API behavior
+```typescript
+// ❌ breaks parallel replay — teardown() affects all sessions globally
+test.afterAll(async () => {
+  await playwrightProxy.teardown();
+});
+```
 
+**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.
 
-## API Reference
+</details>
 
-### ProxyServer Class
+<details>
+<summary><strong>Should I commit recordings to git?</strong></summary>
 
-```typescript
-class ProxyServer {
-  constructor(targets: string[], recordingsDir: string);
-  async init(): Promise<void>;
-  listen(port: number): http.Server;
-}
+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
+/e2e/recordings/** binary
 ```
 
-### Playwright Integration
+</details>
 
-```typescript
-import { playwrightProxy, setProxyMode, RECORDING_ID_HEADER } from 'test-proxy-recorder';
-import type { Page } from '@playwright/test';
-
-// Client-side recording options
-interface ClientSideRecordingOptions {
-  /**
-   * URL pattern for client-side requests to record/replay
-   * Uses Playwright's native format (string or RegExp)
-   * Example: /cognito-.*amazonaws\.com|\.stream-io-api\.com/
-   * Example: 'https://api.example.com/**'
-   */
-  url?: string | RegExp;
-}
+<details>
+<summary><strong>Does the proxy <code>&lt;target-url&gt;</code> matter for browser-only (HAR) recording?</strong></summary>
 
-// Main helper for Playwright tests
-const playwrightProxy = {
-  // Set proxy mode before test and configure page with recording ID header
-  // Supports optional client-side recording for 3rd party APIs
-  async before(
-    page: Page,
-    testInfo: TestInfo,
-    mode: 'record' | 'replay' | 'transparent',
-    options?: number | (ClientSideRecordingOptions & { timeout?: number })
-  ): Promise<void>;
+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.
 
-  // Global teardown - switches proxy to transparent mode
-  // Use in Playwright's globalTeardown configuration
-  async teardown(): Promise<void>;
-};
+</details>
 
-// Direct mode control
-async function setProxyMode(
-  mode: 'record' | 'replay' | 'transparent',
-  id?: string,
-  timeout?: number
-): Promise<void>;
+<details>
+<summary><strong>Can I record against the Next.js dev server?</strong></summary>
 
-// Recording ID header constant
-const RECORDING_ID_HEADER: string; // 'x-test-rcrd-id'
-```
+Prefer `next build` + `next start` over `next dev` for recording and replaying. The dev server is slow and can cause timeouts or flaky recordings.
 
-**Options Parameter:**
-- `number` - Legacy format: timeout in milliseconds
-- `ClientSideRecordingOptions & { timeout?: number }` - Object with optional client-side recording and timeout:
-  - `url?: string | RegExp` - URL pattern for client-side recording (uses Playwright's HAR format)
-  - `timeout?: number` - Auto-reset timeout in milliseconds
+</details>
 
-### Next.js Integration
+<details>
+<summary><strong>How do I update a recording?</strong></summary>
 
-**IMPORTANT**: Use the `/nextjs` import path to avoid webpack bundling issues in Next.js:
+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/`.
 
-```typescript
-import {
-  setNextProxyHeaders,
-  getRecordingId,
-  createHeadersWithRecordingId,
-  RECORDING_ID_HEADER
-} from 'test-proxy-recorder/nextjs';
-import type { NextRequest, NextResponse } from 'next/server';
-
-// Forward recording ID header in Next.js middleware
-// Automatically skipped in production unless TEST_PROXY_RECORDER_ENABLED=true
-function setNextProxyHeaders(
-  request: NextRequest,
-  response: NextResponse
-): void;
-
-// Get recording ID from request headers
-function getRecordingId(
-  requestHeaders: NextRequest | Headers
-): string | null;
-
-// Create headers object with recording ID for fetch requests
-function createHeadersWithRecordingId(
-  requestHeaders: NextRequest | Headers,
-  additionalHeaders?: Record<string, string>
-): Record<string, string>;
-```
+</details>
 
-### Control Endpoint
+---
 
-The control endpoint supports both GET and POST methods.
+## AI Agent Skills
 
-**GET `/__control`** - Retrieve proxy configuration:
+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:
 
-```typescript
-// Response
-{
-  recordingsDir: string;  // Path to recordings directory
-  mode: string;           // Current mode: 'transparent' | 'record' | 'replay'
-  id?: string;            // Active recording/replay session ID
-}
+```bash
+npx @tanstack/intent@latest install
 ```
 
-**POST `/__control`** - Switch proxy mode:
+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.
 
-```typescript
-// Request Body
-{
-  mode: 'transparent' | 'record' | 'replay';
-  id?: string;      // Recording ID (required for record/replay)
-  timeout?: number; // Auto-reset timeout in ms (default: 120000)
-}
+---
 
-// Response
-{
-  success: boolean;
-  mode: string;
-  id: string | null;
-  timeout: number;
-  recordingsDir: string;
-}
-```
+## Roadmap
+
+First-class integrations on the way:
+
+- **TanStack Start**
+- **Remix**
+- **Vite + SSR**
 
-**Note**: Switching to replay mode automatically resets session counters (clears served recordings tracker), allowing replay from the beginning.
+Need one sooner, or a different framework? [Open an issue](https://github.com/asmyshlyaev177/test-proxy-recorder/issues).
+
+---
 
 ## Requirements
 
-- Node.js >= 22.0.0
-- @playwright/test >= 1.0.0 (for Playwright integration)
+- Node.js >= 20.0.0
+- @playwright/test >= 1.0.0 (peer dependency)
+
+---
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions welcome! Please submit a Pull Request.
+
+---
 
 ## License