test-proxy-recorder 0.1.1 → 0.1.3

package/README.md

@@ -1,18 +1,18 @@
 # test-proxy-recorder
 
+[![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.
 
-### BETA VERSION, NOT STABLE FOR PRODUCTION USE
+## BETA VERSION
 
 ## Features
 
-- **Record Mode**: Capture HTTP/HTTPS requests and responses, including WebSocket connections
-- **Replay Mode**: Replay captured requests from disk without hitting real endpoints
-- **Transparent Mode**: Act as a simple proxy without recording or replaying
-- **Playwright Integration**: Built-in fixture for easy integration with Playwright tests
-- **WebSocket Support**: Full support for recording and replaying WebSocket connections
-- **Multiple Targets**: Load balance between multiple backend targets
-- **Timeout Control**: Automatic mode switching after configurable timeouts
+- **Fast CI/CD Tests**: Record API responses once with real backend, replay them on CI/CD
+- **Fast workflow**: Record real interactions with API, instead of mocking every request manually
+- **Server Side Rendering**: Can record SSR requests from JS frameworks like NextJS.
+- **Deterministic Tests**: Same responses every time, no flaky network issues, no need to wire up the whole Backend API for testing
 
 ## Installation
 
@@ -26,40 +26,23 @@ yarn add test-proxy-recorder
 
 ## Quick Start
 
-### Standalone Usage
-
-```typescript
-import { ProxyServer } from 'test-proxy-recorder';
-
-const proxy = new ProxyServer(
-  ['http://localhost:3000'], // backend targets
-  './recordings'             // directory to store recordings
-);
-
-await proxy.init();
-const server = proxy.listen(8080);
-console.log('Proxy running on http://localhost:8080');
-```
-
-### With Playwright
-
-The proxy runs continuously in the background. Tests control the recording/replay mode using `playwrightProxy.before()` and `playwrightProxy.after()`:
+ 1. Run proxy with your backend API as a target `test-proxy-recorder --port 8100 --target http://localhost:8000 --recordings ./recordings`, here your backend on port 8000 as target, proxy on port 8100.
+ 2. Point your Frontend app to proxy port, 8100 as example
+ 3. The proxy runs continuously in the background. Tests control the recording/replay mode using `playwrightProxy.before()` and `playwrightProxy.after()`:
 
 ```typescript
 import { test } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-test('record API responses', async ({ page }, testInfo) => {
-  // Set proxy to recording mode for this test
-  await playwrightProxy.before(testInfo, 'recording');
+test('Test UI with API responses', async ({ page }, testInfo) => {
+  // Set proxy to recording mode to record mocks, sanitized test title will be used as file name
+  await playwrightProxy.before(testInfo, 'record');
 
   // Make requests - they will be recorded
-  await page.goto('http://localhost:8080/api/data');
-
-  // Your test assertions here
-  await expect(page.getByText('Data loaded')).toBeVisible();
+  await page.goto('/myPage');
+ /// ... test content ...
 
-  // Clean up - return to transparent mode
+  // Save mock and return to transparent mode
   await playwrightProxy.after(testInfo);
 });
 
@@ -67,34 +50,13 @@ test('replay recorded responses', async ({ page }, testInfo) => {
   // Set proxy to replay mode - uses recording from test above
   await playwrightProxy.before(testInfo, 'replay');
 
-  // This will use recorded responses instead of hitting the real API
-  await page.goto('http://localhost:8080/api/data');
-
-  await expect(page.getByText('Data loaded')).toBeVisible();
+  await page.goto('/myPage');
+ /// ... test content ...
 
   await playwrightProxy.after(testInfo);
 });
 ```
 
-You can also use standalone functions for more control:
-
-```typescript
-import { test } from '@playwright/test';
-import { setProxyMode, generateSessionId } from 'test-proxy-recorder';
-
-test('custom proxy control', async ({ page }, testInfo) => {
-  const sessionId = generateSessionId(testInfo);
-
-  // Start recording with a 30s timeout
-  await setProxyMode('recording', sessionId, 30000);
-
-  await page.goto('http://localhost:8080/api/data');
-
-  // Switch to transparent mode
-  await setProxyMode('transparent', sessionId);
-});
-```
-
 ## How It Works
 
 The proxy server runs continuously and can switch between three modes:
@@ -113,7 +75,7 @@ Replays previously recorded responses from disk instead of hitting the real API.
 
 ## Modes Control
 
-### Via Playwright (Recommended)
+### Via Playwright
 
 ```typescript
 // Recording mode
@@ -129,40 +91,76 @@ await playwrightProxy.after(testInfo);
 
 ### Via HTTP Control Endpoint
 
+Using curl:
+
 ```bash
 # Switch to record mode
-curl -X POST http://localhost:8080/__proxy_control__ \
+curl -X POST http://localhost:8100/__control \
   -H "Content-Type: application/json" \
-  -d '{"mode": "record", "id": "test-session-1", "timeout": 30000}'
+  -d '{"mode": "record", "id": "my-testfile-1", "timeout": 30000}'
 
 # Switch to replay mode
-curl -X POST http://localhost:8080/__proxy_control__ \
+curl -X POST http://localhost:8100/__control \
   -H "Content-Type: application/json" \
-  -d '{"mode": "replay", "id": "test-session-1"}'
+  -d '{"mode": "replay", "id": "my-testfile-1"}'
 
 # Switch to transparent mode
-curl -X POST http://localhost:8080/__proxy_control__ \
+curl -X POST http://localhost:8100/__control \
   -H "Content-Type: application/json" \
-  -d '{"mode": "transparent", "id": "test-session-1"}'
+  -d '{"mode": "transparent", "id": "my-testfile-1"}'
 ```
 
-## CLI Usage
+Using JavaScript fetch:
+
+```javascript
+// Switch to record mode
+await fetch('http://localhost:8100/__control', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    mode: 'record',
+    id: 'my-testfile-1',
+    timeout: 30000
+  })
+});
+
+// Switch to replay mode
+await fetch('http://localhost:8100/__control', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    mode: 'replay',
+    id: 'my-testfile-1'
+  })
+});
+
+// Switch to transparent mode
+await fetch('http://localhost:8100/__control', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    mode: 'transparent',
+  })
+});
+```
+
+## Usage
 
 ```bash
 # Start proxy server
