test-proxy-recorder 0.1.5 → 0.1.7

package/README.md

@@ -9,328 +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
+test-proxy-recorder <target-url> [options]
+```
+
+### 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
-npm install test-proxy-recorder
-# or
-pnpm add test-proxy-recorder
-# or
-yarn add test-proxy-recorder
+# Basic usage
+test-proxy-recorder http://localhost:8000
+
+# 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
 ```
 
-## Quick Start
+## Playwright Integration
 
- 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()`:
+### 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
 
-Using curl:
+The proxy exposes a control endpoint at `/__control` for programmatic mode switching.
+
+### 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
-  })
-});
-
-// 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',
+    id: 'my-test-1',
+    timeout: 30000 // Optional: auto-reset after 30s
   })
 });
 ```
 
-## Usage
-
-```bash
-# Start proxy server
-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 add multiple targets)
-- `--recordings, -r`: Directory to store recordings (default: ./recordings)
-
-## API
-
-### ProxyServer
-
-```typescript
-class ProxyServer {
-  constructor(targets: string[], recordingsDir: string);
-
-  async init(): Promise<void>;
-  listen(port: number): http.Server;
-}
-```
-
-### Control Endpoint
-
-Send POST requests to `/__control` with JSON body:
+### Control Request Interface
 
 ```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
+  id?: string;      // Recording ID, required for record/replay
+  timeout?: number; // Auto-reset timeout in ms (default: 120000)
 }
 ```
 
-### Playwright Integration API
+## Typical Workflow
 
-```typescript
-import { playwrightProxy, setProxyMode } from 'test-proxy-recorder';
+### Initial Recording
 
-// Main helper object for use with Playwright tests
-const playwrightProxy = {
-  // Set proxy mode before test
-  async before(testInfo: PlaywrightTestInfo, mode: 'record' | 'replay' | 'transparent'): Promise<void>;
+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'`
 
-  // Reset to transparent mode after test
-  async after(testInfo: PlaywrightTestInfo): Promise<void>;
-};
-```
+### Running with Replay
 
-### Global Teardown and Hooks Setup (Recommended)
+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
 
-For robust test setups, it's recommended to configure global teardown and afterEach hooks to ensure the proxy is properly reset even when tests fail. This prevents the proxy from staying in record/replay mode, which could affect subsequent test runs.
+### Updating Recordings
 
-#### 1. Create Global Teardown File
+1. Start backend API
+2. Set test to `'record'` mode
+3. Run test: Overwrites existing recording
+4. Commit updated `.mock.json` file
 
-Create `e2e/global-teardown.ts` to reset the proxy mode after all tests complete:
+## Recording Format
 
-```typescript
-import { setProxyMode } from 'test-proxy-recorder';
+Recordings are stored as JSON files with `.mock.json` extension:
 
-async function globalTeardown() {
-  await setProxyMode('transparent');
-}
-
-export default globalTeardown;
+```text
+e2e/recordings/
+├── create-a-user.mock.json
+├── fetch-users-list.mock.json
+└── delete-user.mock.json
 ```
 
-#### 2. Create Global Hooks File
+## Troubleshooting
 
-Create `e2e/global-hooks.ts` to ensure proxy cleanup happens after each test, even on failure:
+### Proxy not responding
 
-```typescript
-import { test } from '@playwright/test';
-import { playwrightProxy } from 'test-proxy-recorder';
+**Check if proxy is running**:
 
-/**
- * Global afterEach hook to ensure proxy cleanup happens even when tests fail.
- * This will run after every test across all test files.
- */
-test.afterEach(async ({}, testInfo) => {
-  try {
-    await playwrightProxy.after(testInfo);
-  } catch (error) {
-    console.error('Error during proxy cleanup:', error);
-    // Don't throw - we want cleanup to continue even if this fails
-  }
-});
+```bash
+curl http://localhost:8100/__control
 ```
 
-#### 3. Configure Playwright
+**Check port availability**:
 
-Update your `playwright.config.ts` to include the global teardown:
+```bash
+lsof -i :8100
+```
 
-```typescript
-import { defineConfig } from '@playwright/test';
+### No recordings saved
 
-export default defineConfig({
-  testDir: './e2e',
-  globalTeardown: './e2e/global-teardown.ts',
-  // ... rest of your config
-});
-```
+- 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
 
-#### 4. Import Global Hooks in Your Base Page or Test Setup
+### Test fails in replay mode
 
-Import the global hooks file in your base test file or base page to register the afterEach hook:
+- Ensure recording exists for this test
+- Check test name hasn't changed
+- Verify recording file matches expected format
+- Re-record if API responses changed
 
-```typescript
-// In your e2e/basePage.ts or similar base test file
-import { test as base } from '@playwright/test';
+### Recordings not matching requests
 
-// Import global hooks to register afterEach for proxy cleanup
-import './global-hooks';
+- Request URLs must match exactly
+- Headers may affect matching (configurable)
+- Query parameters must be in same order
+- Re-record to capture current API behavior
 
-export const test = base.extend({
-  // your fixtures
-});
-```
 
-## Recording Format
+## API Reference
 
-Recordings are stored as JSON files with `.mock.json` extension in the recordings directory:
+### ProxyServer Class
 
-```text
-recordings/
-├── test-session-1.mock.json
-├── test-session-2.mock.json
-└── ...
+```typescript
+class ProxyServer {
+  constructor(targets: string[], recordingsDir: string);
+  async init(): Promise<void>;
+  listen(port: number): http.Server;
+}
 ```
 
-Each recording contains:
+### Playwright Integration
 
-- Request/response pairs with headers and bodies
-- WebSocket messages with timestamps
-- Unique keys for request matching during replay
+```typescript
+import { playwrightProxy, setProxyMode } from 'test-proxy-recorder';
 
-## Typical Workflow
+// Main helper for Playwright tests
+const playwrightProxy = {
+  // Set proxy mode before test
+  async before(
+    testInfo: TestInfo,
+    mode: 'record' | 'replay' | 'transparent',
+    timeout?: number
+  ): Promise<void>;
 
-1. **Start the proxy server** (runs continuously):
+  // Reset to transparent mode after test
+  async after(testInfo: TestInfo): Promise<void>;
+};
 
-   ```bash
-   test-proxy-recorder http://localhost:8000 --port 8100
-   ```
+// Direct mode control
+async function setProxyMode(
+  mode: 'record' | 'replay' | 'transparent',
+  id?: string,
+  timeout?: number
+): Promise<void>;
+```
 
-2. **Configure your app** to use the proxy (point your app to the proxy port, e.g., 8100)
+### Control Endpoint
+
+**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