test-proxy-recorder 0.1.4 → 0.1.6

package/README.md

@@ -9,262 +9,455 @@ HTTP proxy server for recording and replaying network requests in testing. Works
 
 ## Features
 
-- **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.
+- **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
 
-## Installation
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Complete Setup Guide](#complete-setup-guide)
+- [CLI Usage](#cli-usage)
+- [Playwright Integration](#playwright-integration)
+- [Control Endpoint](#control-endpoint)
+- [Typical Workflow](#typical-workflow)
+- [Recording Format](#recording-format)
+- [Troubleshooting](#troubleshooting)
+- [API Reference](#api-reference)
+
+## How It Works
+
+The proxy server runs continuously and can switch between three modes per test:
+
+### 1. Transparent Mode (Default)
+
+Passes requests through to the backend without recording or replaying.
+
+### 2. Record Mode
+
+Captures all HTTP requests/responses and WebSocket messages to disk. Each test gets its own recording file based on the test name.
+
+### 3. Replay Mode
+
+Replays previously recorded responses from disk instead of hitting the real API. Perfect for fast, deterministic tests.
+
+## Complete Setup Guide
+
+### Step 1: Install Package
+
+```bash
+npm install --save-dev test-proxy-recorder
+```
+
+### Step 2: Add NPM Scripts
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --recordings-dir ./e2e/recordings"
+  }
+}
+```
+
+**RECOMMENDED**: Use `concurrently` to run proxy and app together:
+
+```bash
+npm install --save-dev concurrently
+```
+
+```json
+{
+  "scripts": {
+    "proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --recordings-dir ./e2e/recordings",
+    "dev:proxy": "concurrently -n \"proxy,app\" -c \"blue,green\" \"npm run proxy\" \"INTERNAL_API_URL=http://localhost:8100 npm run dev\""
+  }
+}
+```
+
+### Step 3: Configure Git for Recordings
+
+**CRITICAL**: Recordings must be committed to git for CI/CD replay.
+
+Create or update your `.gitattributes` file:
+
+```gitattributes
+/e2e/recordings/** binary
+```
+
+This marks recording files as binary, which causes long mock files to be collapsed/folded in Pull Request diffs for better readability.
+
+**DO NOT** add `e2e/recordings` to `.gitignore`. Recordings need to be versioned in git for CI/CD to use them.
+
+**Note**: The recordings directory will be created automatically when you first record a test - no need to create it manually.
+
+### Step 4: Create Playwright Global Teardown (Recommended)
+
+Create `e2e/global-teardown.ts`:
+
+```typescript
+import { setProxyMode } from 'test-proxy-recorder';
+
+async function globalTeardown() {
+  await setProxyMode('transparent');
+}
+
+export default globalTeardown;
+```
+
+Update `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  globalTeardown: './e2e/global-teardown.ts',
+  // ... rest of config
+});
+```
+
+### Step 5: Create Example Test
+
+Create `e2e/example.spec.ts`:
+
+```typescript
+import { test, expect } 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
+  await playwrightProxy.before(testInfo, 'replay');
+
+  await page.goto('/');
+  await expect(page.getByText('Welcome')).toBeVisible();
+
+  // Always cleanup after test
+  await playwrightProxy.after(testInfo);
+});
+```
+
+### Step 6: Run Tests
+
+**First run (record mode)**:
+
+```typescript
+await playwrightProxy.before(testInfo, 'record');
+```
+
+**Subsequent runs (replay mode)**:
+
+```typescript
+await playwrightProxy.before(testInfo, 'replay');
+```
+
+## CLI Usage
+
+### Basic Command
 
 ```bash
-npm install test-proxy-recorder
-# or
-pnpm add test-proxy-recorder
-# or
-yarn add test-proxy-recorder
+test-proxy-recorder <target-url> [options]
 ```
 
-## Quick Start
+### CLI Options
+
+- `<target-url>` - Backend API URL (positional argument, required)
+- `--port, -p <number>` - Port to listen on (default: 8080)
+- `--recordings-dir, -r <path>` - Directory to store recordings (default: ./recordings)
+- `--help, -h` - Show help
+
+### Examples
+
+```bash
+# Basic usage
+test-proxy-recorder http://localhost:8000
 
- 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()`:
+# Custom port and recordings directory
+test-proxy-recorder http://localhost:8000 --port 8100 --recordings-dir ./mocks
+
+# Multiple targets (experimental)
+test-proxy-recorder http://localhost:8000 http://localhost:9000 --port 8100
+```
+
+## Playwright Integration
+
+### Basic Test Structure
+
+Every test using the proxy should follow this pattern:
 
 ```typescript
 import { test } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
-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
+test('test name', async ({ page }, testInfo) => {
+  // 1. Set mode BEFORE test actions
+  await playwrightProxy.before(testInfo, 'replay');
+
+  // 2. Test code
+  await page.goto('/page');
+
+  // 3. Reset mode AFTER test completes
+  await playwrightProxy.after(testInfo);
+});
+```
+
+### Recording vs Replay
+
+```typescript
+// Recording mode - captures API responses
+test('create user', async ({ page }, testInfo) => {
   await playwrightProxy.before(testInfo, 'record');
 
-  // Make requests - they will be recorded
-  await page.goto('/myPage');
- /// ... test content ...
+  await page.goto('/users/new');
+  await page.fill('[name="username"]', 'testuser');
+  await page.click('button[type="submit"]');
 
-  // Save mock and return to transparent mode
   await playwrightProxy.after(testInfo);
 });
 
-test('replay recorded responses', async ({ page }, testInfo) => {
-  // Set proxy to replay mode - uses recording from test above
+// Replay mode - uses recorded responses
+test('create user', async ({ page }, testInfo) => {
   await playwrightProxy.before(testInfo, 'replay');
 
-  await page.goto('/myPage');
- /// ... test content ...
+  await page.goto('/users/new');
+  await page.fill('[name="username"]', 'testuser');
+  await page.click('button[type="submit"]');
 
   await playwrightProxy.after(testInfo);
 });
 ```
 
-## How It Works
+### Test Naming
 
-The proxy server runs continuously and can switch between three modes:
+Recording files are auto-generated from test names:
 
-### 1. Transparent Mode (Default)
+- Test: `"create a user"`
+- File: `create-a-user.mock.json`
 
-Simply proxies requests to the backend without recording or replaying.
+**Important**: Keep test names stable for replay to work correctly.
 
-### 2. Record Mode
+### Global Teardown (Recommended)
 
-Captures all HTTP requests/responses and WebSocket messages to disk. Each test gets its own recording file based on the test name.
+Create `e2e/global-teardown.ts`:
 
-### 3. Replay Mode
+```typescript
+import { setProxyMode } from 'test-proxy-recorder';
 
-Replays previously recorded responses from disk instead of hitting the real API. Perfect for fast, deterministic tests.
+async function globalTeardown() {
+  await setProxyMode('transparent');
+}
 
-## Modes Control
+export default globalTeardown;
+```
 
-### Via Playwright
+Update `playwright.config.ts`:
 
 ```typescript
-// Recording mode
-await playwrightProxy.before(testInfo, 'recording');
-// ... test code ...
-await playwrightProxy.after(testInfo);
+import { defineConfig } from '@playwright/test';
 
-// Replay mode
-await playwrightProxy.before(testInfo, 'replay');
-// ... test code ...
-await playwrightProxy.after(testInfo);
+export default defineConfig({
+  testDir: './e2e',
+  globalTeardown: './e2e/global-teardown.ts',
+  // ... rest of config
+});
 ```
 
-### Via HTTP Control Endpoint
+## Control Endpoint
+
+The proxy exposes a control endpoint at `/__control` for programmatic mode switching.
 
-Using curl:
+### Via HTTP
 
 ```bash
 # Switch to record mode
 curl -X POST http://localhost:8100/__control \
   -H "Content-Type: application/json" \
-  -d '{"mode": "record", "id": "my-testfile-1", "timeout": 30000}'
+  -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-testfile-1"}'
+  -d '{"mode": "replay", "id": "my-test-1"}'
 
 # Switch to transparent mode
 curl -X POST http://localhost:8100/__control \
   -H "Content-Type: application/json" \
-  -d '{"mode": "transparent", "id": "my-testfile-1"}'
+  -d '{"mode": "transparent"}'
 ```
 
-Using JavaScript fetch:
+### Via JavaScript
 
 ```javascript
-// Switch to record mode
 await fetch('http://localhost:8100/__control', {
   method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
+  headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
     mode: 'record',
-    id: 'my-testfile-1',
-    timeout: 30000
+    id: 'my-test-1',
+    timeout: 30000 // Optional: auto-reset after 30s
   })
 });
+```
 
-// 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'
-  })
-});
+### Control Request Interface
 
-// Switch to transparent mode
-await fetch('http://localhost:8100/__control', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    mode: 'transparent',
-  })
-});
+```typescript
+interface ControlRequest {
+  mode: 'transparent' | 'record' | 'replay';
+  id?: string;      // Recording ID, required for record/replay
+  timeout?: number; // Auto-reset timeout in ms (default: 120000)
+}
 ```
 
-## Usage
+## Typical Workflow
 
-```bash
-# Start proxy server
-test-proxy-recorder --port 8100 --target http://localhost:8000 --recordings ./recordings
+### 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'`
+
+### Running with Replay
+
+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
+
+### Updating Recordings
+
+1. Start backend API
+2. Set test to `'record'` mode
+3. Run test: Overwrites existing recording
+4. Commit updated `.mock.json` file
+
+## Recording Format
+
+Recordings are stored as JSON files with `.mock.json` extension:
+
+```text
+e2e/recordings/
+├── create-a-user.mock.json
+├── fetch-users-list.mock.json
+└── delete-user.mock.json
 ```
 
-### CLI Options
+## Troubleshooting
 
-- `--port, -p`: Port to listen on (default: 8080)
-- `--target, -t`: Backend target URL (can add multiple targets)
-- `--recordings, -r`: Directory to store recordings (default: ./recordings)
+### Proxy not responding
 
-## API
+**Check if proxy is running**:
 
-### ProxyServer
+```bash
+curl http://localhost:8100/__control
+```
 
-```typescript
-class ProxyServer {
-  constructor(targets: string[], recordingsDir: string);
+**Check port availability**:
 
-  async init(): Promise<void>;
-  listen(port: number): http.Server;
-}
+```bash
+lsof -i :8100
 ```
 
-### Control Endpoint
+### No recordings saved
+
+- 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
+
+- Ensure recording exists for this test
+- Check test name hasn't changed
+- Verify recording file matches expected format
+- Re-record if API responses changed
+
+### Recordings not matching requests
+
+- Request URLs must match exactly
+- Headers may affect matching (configurable)
+- Query parameters must be in same order
+- Re-record to capture current API behavior
+
+
+## API Reference
 
-Send POST requests to `/__control` with JSON body:
+### ProxyServer Class
 
 ```typescript
-interface ControlRequest {
-  mode: 'transparent' | 'record' | 'replay';
-  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
+class ProxyServer {
+  constructor(targets: string[], recordingsDir: string);
+  async init(): Promise<void>;
+  listen(port: number): http.Server;
 }
 ```
 
-### Playwright Integration API
+### Playwright Integration
 
 ```typescript
-import { playwrightProxy } from 'test-proxy-recorder';
+import { playwrightProxy, setProxyMode } from 'test-proxy-recorder';
 
-// Main helper object for use with Playwright tests
+// Main helper for Playwright tests
 const playwrightProxy = {
   // Set proxy mode before test
-  async before(testInfo: PlaywrightTestInfo, mode: 'record' | 'replay' | 'transparent'): Promise<void>;
+  async before(
+    testInfo: TestInfo,
+    mode: 'record' | 'replay' | 'transparent',
+    timeout?: number
+  ): Promise<void>;
 
   // Reset to transparent mode after test
-  async after(testInfo: PlaywrightTestInfo): Promise<void>;
+  async after(testInfo: TestInfo): Promise<void>;
 };
-```
-
-## Recording Format
-
-Recordings are stored as JSON files in the recordings directory:
 
+// Direct mode control
+async function setProxyMode(
+  mode: 'record' | 'replay' | 'transparent',
+  id?: string,
+  timeout?: number
+): Promise<void>;
 ```
-recordings/
-├── test-session-1.json
-├── test-session-2.json
-└── ...
-```
-
-Each recording contains:
-
-- Request/response pairs with headers and bodies
-- WebSocket messages with timestamps
-- Unique keys for request matching during replay
-
-## Typical Workflow
-
-1. **Start the proxy server** (runs continuously):
 
-   ```bash
-   test-proxy-recorder http://localhost:8000 --port 8100
-   ```
-
-2. **Configure your app** to use the proxy:
+### Control Endpoint
 
-   ```bash
-   export EXTERNAL_API_URL=http://localhost:8100 yarn dev
-   ```
+**Endpoint**: `POST http://localhost:8100/__control`
 
-3. **Record responses** (first run):
+**Request Body**:
 
-   ```typescript
-   test('my test', async ({ page }, testInfo) => {
-     await playwrightProxy.before(testInfo, 'record');
-     // Test interacts with real API through proxy
-     await page.goto('/my-page');
-     await playwrightProxy.after(testInfo);
-   });
-   ```
+```typescript
+{
+  mode: 'transparent' | 'record' | 'replay';
+  id?: string;      // Recording ID (required for record/replay)
+  timeout?: number; // Auto-reset timeout in ms (default: 120000)
+}
+```
 
-4. **Replay responses** (subsequent runs):
+**Response**:
 
-   ```typescript
-   test('my test', async ({ page }, testInfo) => {
-     await playwrightProxy.before(testInfo, 'replay');
-     // Test uses recorded responses - no real API calls
-     await page.goto('/my-page');
-     await playwrightProxy.after(testInfo);
-   });
-   ```
+```typescript
+{
+  success: boolean;
+  mode: string;
+  id: string | null;
+  timeout: number;
+}
+```
 
 ## Requirements
 
 - Node.js >= 22.0.0
-- @playwright/test >= 1.0.0
-
-## License
-
-MIT
+- @playwright/test >= 1.0.0 (for Playwright integration)
 
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

package/dist/{index-De4mgziH.d.cts → index-CBjvm5rb.d.cts}

@@ -47,7 +47,7 @@ interface RecordingSession {
     websocketRecordings: WebSocketRecording[];
 }
 
-type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
+type PlaywrightTestInfo = Pick<TestInfo, 'title' | 'titlePath'>;
 /**
  * Set the proxy mode for a given session
  * @param mode - The proxy mode to set (recording, replay, transparent)
@@ -57,6 +57,10 @@ type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
 declare function setProxyMode(mode: Mode, sessionId?: string, timeout?: number): Promise<void>;
 /**
  * Generate a session ID from test info
+ * Uses titlePath to create folder structure with test file name
+ * Supports both .spec.ts and .test.ts extensions
+ * Example: ['jobs/Create.spec.ts', 'create a job'] becomes 'jobs/Create__create-a-job'
+ * Example: ['users/Auth.test.ts', 'login test'] becomes 'users/Auth__login-test'
  * @param testInfo - Playwright test info object
  */
 declare function generateSessionId(testInfo: PlaywrightTestInfo): string;

package/dist/{index-De4mgziH.d.ts → index-CBjvm5rb.d.ts}

@@ -47,7 +47,7 @@ interface RecordingSession {
     websocketRecordings: WebSocketRecording[];
 }
 
-type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
+type PlaywrightTestInfo = Pick<TestInfo, 'title' | 'titlePath'>;
 /**
  * Set the proxy mode for a given session
  * @param mode - The proxy mode to set (recording, replay, transparent)
@@ -57,6 +57,10 @@ type PlaywrightTestInfo = Pick<TestInfo, 'title'>;
 declare function setProxyMode(mode: Mode, sessionId?: string, timeout?: number): Promise<void>;
 /**
  * Generate a session ID from test info
+ * Uses titlePath to create folder structure with test file name
+ * Supports both .spec.ts and .test.ts extensions
+ * Example: ['jobs/Create.spec.ts', 'create a job'] becomes 'jobs/Create__create-a-job'
+ * Example: ['users/Auth.test.ts', 'login test'] becomes 'users/Auth__login-test'
  * @param testInfo - Playwright test info object
  */
 declare function generateSessionId(testInfo: PlaywrightTestInfo): string;