test-proxy-recorder 0.2.0 → 0.3.0

package/README.md

@@ -21,6 +21,7 @@ HTTP proxy server for recording and replaying network requests in testing. 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)
@@ -128,14 +129,10 @@ Create `e2e/example.spec.ts`:
 import { test, expect } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-// Setup afterEach hook to reset proxy after each test
-test.afterEach(async ({ page: _page }, testInfo) => {
-  await playwrightProxy.after(testInfo);
-});
-
 test('example test with proxy', async ({ page }, testInfo) => {
   // Set proxy mode: 'record' to capture, 'replay' to use recordings
-  await playwrightProxy.before(testInfo, 'replay');
+  // This automatically sets up page.on('close') for cleanup
+  await playwrightProxy.before(page, testInfo, 'replay');
 
   await page.goto('/');
   await expect(page.getByText('Welcome')).toBeVisible();
@@ -147,13 +144,13 @@ test('example test with proxy', async ({ page }, testInfo) => {
 **First run (record mode)**:
 
 ```typescript
-await playwrightProxy.before(testInfo, 'record');
+await playwrightProxy.before(page, testInfo, 'record');
 ```
 
 **Subsequent runs (replay mode)**:
 
 ```typescript
-await playwrightProxy.before(testInfo, 'replay');
+await playwrightProxy.before(page, testInfo, 'replay');
 ```
 
 ## CLI Usage
@@ -186,24 +183,26 @@ test-proxy-recorder http://localhost:8000 http://localhost:9000 --port 8100
 
 ## Playwright Integration
 
+### Session Identification
+
+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.
+
 ### Basic Test Structure
 
-Every test file using the proxy should follow this pattern:
+Every test using the proxy should follow this pattern:
 
 ```typescript
 import { test } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-// Setup afterEach hook once per test file
-test.afterEach(async ({ page: _page }, testInfo) => {
-  await playwrightProxy.after(testInfo);
-});
-
 test('test name', async ({ page }, testInfo) => {
-  // 1. Set mode BEFORE test actions
-  await playwrightProxy.before(testInfo, 'replay');
+  // Set mode BEFORE test actions
+  // This automatically sets the recording ID header and cleanup handler
+  await playwrightProxy.before(page, testInfo, 'replay');
 
-  // 2. Test code
+  // Test code
   await page.goto('/page');
   // Test assertions...
 });
@@ -215,14 +214,9 @@ test('test name', async ({ page }, testInfo) => {
 import { test } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-// Setup afterEach hook to automatically cleanup after each test
-test.afterEach(async ({ page: _page }, testInfo) => {
-  await playwrightProxy.after(testInfo);
-});
-
 // Recording mode - captures API responses
 test('create user', async ({ page }, testInfo) => {
-  await playwrightProxy.before(testInfo, 'record');
+  await playwrightProxy.before(page, testInfo, 'record');
 
   await page.goto('/users/new');
   await page.fill('[name="username"]', 'testuser');
@@ -231,7 +225,7 @@ test('create user', async ({ page }, testInfo) => {
 
 // Replay mode - uses recorded responses
 test('create user', async ({ page }, testInfo) => {
-  await playwrightProxy.before(testInfo, 'replay');
+  await playwrightProxy.before(page, testInfo, 'replay');
 
   await page.goto('/users/new');
   await page.fill('[name="username"]', 'testuser');
@@ -274,6 +268,78 @@ export default defineConfig({
 });
 ```
 
+## 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.
+
+### Option 1: Using Next.js Middleware (Recommended)
+
+Create or update `middleware.ts` in your Next.js project root:
+
+```typescript
+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);
+
+  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:
+
+```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());
+}
+```
+
+### Option 3: Using getRecordingId Helper
+
+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.
@@ -410,20 +476,20 @@ class ProxyServer {
 ### Playwright Integration
 
 ```typescript
-import { playwrightProxy, setProxyMode } from 'test-proxy-recorder';
+import { playwrightProxy, setProxyMode, RECORDING_ID_HEADER } from 'test-proxy-recorder';
+import type { Page } from '@playwright/test';
 
 // Main helper for Playwright tests
 const playwrightProxy = {
-  // Set proxy mode before test
+  // Set proxy mode before test and configure page with recording ID header
+  // Automatically sets up page.on('close') handler for cleanup
   async before(
+    page: Page,
     testInfo: TestInfo,
     mode: 'record' | 'replay' | 'transparent',
     timeout?: number
   ): Promise<void>;
 
-  // Reset replay session and return to transparent mode after test
-  // Resets sequence counters to ensure next replay starts fresh
-  async after(testInfo: TestInfo): Promise<void>;
 
   // Global teardown - switches proxy to transparent mode
   // Use in Playwright's globalTeardown configuration
@@ -436,6 +502,41 @@ async function setProxyMode(
   id?: string,
   timeout?: number
 ): Promise<void>;
+
+// Recording ID header constant
+const RECORDING_ID_HEADER: string; // 'x-test-rcrd-id'
+```
+
+### Next.js Integration
+
+**IMPORTANT**: Use the `/nextjs` import path to avoid webpack bundling issues in Next.js:
+
+```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>;
 ```
 
 ### Control Endpoint

package/dist/{index-nmNRt1WE.d.cts → index-CVuiglPk.d.cts}

@@ -1,4 +1,4 @@
-import { TestInfo } from '@playwright/test';
+import { TestInfo, Page } from '@playwright/test';
 import http from 'node:http';
 
 declare const Modes: {
@@ -82,22 +82,18 @@ declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
 declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
 /**
  * Playwright test fixture helper for managing proxy mode
- * Use this in beforeEach/afterEach hooks
+ * Use this in test functions with page.on('close') for automatic cleanup
  */
 declare const playwrightProxy: {
     /**
-     * Setup before test - sets the proxy mode
+     * Setup before test - sets the proxy mode and configures page with custom header
+     * Automatically sets up page.on('close') handler for cleanup
+     * @param page - Playwright page object
      * @param testInfo - Playwright test info object
      * @param mode - The proxy mode to use for this test
      * @param timeout - Optional timeout in milliseconds
      */
-    before(testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
-    /**
-     * Cleanup after test - resets replay session by re-entering replay mode
-     * switchToReplayMode automatically clears sequence counters
-     * @param testInfo - Playwright test info object
-     */
-    after(testInfo: PlaywrightTestInfo): Promise<void>;
+    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
     /**
      * Global teardown - switches proxy to transparent mode
      * Use this in Playwright's globalTeardown to ensure clean state

package/dist/{index-nmNRt1WE.d.ts → index-CVuiglPk.d.ts}

@@ -1,4 +1,4 @@
-import { TestInfo } from '@playwright/test';
+import { TestInfo, Page } from '@playwright/test';
 import http from 'node:http';
 
 declare const Modes: {
@@ -82,22 +82,18 @@ declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
 declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
 /**
  * Playwright test fixture helper for managing proxy mode
- * Use this in beforeEach/afterEach hooks
+ * Use this in test functions with page.on('close') for automatic cleanup
  */
 declare const playwrightProxy: {
     /**
-     * Setup before test - sets the proxy mode
+     * Setup before test - sets the proxy mode and configures page with custom header
+     * Automatically sets up page.on('close') handler for cleanup
+     * @param page - Playwright page object
      * @param testInfo - Playwright test info object
      * @param mode - The proxy mode to use for this test
      * @param timeout - Optional timeout in milliseconds
      */
-    before(testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
-    /**
-     * Cleanup after test - resets replay session by re-entering replay mode
-     * switchToReplayMode automatically clears sequence counters
-     * @param testInfo - Playwright test info object
-     */
-    after(testInfo: PlaywrightTestInfo): Promise<void>;
+    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
     /**
      * Global teardown - switches proxy to transparent mode
      * Use this in Playwright's globalTeardown to ensure clean state

package/dist/index.cjs

@@ -19,8 +19,6 @@ var crypto__default = /*#__PURE__*/_interopDefault(crypto);
 var path__default = /*#__PURE__*/_interopDefault(path);
 var filenamify2__default = /*#__PURE__*/_interopDefault(filenamify2);
 
-// src/ProxyServer.ts
-
 // src/constants.ts
 var DEFAULT_TIMEOUT_MS = 120 * 1e3;
 var HTTP_STATUS_BAD_GATEWAY = 502;
@@ -28,6 +26,7 @@ var HTTP_STATUS_OK = 200;
 var HTTP_STATUS_BAD_REQUEST = 400;
 var HTTP_STATUS_NOT_FOUND = 404;
 var CONTROL_ENDPOINT = "/__control";
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
 
 // src/types.ts
 var Modes = {
@@ -200,7 +199,7 @@ var ProxyServer = class {
     return {
       "access-control-allow-origin": origin || "*",
       "access-control-allow-credentials": "true",
-      "access-control-allow-headers": req.headers["access-control-request-headers"] || "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+      "access-control-allow-headers": req.headers["access-control-request-headers"] || `Origin, X-Requested-With, Content-Type, Accept, Authorization, ${RECORDING_ID_HEADER}`,
       "access-control-allow-methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
       "access-control-expose-headers": "*"
     };
@@ -214,9 +213,22 @@ var ProxyServer = class {
     this.currentTargetIndex = (this.currentTargetIndex + 1) % this.targets.length;
     return target;
   }
+  /**
+   * Extract recording ID from custom HTTP header
+   * Used for concurrent replay session routing, especially with Next.js
+   * @param req The incoming HTTP request
+   * @returns The recording ID from header, or null if not found
+   */
+  getRecordingIdFromHeader(req) {
+    const headerValue = req.headers[RECORDING_ID_HEADER];
+    if (!headerValue) {
+      return null;
+    }
+    return Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  }
   /**
    * Extract recording ID from request cookie
-   * Used for concurrent replay session routing
+   * Used for concurrent replay session routing (fallback method)
    * @param req The incoming HTTP request
    * @returns The recording ID from cookie, or null if not found
    */
@@ -228,6 +240,14 @@ var ProxyServer = class {
     const match = cookies.match(/proxy-recording-id=([^;]+)/);
     return match ? decodeURIComponent(match[1]) : null;
   }
+  /**
+   * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+   * @param req The incoming HTTP request
+   * @returns The recording ID, or null if not found
+   */
+  getRecordingIdFromRequest(req) {
+    return this.getRecordingIdFromHeader(req) || this.getRecordingIdFromCookie(req);
+  }
   /**
    * Get or create a replay session state for a given recording ID
    * @param recordingId The recording ID to get/create session for
@@ -505,7 +525,7 @@ var ProxyServer = class {
     return true;
   }
   async handleReplayRequest(req, res) {
-    const recordingId = this.getRecordingIdFromCookie(req) || this.replayId;
+    const recordingId = this.getRecordingIdFromRequest(req) || this.replayId;
     if (!recordingId) {
       const corsHeaders = this.getCorsHeaders(req);
       res.writeHead(HTTP_STATUS_BAD_REQUEST, {
@@ -954,23 +974,29 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
    * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode, timeout) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
     await setProxyMode(mode, sessionId, timeout);
-  },
-  /**
-   * Cleanup after test - resets replay session by re-entering replay mode
-   * switchToReplayMode automatically clears sequence counters
-   * @param testInfo - Playwright test info object
-   */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.replay, sessionId);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
    * Global teardown - switches proxy to transparent mode
@@ -981,9 +1007,45 @@ var playwrightProxy = {
   }
 };
 
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
 exports.ProxyServer = ProxyServer;
+exports.RECORDING_ID_HEADER = RECORDING_ID_HEADER;
+exports.createHeadersWithRecordingId = createHeadersWithRecordingId;
 exports.generateSessionId = generateSessionId;
+exports.getRecordingId = getRecordingId;
 exports.playwrightProxy = playwrightProxy;
+exports.setNextProxyHeaders = setNextProxyHeaders;
 exports.setProxyMode = setProxyMode;
 exports.startRecording = startRecording;
 exports.startReplay = startReplay;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
+export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders } from './nextjs/index.cjs';
 import http from 'node:http';
-export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-nmNRt1WE.cjs';
+export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-CVuiglPk.cjs';
 import '@playwright/test';
 
 declare class ProxyServer {
@@ -28,13 +29,26 @@ declare class ProxyServer {
     private getCorsHeaders;
     private addCorsHeaders;
     private getTarget;
+    /**
+     * Extract recording ID from custom HTTP header
+     * Used for concurrent replay session routing, especially with Next.js
+     * @param req The incoming HTTP request
+     * @returns The recording ID from header, or null if not found
+     */
+    private getRecordingIdFromHeader;
     /**
      * Extract recording ID from request cookie
-     * Used for concurrent replay session routing
+     * Used for concurrent replay session routing (fallback method)
      * @param req The incoming HTTP request
      * @returns The recording ID from cookie, or null if not found
      */
     private getRecordingIdFromCookie;
+    /**
+     * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+     * @param req The incoming HTTP request
+     * @returns The recording ID, or null if not found
+     */
+    private getRecordingIdFromRequest;
     /**
      * Get or create a replay session state for a given recording ID
      * @param recordingId The recording ID to get/create session for

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders } from './nextjs/index.js';
 import http from 'node:http';
-export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-nmNRt1WE.js';
+export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-CVuiglPk.js';
 import '@playwright/test';
 
 declare class ProxyServer {
@@ -28,13 +29,26 @@ declare class ProxyServer {
     private getCorsHeaders;
     private addCorsHeaders;
     private getTarget;
+    /**
+     * Extract recording ID from custom HTTP header
+     * Used for concurrent replay session routing, especially with Next.js
+     * @param req The incoming HTTP request
+     * @returns The recording ID from header, or null if not found
+     */
+    private getRecordingIdFromHeader;
     /**
      * Extract recording ID from request cookie
-     * Used for concurrent replay session routing
+     * Used for concurrent replay session routing (fallback method)
      * @param req The incoming HTTP request
      * @returns The recording ID from cookie, or null if not found
      */
     private getRecordingIdFromCookie;
+    /**
+     * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+     * @param req The incoming HTTP request
+     * @returns The recording ID, or null if not found
+     */
+    private getRecordingIdFromRequest;
     /**
      * Get or create a replay session state for a given recording ID
      * @param recordingId The recording ID to get/create session for

package/dist/index.mjs

@@ -7,8 +7,6 @@ import crypto from 'crypto';
 import path from 'path';
 import filenamify2 from 'filenamify';
 
-// src/ProxyServer.ts
-
 // src/constants.ts
 var DEFAULT_TIMEOUT_MS = 120 * 1e3;
 var HTTP_STATUS_BAD_GATEWAY = 502;
@@ -16,6 +14,7 @@ var HTTP_STATUS_OK = 200;
 var HTTP_STATUS_BAD_REQUEST = 400;
 var HTTP_STATUS_NOT_FOUND = 404;
 var CONTROL_ENDPOINT = "/__control";
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
 
 // src/types.ts
 var Modes = {
@@ -188,7 +187,7 @@ var ProxyServer = class {
     return {
       "access-control-allow-origin": origin || "*",
       "access-control-allow-credentials": "true",
-      "access-control-allow-headers": req.headers["access-control-request-headers"] || "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+      "access-control-allow-headers": req.headers["access-control-request-headers"] || `Origin, X-Requested-With, Content-Type, Accept, Authorization, ${RECORDING_ID_HEADER}`,
       "access-control-allow-methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
       "access-control-expose-headers": "*"
     };
@@ -202,9 +201,22 @@ var ProxyServer = class {
     this.currentTargetIndex = (this.currentTargetIndex + 1) % this.targets.length;
     return target;
   }
+  /**
+   * Extract recording ID from custom HTTP header
+   * Used for concurrent replay session routing, especially with Next.js
+   * @param req The incoming HTTP request
+   * @returns The recording ID from header, or null if not found
+   */
+  getRecordingIdFromHeader(req) {
+    const headerValue = req.headers[RECORDING_ID_HEADER];
+    if (!headerValue) {
+      return null;
+    }
+    return Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  }
   /**
    * Extract recording ID from request cookie
-   * Used for concurrent replay session routing
+   * Used for concurrent replay session routing (fallback method)
    * @param req The incoming HTTP request
    * @returns The recording ID from cookie, or null if not found
    */
@@ -216,6 +228,14 @@ var ProxyServer = class {
     const match = cookies.match(/proxy-recording-id=([^;]+)/);
     return match ? decodeURIComponent(match[1]) : null;
   }
+  /**
+   * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+   * @param req The incoming HTTP request
+   * @returns The recording ID, or null if not found
+   */
+  getRecordingIdFromRequest(req) {
+    return this.getRecordingIdFromHeader(req) || this.getRecordingIdFromCookie(req);
+  }
   /**
    * Get or create a replay session state for a given recording ID
    * @param recordingId The recording ID to get/create session for
@@ -493,7 +513,7 @@ var ProxyServer = class {
     return true;
   }
   async handleReplayRequest(req, res) {
-    const recordingId = this.getRecordingIdFromCookie(req) || this.replayId;
+    const recordingId = this.getRecordingIdFromRequest(req) || this.replayId;
     if (!recordingId) {
       const corsHeaders = this.getCorsHeaders(req);
       res.writeHead(HTTP_STATUS_BAD_REQUEST, {
@@ -942,23 +962,29 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
    * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode, timeout) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
     await setProxyMode(mode, sessionId, timeout);
-  },
-  /**
-   * Cleanup after test - resets replay session by re-entering replay mode
-   * switchToReplayMode automatically clears sequence counters
-   * @param testInfo - Playwright test info object
-   */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.replay, sessionId);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
    * Global teardown - switches proxy to transparent mode
@@ -969,6 +995,38 @@ var playwrightProxy = {
   }
 };
 
-export { ProxyServer, generateSessionId, playwrightProxy, setProxyMode, startRecording, startReplay, stopProxy };
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
+export { ProxyServer, RECORDING_ID_HEADER, createHeadersWithRecordingId, generateSessionId, getRecordingId, playwrightProxy, setNextProxyHeaders, setProxyMode, startRecording, startReplay, stopProxy };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/nextjs/index.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
+exports.RECORDING_ID_HEADER = RECORDING_ID_HEADER;
+exports.createHeadersWithRecordingId = createHeadersWithRecordingId;
+exports.getRecordingId = getRecordingId;
+exports.setNextProxyHeaders = setNextProxyHeaders;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/nextjs/index.d.cts

@@ -0,0 +1,89 @@
+declare const RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+/**
+ * Minimal type for Next.js Request - compatible with next/server's NextRequest
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSRequest {
+    headers: Headers;
+}
+/**
+ * Minimal type for Next.js Response - compatible with next/server's NextResponse
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSResponse {
+    headers: Headers;
+}
+/**
+ * Next.js middleware helper for forwarding test proxy recording headers
+ * Automatically forwards the recording ID header from incoming requests to the proxy
+ * Only runs in non-production environments or when TEST_PROXY_RECORDER_ENABLED is set
+ *
+ * @example
+ * // 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();
+ *   // Only forwards headers in test/dev environments
+ *   setNextProxyHeaders(request, response);
+ *   return response;
+ * }
+ *
+ * @param request - Next.js request object (NextRequest from next/server)
+ * @param response - Next.js response object (NextResponse from next/server)
+ */
+declare function setNextProxyHeaders(request: NextJSRequest, response: NextJSResponse): void;
+/**
+ * Get the recording ID from the request if present
+ * Useful for manually adding the header to fetch requests in Next.js
+ *
+ * @example
+ * // In your API route or server component
+ * import { getRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const recordingId = getRecordingId(headers());
+ *
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: {
+ *       ...(recordingId && { 'x-test-rcrd-id': recordingId })
+ *     }
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @returns The recording ID if present, null otherwise
+ */
+declare function getRecordingId(requestHeaders: NextJSRequest | Headers): string | null;
+/**
+ * Create headers object with recording ID for fetch requests
+ * Use this helper when making fetch requests in Next.js to forward the recording ID
+ *
+ * @example
+ * // In your API route or server component
+ * import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: createHeadersWithRecordingId(headers(), {
+ *       'Content-Type': 'application/json',
+ *     })
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @param additionalHeaders - Optional additional headers to include
+ * @returns Headers object with recording ID if present
+ */
+declare function createHeadersWithRecordingId(requestHeaders: NextJSRequest | Headers, additionalHeaders?: Record<string, string>): Record<string, string>;
+
+export { type NextJSRequest, type NextJSResponse, RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders };

package/dist/nextjs/index.d.ts

@@ -0,0 +1,89 @@
+declare const RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+/**
+ * Minimal type for Next.js Request - compatible with next/server's NextRequest
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSRequest {
+    headers: Headers;
+}
+/**
+ * Minimal type for Next.js Response - compatible with next/server's NextResponse
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSResponse {
+    headers: Headers;
+}
+/**
+ * Next.js middleware helper for forwarding test proxy recording headers
+ * Automatically forwards the recording ID header from incoming requests to the proxy
+ * Only runs in non-production environments or when TEST_PROXY_RECORDER_ENABLED is set
+ *
+ * @example
+ * // 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();
+ *   // Only forwards headers in test/dev environments
+ *   setNextProxyHeaders(request, response);
+ *   return response;
+ * }
+ *
+ * @param request - Next.js request object (NextRequest from next/server)
+ * @param response - Next.js response object (NextResponse from next/server)
+ */
+declare function setNextProxyHeaders(request: NextJSRequest, response: NextJSResponse): void;
+/**
+ * Get the recording ID from the request if present
+ * Useful for manually adding the header to fetch requests in Next.js
+ *
+ * @example
+ * // In your API route or server component
+ * import { getRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const recordingId = getRecordingId(headers());
+ *
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: {
+ *       ...(recordingId && { 'x-test-rcrd-id': recordingId })
+ *     }
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @returns The recording ID if present, null otherwise
+ */
+declare function getRecordingId(requestHeaders: NextJSRequest | Headers): string | null;
+/**
+ * Create headers object with recording ID for fetch requests
+ * Use this helper when making fetch requests in Next.js to forward the recording ID
+ *
+ * @example
+ * // In your API route or server component
+ * import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: createHeadersWithRecordingId(headers(), {
+ *       'Content-Type': 'application/json',
+ *     })
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @param additionalHeaders - Optional additional headers to include
+ * @returns Headers object with recording ID if present
+ */
+declare function createHeadersWithRecordingId(requestHeaders: NextJSRequest | Headers, additionalHeaders?: Record<string, string>): Record<string, string>;
+
+export { type NextJSRequest, type NextJSResponse, RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders };

package/dist/nextjs/index.mjs

@@ -0,0 +1,38 @@
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
+export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/playwright/index.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
 // src/types.ts
 var Modes = {
   transparent: "transparent",
@@ -86,23 +89,29 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
    * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode, timeout) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
     await setProxyMode(mode, sessionId, timeout);
-  },
-  /**
-   * Cleanup after test - resets replay session by re-entering replay mode
-   * switchToReplayMode automatically clears sequence counters
-   * @param testInfo - Playwright test info object
-   */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.replay, sessionId);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
    * Global teardown - switches proxy to transparent mode

package/dist/playwright/index.d.cts

@@ -1,3 +1,3 @@
 import '@playwright/test';
-export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-nmNRt1WE.cjs';
+export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-CVuiglPk.cjs';
 import 'node:http';

package/dist/playwright/index.d.ts

@@ -1,3 +1,3 @@
 import '@playwright/test';
-export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-nmNRt1WE.js';
+export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-CVuiglPk.js';
 import 'node:http';

package/dist/playwright/index.mjs

@@ -1,3 +1,6 @@
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
 // src/types.ts
 var Modes = {
   transparent: "transparent",
@@ -84,23 +87,29 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
    * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode, timeout) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
     await setProxyMode(mode, sessionId, timeout);
-  },
-  /**
-   * Cleanup after test - resets replay session by re-entering replay mode
-   * switchToReplayMode automatically clears sequence counters
-   * @param testInfo - Playwright test info object
-   */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.replay, sessionId);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
    * Global teardown - switches proxy to transparent mode

package/dist/proxy.js

@@ -50,6 +50,7 @@ var HTTP_STATUS_OK = 200;
 var HTTP_STATUS_BAD_REQUEST = 400;
 var HTTP_STATUS_NOT_FOUND = 404;
 var CONTROL_ENDPOINT = "/__control";
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
 
 // src/types.ts
 var Modes = {
@@ -222,7 +223,7 @@ var ProxyServer = class {
     return {
       "access-control-allow-origin": origin || "*",
       "access-control-allow-credentials": "true",
-      "access-control-allow-headers": req.headers["access-control-request-headers"] || "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+      "access-control-allow-headers": req.headers["access-control-request-headers"] || `Origin, X-Requested-With, Content-Type, Accept, Authorization, ${RECORDING_ID_HEADER}`,
       "access-control-allow-methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
       "access-control-expose-headers": "*"
     };
@@ -236,9 +237,22 @@ var ProxyServer = class {
     this.currentTargetIndex = (this.currentTargetIndex + 1) % this.targets.length;
     return target;
   }
+  /**
+   * Extract recording ID from custom HTTP header
+   * Used for concurrent replay session routing, especially with Next.js
+   * @param req The incoming HTTP request
+   * @returns The recording ID from header, or null if not found
+   */
+  getRecordingIdFromHeader(req) {
+    const headerValue = req.headers[RECORDING_ID_HEADER];
+    if (!headerValue) {
+      return null;
+    }
+    return Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  }
   /**
    * Extract recording ID from request cookie
-   * Used for concurrent replay session routing
+   * Used for concurrent replay session routing (fallback method)
    * @param req The incoming HTTP request
    * @returns The recording ID from cookie, or null if not found
    */
@@ -250,6 +264,14 @@ var ProxyServer = class {
     const match = cookies.match(/proxy-recording-id=([^;]+)/);
     return match ? decodeURIComponent(match[1]) : null;
   }
+  /**
+   * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+   * @param req The incoming HTTP request
+   * @returns The recording ID, or null if not found
+   */
+  getRecordingIdFromRequest(req) {
+    return this.getRecordingIdFromHeader(req) || this.getRecordingIdFromCookie(req);
+  }
   /**
    * Get or create a replay session state for a given recording ID
    * @param recordingId The recording ID to get/create session for
@@ -527,7 +549,7 @@ var ProxyServer = class {
     return true;
   }
   async handleReplayRequest(req, res) {
-    const recordingId = this.getRecordingIdFromCookie(req) || this.replayId;
+    const recordingId = this.getRecordingIdFromRequest(req) || this.replayId;
     if (!recordingId) {
       const corsHeaders = this.getCorsHeaders(req);
       res.writeHead(HTTP_STATUS_BAD_REQUEST, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "test-proxy-recorder",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "HTTP proxy server for recording and replaying network requests in testing. Works seamlessly with Playwright testing framework.",
   "type": "module",
   "main": "dist/index.mjs",
@@ -15,6 +15,11 @@
       "require": "./dist/playwright/index.cjs",
       "types": "./dist/playwright/index.d.ts",
       "default": "./dist/playwright/index.mjs"
+    },
+    "./nextjs": {
+      "require": "./dist/nextjs/index.cjs",
+      "types": "./dist/nextjs/index.d.ts",
+      "default": "./dist/nextjs/index.mjs"
     }
   },
   "bin": {