-test-proxy-recorder --port 8080 --target http://localhost:3000 --recordings ./recordings
-
-# With multiple targets for load balancing
-test-proxy-recorder --port 8080 \
-  --target http://localhost:3000 \
-  --target http://localhost:3001 \
-  --recordings ./recordings
+test-proxy-recorder --port 8100 --target http://localhost:8000 --recordings ./recordings
 ```
 
 ### CLI Options
 
 - `--port, -p`: Port to listen on (default: 8080)
-- `--target, -t`: Backend target URL (can be specified multiple times)
+- `--target, -t`: Backend target URL (can add multiple targets)
 - `--recordings, -r`: Directory to store recordings (default: ./recordings)
 
 ## API
@@ -180,13 +178,13 @@ class ProxyServer {
 
 ### Control Endpoint
 
-Send POST requests to `/__proxy_control__` with JSON body:
+Send POST requests to `/__control` with JSON body:
 
 ```typescript
 interface ControlRequest {
   mode: 'transparent' | 'record' | 'replay';
-  id?: string;      // Required for record/replay modes
-  timeout?: number; // Auto-switch to transparent mode after timeout (ms)
+  id?: string;      // Will be used as file name for recordings, required for record/replay modes
+  timeout?: number; // Auto-switch to transparent mode after timeout (ms), default 120 seconds
 }
 ```
 
@@ -198,36 +196,11 @@ import { playwrightProxy } from 'test-proxy-recorder';
 // Main helper object for use with Playwright tests
 const playwrightProxy = {
   // Set proxy mode before test
-  async before(testInfo: PlaywrightTestInfo, mode: 'recording' | 'replay' | 'transparent'): Promise<void>;
+  async before(testInfo: PlaywrightTestInfo, mode: 'record' | 'replay' | 'transparent'): Promise<void>;
 
   // Reset to transparent mode after test
   async after(testInfo: PlaywrightTestInfo): Promise<void>;
 };
-
-// Standalone functions for custom control:
-import {
-  setProxyMode,        // Set mode with custom session ID
-  generateSessionId,   // Generate session ID from test info
-  startRecording,      // Helper to start recording
-  startReplay,         // Helper to start replay
-  stopProxy            // Helper to stop recording/replay
-} from 'test-proxy-recorder';
-```
-
-### Usage Pattern
-
-```typescript
-test('your test', async ({ page }, testInfo) => {
-  // Setup: Set proxy mode at start of test
-  await playwrightProxy.before(testInfo, 'replay');
-
-  // Your test code here
-  await page.goto('/your-page');
-  await expect(page.getByText('Something')).toBeVisible();
-
-  // Cleanup: Return to transparent mode
-  await playwrightProxy.after(testInfo);
-});
 ```
 
 ## Recording Format
@@ -252,20 +225,20 @@ Each recording contains:
 1. **Start the proxy server** (runs continuously):
 
    ```bash
-   test-proxy-recorder http://localhost:3000 --port 8080
+   test-proxy-recorder http://localhost:8000 --port 8100
    ```
 
 2. **Configure your app** to use the proxy:
 
    ```bash
-   export EXTERNAL_API_URL=http://localhost:8080
+   export EXTERNAL_API_URL=http://localhost:8100 yarn dev
    ```
 
 3. **Record responses** (first run):
 
    ```typescript
    test('my test', async ({ page }, testInfo) => {
-     await playwrightProxy.before(testInfo, 'recording');
+     await playwrightProxy.before(testInfo, 'record');
      // Test interacts with real API through proxy
      await page.goto('/my-page');
      await playwrightProxy.after(testInfo);
@@ -283,68 +256,10 @@ Each recording contains:
    });
    ```
 
-## Use Cases
-
-- **Fast CI/CD Tests**: Record API responses once, replay them for instant test execution
-- **Deterministic Tests**: Same responses every time, no flaky network issues
-- **API Contract Testing**: Verify frontend handles all API scenarios
-- **WebSocket Testing**: Record and replay complex WebSocket message sequences
-
-## Configuration Examples
-
-### With Environment Variables
-
-```typescript
-const proxy = new ProxyServer(
-  [process.env.BACKEND_URL || 'http://localhost:3000'],
-  process.env.RECORDINGS_DIR || './recordings'
-);
-```
-
-### Multiple Backend Targets
-
-```typescript
-// Round-robin load balancing between targets
-const proxy = new ProxyServer(
-  [
-    'http://backend-1:3000',
-    'http://backend-2:3000',
-    'http://backend-3:3000'
-  ],
-  './recordings'
-);
-```
-
-## WebSocket Support
-
-WebSocket connections are automatically detected and recorded/replayed:
-
-```typescript
-test('websocket test', async ({ page }, testInfo) => {
-  // Recording WebSocket messages
-  await playwrightProxy.before(testInfo, 'recording');
-
-  await page.goto('/websocket-page');
-  // WebSocket connections and messages are recorded
-
-  await playwrightProxy.after(testInfo);
-});
-
-test('websocket replay', async ({ page }, testInfo) => {
-  // Replay WebSocket messages
-  await playwrightProxy.before(testInfo, 'replay');
-
-  await page.goto('/websocket-page');
-  // Previously recorded WebSocket messages are replayed
-
-  await playwrightProxy.after(testInfo);
-});
-```
-
 ## Requirements
 
 - Node.js >= 22.0.0
-- For Playwright integration: @playwright/test >= 1.0.0
+- @playwright/test >= 1.0.0
 
 ## License
 
@@ -353,11 +268,3 @@ MIT
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
-
-## Author
-
-asmyshlyaev177
-
-## Repository
-
-[https://github.com/asmyshlyaev177/test-proxy-recorder](https://github.com/asmyshlyaev177/test-proxy-recorder)

package/dist/index-DfFpm8mB.d.cts

@@ -0,0 +1,95 @@
+import { TestInfo } from '@playwright/test';
+import http from 'node:http';
+
+declare const Modes: {
+    readonly transparent: "transparent";
+    readonly record: "record";
+    readonly replay: "replay";
+};
+type Mode = (typeof Modes)[keyof typeof Modes];
+interface ControlRequest {
+    mode: Mode;
+    id?: string;
+    timeout?: number;
+}
+interface RecordedRequest {
+    method: string;
+    url: string;
+    headers: http.IncomingHttpHeaders;
+    body: string | null;
+}
+interface RecordedResponse {
+    statusCode: number;
+    headers: http.IncomingHttpHeaders;
+    body: string | null;
+}
+interface Recording {
+    request: RecordedRequest;
+    response?: RecordedResponse;
+    timestamp: string;
+    key: string;
+}
+interface WebSocketMessage {
+    direction: 'client-to-server' | 'server-to-client';
+    data: string;
+    timestamp: string;
+}
+interface WebSocketRecording {
+    url: string;
+    messages: WebSocketMessage[];
+    timestamp: string;
+    key: string;
+}
+interface RecordingSession {
+    id: string;
+    recordings: Recording[];
+    websocketRecordings: WebSocketRecording[];
+}
+
+type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
+/**
+ * Set the proxy mode for a given session
+ * @param mode - The proxy mode to set (recording, replay, transparent)
+ * @param sessionId - Unique identifier for the session
+ * @param timeout - Optional timeout in milliseconds
+ */
+declare function setProxyMode(mode: Mode, sessionId: string, timeout?: number): Promise<void>;
+/**
+ * Generate a session ID from test info
+ * @param testInfo - Playwright test info object
+ */
+declare function generateSessionId(testInfo: PlaywrightTestInfo): string;
+/**
+ * Start recording for a test
+ * @param testInfo - Playwright test info object
+ */
+declare function startRecording(testInfo: PlaywrightTestInfo): Promise<void>;
+/**
+ * Start replay for a test
+ * @param testInfo - Playwright test info object
+ */
+declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
+/**
+ * Stop recording/replay and return to transparent mode
+ * @param testInfo - Playwright test info object
+ */
+declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
+/**
+ * Playwright test fixture helper for managing proxy mode
+ * Use this in beforeEach/afterEach hooks
+ */
+declare const playwrightProxy: {
+    /**
+     * Setup before test - sets the proxy mode
+     * @param testInfo - Playwright test info object
+     * @param mode - The proxy mode to use for this test
+     */
+    before(testInfo: PlaywrightTestInfo, mode: Mode): Promise<void>;
+    /**
+     * Cleanup after test - returns to transparent mode
+     * @param testInfo - Playwright test info object
+     */
+    after(testInfo: PlaywrightTestInfo): Promise<void>;
+};
+
+export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type Recording as R, type WebSocketRecording as W, type RecordingSession as a, startRecording as b, startReplay as c, stopProxy as d, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

package/dist/index-DfFpm8mB.d.ts

@@ -0,0 +1,95 @@
+import { TestInfo } from '@playwright/test';
+import http from 'node:http';
+
+declare const Modes: {
+    readonly transparent: "transparent";
+    readonly record: "record";
+    readonly replay: "replay";
+};
+type Mode = (typeof Modes)[keyof typeof Modes];
+interface ControlRequest {
+    mode: Mode;
+    id?: string;
+    timeout?: number;
+}
+interface RecordedRequest {
+    method: string;
+    url: string;
+    headers: http.IncomingHttpHeaders;
+    body: string | null;
+}
+interface RecordedResponse {
+    statusCode: number;
+    headers: http.IncomingHttpHeaders;
+    body: string | null;
+}
+interface Recording {
+    request: RecordedRequest;
+    response?: RecordedResponse;
+    timestamp: string;
+    key: string;
+}
+interface WebSocketMessage {
+    direction: 'client-to-server' | 'server-to-client';
+    data: string;
+    timestamp: string;
+}
+interface WebSocketRecording {
+    url: string;
+    messages: WebSocketMessage[];
+    timestamp: string;
+    key: string;
+}
+interface RecordingSession {
+    id: string;
+    recordings: Recording[];
+    websocketRecordings: WebSocketRecording[];
+}
+
+type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
+/**
+ * Set the proxy mode for a given session
+ * @param mode - The proxy mode to set (recording, replay, transparent)
+ * @param sessionId - Unique identifier for the session
+ * @param timeout - Optional timeout in milliseconds
+ */
+declare function setProxyMode(mode: Mode, sessionId: string, timeout?: number): Promise<void>;
+/**
+ * Generate a session ID from test info
+ * @param testInfo - Playwright test info object
+ */
+declare function generateSessionId(testInfo: PlaywrightTestInfo): string;
+/**
+ * Start recording for a test
+ * @param testInfo - Playwright test info object
+ */
+declare function startRecording(testInfo: PlaywrightTestInfo): Promise<void>;
+/**
+ * Start replay for a test
+ * @param testInfo - Playwright test info object
+ */
+declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
+/**
+ * Stop recording/replay and return to transparent mode
+ * @param testInfo - Playwright test info object
+ */
+declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
+/**
+ * Playwright test fixture helper for managing proxy mode
+ * Use this in beforeEach/afterEach hooks
+ */
+declare const playwrightProxy: {
+    /**
+     * Setup before test - sets the proxy mode
+     * @param testInfo - Playwright test info object
+     * @param mode - The proxy mode to use for this test
+     */
+    before(testInfo: PlaywrightTestInfo, mode: Mode): Promise<void>;
+    /**
+     * Cleanup after test - returns to transparent mode
+     * @param testInfo - Playwright test info object
+     */
+    after(testInfo: PlaywrightTestInfo): Promise<void>;
+};
+
+export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type Recording as R, type WebSocketRecording as W, type RecordingSession as a, startRecording as b, startReplay as c, stopProxy as d, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

package/dist/index.cjs

@@ -5,6 +5,7 @@ var http = require('http');
 var httpProxy = require('http-proxy');
 var ws = require('ws');
 var path = require('path');
+var filenamify = require('filenamify');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -12,6 +13,7 @@ var fs__default = /*#__PURE__*/_interopDefault(fs);
 var http__default = /*#__PURE__*/_interopDefault(http);
 var httpProxy__default = /*#__PURE__*/_interopDefault(httpProxy);
 var path__default = /*#__PURE__*/_interopDefault(path);
+var filenamify__default = /*#__PURE__*/_interopDefault(filenamify);
 
 // src/ProxyServer.ts
 
@@ -47,6 +49,24 @@ async function saveRecordingSession(recordingsDir, session) {
     `Saved ${session.recordings.length} HTTP recordings and ${session.websocketRecordings?.length || 0} WebSocket recordings to ${filePath}`
   );
 }
+var QUERY_HASH_LENGTH = 8;
+function getReqID(req) {
+  const urlParts = req.url.split("?");
+  const pathname = urlParts[0];
+  const query = urlParts[1] || "";
+  const pathPart = pathname === "/" ? "root" : pathname.slice(1);
+  const normalizedPath = filenamify__default.default(pathPart, { replacement: "_" });
+  const queryHash = generateQueryHash(query);
+  const filename = `${req.method}_${normalizedPath}${queryHash}.json`;
+  return filenamify__default.default(filename, { replacement: "_" });
+}
+function generateQueryHash(query) {
+  if (!query) {
+    return "";
+  }
+  const hash = Buffer.from(query).toString("base64").replaceAll(/[^a-zA-Z0-9]/g, "").slice(0, Math.max(0, QUERY_HASH_LENGTH));
+  return `_${hash}`;
+}
 
 // src/utils/httpHelpers.ts
 var CONTENT_TYPE_JSON = "application/json";
@@ -62,28 +82,6 @@ function sendJsonResponse(res, statusCode, data) {
   res.end(JSON.stringify(data));
 }
 
-// src/utils/requestKeyGenerator.ts
-var QUERY_HASH_LENGTH = 8;
-function generateRequestKey(req) {
-  const urlParts = req.url.split("?");
-  const pathname = urlParts[0];
-  const query = urlParts[1] || "";
-  const normalizedPath = normalizePathname(pathname);
-  const queryHash = generateQueryHash(query);
-  return `${req.method}_${normalizedPath}${queryHash}.json`;
-}
-function normalizePathname(pathname) {
-  const normalized = pathname.replaceAll("/", "_").replace(/^_/, "");
-  return normalized || "root";
-}
-function generateQueryHash(query) {
-  if (!query) {
-    return "";
-  }
-  const hash = Buffer.from(query).toString("base64").replaceAll(/[^a-zA-Z0-9]/g, "").slice(0, Math.max(0, QUERY_HASH_LENGTH));
-  return `_${hash}`;
-}
-
 // src/ProxyServer.ts
 var ProxyServer = class {
   targets;
@@ -209,6 +207,7 @@ var ProxyServer = class {
     this.recordingId = null;
     this.replayId = null;
     this.currentSession = null;
+    clearTimeout(this.modeTimeout || 0);
     console.log("Switched to transparent mode");
   }
   switchToRecordMode(id) {
@@ -259,7 +258,7 @@ var ProxyServer = class {
     if (!this.currentSession) {
       return;
     }
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const record = {
       request: {
         method: req.method,
@@ -276,7 +275,7 @@ var ProxyServer = class {
     if (!this.currentSession) {
       return;
     }
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const record = this.currentSession.recordings.find((r) => r.key === key);
     if (!record) {
       console.error("Request record not found for response:", key);
@@ -298,7 +297,7 @@ var ProxyServer = class {
     });
   }
   async handleReplayRequest(req, res) {
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const filePath = getRecordingPath(this.recordingsDir, this.replayId);
     try {
       const session = await loadRecordingSession(filePath);
@@ -555,15 +554,15 @@ function generateSessionId(testInfo) {
 }
 async function startRecording(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("recording", sessionId);
+  await setProxyMode(Modes.record, sessionId);
 }
 async function startReplay(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("replay", sessionId);
+  await setProxyMode(Modes.replay, sessionId);
 }
 async function stopProxy(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("transparent", sessionId);
+  await setProxyMode(Modes.transparent, sessionId);
 }
 var playwrightProxy = {
   /**
@@ -582,7 +581,7 @@ var playwrightProxy = {
    */
   async after(testInfo) {
     const sessionId = generateSessionId(testInfo);
-    await setProxyMode("transparent", sessionId);
+    await setProxyMode(Modes.transparent, sessionId);
   }
 };
 

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import http from 'node:http';
-export { PlaywrightTestInfo, ProxyMode, generateSessionId, playwrightProxy, setProxyMode, startRecording, startReplay, stopProxy } from './playwright/index.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-DfFpm8mB.cjs';
 import '@playwright/test';
 
 declare class ProxyServer {
@@ -40,49 +40,4 @@ declare class ProxyServer {
     private logServerStartup;
 }
 
-declare const Modes: {
-    readonly transparent: "transparent";
-    readonly record: "record";
-    readonly replay: "replay";
-};
-type Mode = (typeof Modes)[keyof typeof Modes];
-interface ControlRequest {
-    mode: Mode;
-    id?: string;
-    timeout?: number;
-}
-interface RecordedRequest {
-    method: string;
-    url: string;
-    headers: http.IncomingHttpHeaders;
-    body: string | null;
-}
-interface RecordedResponse {
-    statusCode: number;
-    headers: http.IncomingHttpHeaders;
-    body: string | null;
-}
-interface Recording {
-    request: RecordedRequest;
-    response?: RecordedResponse;
-    timestamp: string;
-    key: string;
-}
-interface WebSocketMessage {
-    direction: 'client-to-server' | 'server-to-client';
-    data: string;
-    timestamp: string;
-}
-interface WebSocketRecording {
-    url: string;
-    messages: WebSocketMessage[];
-    timestamp: string;
-    key: string;
-}
-interface RecordingSession {
-    id: string;
-    recordings: Recording[];
-    websocketRecordings: WebSocketRecording[];
-}
-
-export { type ControlRequest, type Mode, ProxyServer, type Recording, type RecordingSession, type WebSocketRecording };
+export { ProxyServer };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import http from 'node:http';
-export { PlaywrightTestInfo, ProxyMode, generateSessionId, playwrightProxy, setProxyMode, startRecording, startReplay, stopProxy } from './playwright/index.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-DfFpm8mB.js';
 import '@playwright/test';
 
 declare class ProxyServer {
@@ -40,49 +40,4 @@ declare class ProxyServer {
     private logServerStartup;
 }
 
-declare const Modes: {
-    readonly transparent: "transparent";
-    readonly record: "record";
-    readonly replay: "replay";
-};
-type Mode = (typeof Modes)[keyof typeof Modes];
-interface ControlRequest {
-    mode: Mode;
-    id?: string;
-    timeout?: number;
-}
-interface RecordedRequest {
-    method: string;
-    url: string;
-    headers: http.IncomingHttpHeaders;
-    body: string | null;
-}
-interface RecordedResponse {
-    statusCode: number;
-    headers: http.IncomingHttpHeaders;
-    body: string | null;
-}
-interface Recording {
-    request: RecordedRequest;
-    response?: RecordedResponse;
-    timestamp: string;
-    key: string;
-}
-interface WebSocketMessage {
-    direction: 'client-to-server' | 'server-to-client';
-    data: string;
-    timestamp: string;
-}
-interface WebSocketRecording {
-    url: string;
-    messages: WebSocketMessage[];
-    timestamp: string;
-    key: string;
-}
-interface RecordingSession {
-    id: string;
-    recordings: Recording[];
-    websocketRecordings: WebSocketRecording[];
-}
-
-export { type ControlRequest, type Mode, ProxyServer, type Recording, type RecordingSession, type WebSocketRecording };
+export { ProxyServer };

package/dist/index.mjs

@@ -3,6 +3,7 @@ import http from 'http';
 import httpProxy from 'http-proxy';
 import { WebSocket, WebSocketServer } from 'ws';
 import path from 'path';
+import filenamify from 'filenamify';
 
 // src/ProxyServer.ts
 
@@ -38,6 +39,24 @@ async function saveRecordingSession(recordingsDir, session) {
     `Saved ${session.recordings.length} HTTP recordings and ${session.websocketRecordings?.length || 0} WebSocket recordings to ${filePath}`
   );
 }
+var QUERY_HASH_LENGTH = 8;
+function getReqID(req) {
+  const urlParts = req.url.split("?");
+  const pathname = urlParts[0];
+  const query = urlParts[1] || "";
+  const pathPart = pathname === "/" ? "root" : pathname.slice(1);
+  const normalizedPath = filenamify(pathPart, { replacement: "_" });
+  const queryHash = generateQueryHash(query);
+  const filename = `${req.method}_${normalizedPath}${queryHash}.json`;
+  return filenamify(filename, { replacement: "_" });
+}
+function generateQueryHash(query) {
+  if (!query) {
+    return "";
+  }
+  const hash = Buffer.from(query).toString("base64").replaceAll(/[^a-zA-Z0-9]/g, "").slice(0, Math.max(0, QUERY_HASH_LENGTH));
+  return `_${hash}`;
+}
 
 // src/utils/httpHelpers.ts
 var CONTENT_TYPE_JSON = "application/json";
@@ -53,28 +72,6 @@ function sendJsonResponse(res, statusCode, data) {
   res.end(JSON.stringify(data));
 }
 
-// src/utils/requestKeyGenerator.ts
-var QUERY_HASH_LENGTH = 8;
-function generateRequestKey(req) {
-  const urlParts = req.url.split("?");
-  const pathname = urlParts[0];
-  const query = urlParts[1] || "";
-  const normalizedPath = normalizePathname(pathname);
-  const queryHash = generateQueryHash(query);
-  return `${req.method}_${normalizedPath}${queryHash}.json`;
-}
-function normalizePathname(pathname) {
-  const normalized = pathname.replaceAll("/", "_").replace(/^_/, "");
-  return normalized || "root";
-}
-function generateQueryHash(query) {
-  if (!query) {
-    return "";
-  }
-  const hash = Buffer.from(query).toString("base64").replaceAll(/[^a-zA-Z0-9]/g, "").slice(0, Math.max(0, QUERY_HASH_LENGTH));
-  return `_${hash}`;
-}
-
 // src/ProxyServer.ts
 var ProxyServer = class {
   targets;
@@ -200,6 +197,7 @@ var ProxyServer = class {
     this.recordingId = null;
     this.replayId = null;
     this.currentSession = null;
+    clearTimeout(this.modeTimeout || 0);
     console.log("Switched to transparent mode");
   }
   switchToRecordMode(id) {
@@ -250,7 +248,7 @@ var ProxyServer = class {
     if (!this.currentSession) {
       return;
     }
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const record = {
       request: {
         method: req.method,
@@ -267,7 +265,7 @@ var ProxyServer = class {
     if (!this.currentSession) {
       return;
     }
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const record = this.currentSession.recordings.find((r) => r.key === key);
     if (!record) {
       console.error("Request record not found for response:", key);
@@ -289,7 +287,7 @@ var ProxyServer = class {
     });
   }
   async handleReplayRequest(req, res) {
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const filePath = getRecordingPath(this.recordingsDir, this.replayId);
     try {
       const session = await loadRecordingSession(filePath);
@@ -546,15 +544,15 @@ function generateSessionId(testInfo) {
 }
 async function startRecording(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("recording", sessionId);
+  await setProxyMode(Modes.record, sessionId);
 }
 async function startReplay(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("replay", sessionId);
+  await setProxyMode(Modes.replay, sessionId);
 }
 async function stopProxy(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("transparent", sessionId);
+  await setProxyMode(Modes.transparent, sessionId);
 }
 var playwrightProxy = {
   /**
@@ -573,7 +571,7 @@ var playwrightProxy = {
    */
   async after(testInfo) {
     const sessionId = generateSessionId(testInfo);
-    await setProxyMode("transparent", sessionId);
+    await setProxyMode(Modes.transparent, sessionId);
   }
 };
 

package/dist/playwright/index.cjs

@@ -1,5 +1,12 @@
 'use strict';
 
+// src/types.ts
+var Modes = {
+  transparent: "transparent",
+  record: "record",
+  replay: "replay"
+};
+
 // src/playwright/index.ts
 var INTERNAL_API_URL = process.env.INTERNAL_API_URL || "http://localhost:8100";
 async function setProxyMode(mode, sessionId, timeout) {
@@ -31,15 +38,15 @@ function generateSessionId(testInfo) {
 }
 async function startRecording(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("recording", sessionId);
+  await setProxyMode(Modes.record, sessionId);
 }
 async function startReplay(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("replay", sessionId);
+  await setProxyMode(Modes.replay, sessionId);
 }
 async function stopProxy(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("transparent", sessionId);
+  await setProxyMode(Modes.transparent, sessionId);
 }
 var playwrightProxy = {
   /**
@@ -58,7 +65,7 @@ var playwrightProxy = {
    */
   async after(testInfo) {
     const sessionId = generateSessionId(testInfo);
-    await setProxyMode("transparent", sessionId);
+    await setProxyMode(Modes.transparent, sessionId);
   }
 };
 

package/dist/playwright/index.d.cts

@@ -1,50 +1,3 @@
-import { TestInfo } from '@playwright/test';
-
-type ProxyMode = 'recording' | 'replay' | 'transparent';
-type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
-/**
- * Set the proxy mode for a given session
- * @param mode - The proxy mode to set (recording, replay, transparent)
- * @param sessionId - Unique identifier for the session
- * @param timeout - Optional timeout in milliseconds
- */
-declare function setProxyMode(mode: ProxyMode, sessionId: string, timeout?: number): Promise<void>;
-/**
- * Generate a session ID from test info
- * @param testInfo - Playwright test info object
- */
-declare function generateSessionId(testInfo: PlaywrightTestInfo): string;
-/**
- * Start recording for a test
- * @param testInfo - Playwright test info object
- */
-declare function startRecording(testInfo: PlaywrightTestInfo): Promise<void>;
-/**
- * Start replay for a test
- * @param testInfo - Playwright test info object
- */
-declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
-/**
- * Stop recording/replay and return to transparent mode
- * @param testInfo - Playwright test info object
- */
-declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
-/**
- * Playwright test fixture helper for managing proxy mode
- * Use this in beforeEach/afterEach hooks
- */
-declare const playwrightProxy: {
-    /**
-     * Setup before test - sets the proxy mode
-     * @param testInfo - Playwright test info object
-     * @param mode - The proxy mode to use for this test
-     */
-    before(testInfo: PlaywrightTestInfo, mode: ProxyMode): Promise<void>;
-    /**
-     * Cleanup after test - returns to transparent mode
-     * @param testInfo - Playwright test info object
-     */
-    after(testInfo: PlaywrightTestInfo): Promise<void>;
-};
-
-export { type PlaywrightTestInfo, type ProxyMode, generateSessionId, playwrightProxy, setProxyMode, startRecording, startReplay, stopProxy };
+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-DfFpm8mB.cjs';
+import 'node:http';

package/dist/playwright/index.d.ts

@@ -1,50 +1,3 @@
-import { TestInfo } from '@playwright/test';
-
-type ProxyMode = 'recording' | 'replay' | 'transparent';
-type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
-/**
- * Set the proxy mode for a given session
- * @param mode - The proxy mode to set (recording, replay, transparent)
- * @param sessionId - Unique identifier for the session
- * @param timeout - Optional timeout in milliseconds
- */
-declare function setProxyMode(mode: ProxyMode, sessionId: string, timeout?: number): Promise<void>;
-/**
- * Generate a session ID from test info
- * @param testInfo - Playwright test info object
- */
-declare function generateSessionId(testInfo: PlaywrightTestInfo): string;
-/**
- * Start recording for a test
- * @param testInfo - Playwright test info object
- */
-declare function startRecording(testInfo: PlaywrightTestInfo): Promise<void>;
-/**
- * Start replay for a test
- * @param testInfo - Playwright test info object
- */
-declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
-/**
- * Stop recording/replay and return to transparent mode
- * @param testInfo - Playwright test info object
- */
-declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
-/**
- * Playwright test fixture helper for managing proxy mode
- * Use this in beforeEach/afterEach hooks
- */
-declare const playwrightProxy: {
-    /**
-     * Setup before test - sets the proxy mode
-     * @param testInfo - Playwright test info object
-     * @param mode - The proxy mode to use for this test
-     */
-    before(testInfo: PlaywrightTestInfo, mode: ProxyMode): Promise<void>;
-    /**
-     * Cleanup after test - returns to transparent mode
-     * @param testInfo - Playwright test info object
-     */
-    after(testInfo: PlaywrightTestInfo): Promise<void>;
-};
-
-export { type PlaywrightTestInfo, type ProxyMode, generateSessionId, playwrightProxy, setProxyMode, startRecording, startReplay, stopProxy };
+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-DfFpm8mB.js';
+import 'node:http';

package/dist/playwright/index.mjs

@@ -1,3 +1,10 @@
+// src/types.ts
+var Modes = {
+  transparent: "transparent",
+  record: "record",
+  replay: "replay"
+};
+
 // src/playwright/index.ts
 var INTERNAL_API_URL = process.env.INTERNAL_API_URL || "http://localhost:8100";
 async function setProxyMode(mode, sessionId, timeout) {
@@ -29,15 +36,15 @@ function generateSessionId(testInfo) {
 }
 async function startRecording(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("recording", sessionId);
+  await setProxyMode(Modes.record, sessionId);
 }
 async function startReplay(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("replay", sessionId);
+  await setProxyMode(Modes.replay, sessionId);
 }
 async function stopProxy(testInfo) {
   const sessionId = generateSessionId(testInfo);
-  await setProxyMode("transparent", sessionId);
+  await setProxyMode(Modes.transparent, sessionId);
 }
 var playwrightProxy = {
   /**
@@ -56,7 +63,7 @@ var playwrightProxy = {
    */
   async after(testInfo) {
     const sessionId = generateSessionId(testInfo);
-    await setProxyMode("transparent", sessionId);
+    await setProxyMode(Modes.transparent, sessionId);
   }
 };
 

package/dist/proxy.js

@@ -4,6 +4,7 @@ import fs from 'fs/promises';
 import http from 'http';
 import httpProxy from 'http-proxy';
 import { WebSocket, WebSocketServer } from 'ws';
+import filenamify from 'filenamify';
 
 // src/cli.ts
 var DEFAULT_PORT = 8e3;
@@ -72,6 +73,24 @@ async function saveRecordingSession(recordingsDir2, session) {
     `Saved ${session.recordings.length} HTTP recordings and ${session.websocketRecordings?.length || 0} WebSocket recordings to ${filePath}`
   );
 }
+var QUERY_HASH_LENGTH = 8;
+function getReqID(req) {
+  const urlParts = req.url.split("?");
+  const pathname = urlParts[0];
+  const query = urlParts[1] || "";
+  const pathPart = pathname === "/" ? "root" : pathname.slice(1);
+  const normalizedPath = filenamify(pathPart, { replacement: "_" });
+  const queryHash = generateQueryHash(query);
+  const filename = `${req.method}_${normalizedPath}${queryHash}.json`;
+  return filenamify(filename, { replacement: "_" });
+}
+function generateQueryHash(query) {
+  if (!query) {
+    return "";
+  }
+  const hash = Buffer.from(query).toString("base64").replaceAll(/[^a-zA-Z0-9]/g, "").slice(0, Math.max(0, QUERY_HASH_LENGTH));
+  return `_${hash}`;
+}
 
 // src/utils/httpHelpers.ts
 var CONTENT_TYPE_JSON = "application/json";
@@ -87,28 +106,6 @@ function sendJsonResponse(res, statusCode, data) {
   res.end(JSON.stringify(data));
 }
 
-// src/utils/requestKeyGenerator.ts
-var QUERY_HASH_LENGTH = 8;
-function generateRequestKey(req) {
-  const urlParts = req.url.split("?");
-  const pathname = urlParts[0];
-  const query = urlParts[1] || "";
-  const normalizedPath = normalizePathname(pathname);
-  const queryHash = generateQueryHash(query);
-  return `${req.method}_${normalizedPath}${queryHash}.json`;
-}
-function normalizePathname(pathname) {
-  const normalized = pathname.replaceAll("/", "_").replace(/^_/, "");
-  return normalized || "root";
-}
-function generateQueryHash(query) {
-  if (!query) {
-    return "";
-  }
-  const hash = Buffer.from(query).toString("base64").replaceAll(/[^a-zA-Z0-9]/g, "").slice(0, Math.max(0, QUERY_HASH_LENGTH));
-  return `_${hash}`;
-}
-
 // src/ProxyServer.ts
 var ProxyServer = class {
   targets;
@@ -234,6 +231,7 @@ var ProxyServer = class {
     this.recordingId = null;
     this.replayId = null;
     this.currentSession = null;
+    clearTimeout(this.modeTimeout || 0);
     console.log("Switched to transparent mode");
   }
   switchToRecordMode(id) {
@@ -284,7 +282,7 @@ var ProxyServer = class {
     if (!this.currentSession) {
       return;
     }
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const record = {
       request: {
         method: req.method,
@@ -301,7 +299,7 @@ var ProxyServer = class {
     if (!this.currentSession) {
       return;
     }
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const record = this.currentSession.recordings.find((r) => r.key === key);
     if (!record) {
       console.error("Request record not found for response:", key);
@@ -323,7 +321,7 @@ var ProxyServer = class {
     });
   }
   async handleReplayRequest(req, res) {
-    const key = generateRequestKey(req);
+    const key = getReqID(req);
     const filePath = getRecordingPath(this.recordingsDir, this.replayId);
     try {
       const session = await loadRecordingSession(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "test-proxy-recorder",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "HTTP proxy server for recording and replaying network requests in testing. Works seamlessly with Playwright testing framework.",
   "type": "module",
   "main": "dist/index.mjs",
@@ -79,6 +79,7 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
+    "filenamify": "^7.0.1",
     "http-proxy": "^1.18.1"
   },
   "peerDependencies": {