test-proxy-recorder 0.3.1 → 0.3.3

package/README.md

@@ -268,6 +268,67 @@ export default defineConfig({
 });
 ```
 
+### Client-Side Recording for 3rd Party APIs
+
+For applications that make client-side requests to 3rd party services (e.g., AWS Cognito, Stream.io, analytics services), you can use client-side recording to capture these requests directly in the browser using Playwright's HAR (HTTP Archive) format.
+
+**Why use client-side recording?**
+- Server-side proxy cannot intercept requests made directly from the browser to external services
+- HAR files are a standard format supported by Playwright and browser dev tools
+- Automatically handles CORS and other browser-specific request behaviors
+
+**Example:**
+
+```typescript
+import { test } from '@playwright/test';
+import { playwrightProxy } from 'test-proxy-recorder';
+
+test('authentication flow', async ({ page }, testInfo) => {
+  // Record both server-side (via proxy) and client-side (via HAR) requests
+  await playwrightProxy.before(
+    page,
+    testInfo,
+    'replay',
+    {
+      // Client-side URL pattern using Playwright's format
+      url: /cognito-.*amazonaws\.com|\.stream-io-api\.com/,
+      timeout: 60000 // Optional: custom timeout
+    }
+  );
+
+  await page.goto('/login');
+  // Cognito authentication requests are recorded to HAR files
+  await page.fill('[name="email"]', 'user@example.com');
+  await page.click('button[type="submit"]');
+});
+```
+
+**URL Pattern Options:**
+```typescript
+// RegExp pattern (recommended for multiple domains)
+{ url: /cognito-.*amazonaws\.com|\.stream-io-api\.com/ }
+
+// String glob pattern
+{ url: 'https://api.example.com/**' }
+
+// Specific domain
+{ url: /api\.external-service\.com/ }
+```
+
+**Storage:**
+Client-side recordings are stored as HAR files alongside server-side recordings:
+```
+e2e/recordings/
+├── my-test.mock.json  # Server-side recordings (proxy)
+└── my-test.har        # Client-side recordings (browser)
+```
+
+**Recording vs Replay:**
+- **Record mode**: Creates/updates HAR file with actual responses from 3rd party services
+- **Replay mode**: Uses recorded HAR file, no network requests made to 3rd party services
+
+**Note:** The recordings directory is automatically retrieved from the proxy server, ensuring both server-side and client-side recordings are stored in the same location.
+
 ## Next.js Integration
 
 When testing Next.js applications with server-side rendering (SSR) or API routes, you need to ensure the recording ID header is forwarded to the proxy. The package provides helpers for this.
@@ -342,10 +403,37 @@ export async function GET() {
 
 ## Control Endpoint
 
-The proxy exposes a control endpoint at `/__control` for programmatic mode switching.
+The proxy exposes a control endpoint at `/__control` for programmatic mode switching and configuration retrieval.
+
+### GET - Retrieve Proxy Configuration
+
+Get the current proxy configuration including recordings directory, mode, and active session ID.
+
+**Via HTTP:**
+```bash
+curl http://localhost:8100/__control
+```
+
+**Response:**
+```json
+{
+  "recordingsDir": "/path/to/e2e/recordings",
+  "mode": "replay",
+  "id": "my-test-1"
+}
+```
+
+**Via JavaScript:**
+```javascript
+const config = await fetch('http://localhost:8100/__control').then(r => r.json());
+console.log(config.recordingsDir); // "/path/to/e2e/recordings"
+console.log(config.mode);          // "replay"
+console.log(config.id);            // "my-test-1"
+```
 
-### Via HTTP
+### POST - Switch Proxy Mode
 
+**Via HTTP:**
 ```bash
 # Switch to record mode
 curl -X POST http://localhost:8100/__control \
@@ -363,8 +451,7 @@ curl -X POST http://localhost:8100/__control \
   -d '{"mode": "transparent"}'
 ```
 
-### Via JavaScript
-
+**Via JavaScript:**
 ```javascript
 await fetch('http://localhost:8100/__control', {
   method: 'POST',
@@ -385,6 +472,12 @@ interface ControlRequest {
   id?: string;      // Recording ID, required for record/replay
   timeout?: number; // Auto-reset timeout in ms (default: 120000)
 }
+
+interface ControlResponse {
+  recordingsDir: string;
+  mode: string;
+  id?: string;
+}
 ```
 
 ## Typical Workflow
@@ -414,15 +507,21 @@ interface ControlRequest {
 
 ## Recording Format
 
-Recordings are stored as JSON files with `.mock.json` extension:
+Recordings are stored in two formats depending on the recording type:
+
+**Server-side recordings** (via proxy): JSON files with `.mock.json` extension
+**Client-side recordings** (via HAR): HTTP Archive files with `.har` extension
 
 ```text
 e2e/recordings/
-├── create-a-user.mock.json
+├── create-a-user.mock.json       # Server-side API calls
+├── create-a-user.har             # Client-side 3rd party requests
 ├── fetch-users-list.mock.json
 └── delete-user.mock.json
 ```
 
+Both file types use the same naming convention based on the test name, making it easy to identify which recordings belong to which test.
+
 ## Troubleshooting
 
 ### Proxy not responding
@@ -479,18 +578,28 @@ class ProxyServer {
 import { playwrightProxy, setProxyMode, RECORDING_ID_HEADER } from 'test-proxy-recorder';
 import type { Page } from '@playwright/test';
 
+// Client-side recording options
+interface ClientSideRecordingOptions {
+  /**
+   * URL pattern for client-side requests to record/replay
+   * Uses Playwright's native format (string or RegExp)
+   * Example: /cognito-.*amazonaws\.com|\.stream-io-api\.com/
+   * Example: 'https://api.example.com/**'
+   */
+  url?: string | RegExp;
+}
+
 // Main helper for Playwright tests
 const playwrightProxy = {
   // Set proxy mode before test and configure page with recording ID header
-  // Automatically sets up page.on('close') handler for cleanup
+  // Supports optional client-side recording for 3rd party APIs
   async before(
     page: Page,
     testInfo: TestInfo,
     mode: 'record' | 'replay' | 'transparent',
-    timeout?: number
+    options?: number | (ClientSideRecordingOptions & { timeout?: number })
   ): Promise<void>;
 
-
   // Global teardown - switches proxy to transparent mode
   // Use in Playwright's globalTeardown configuration
   async teardown(): Promise<void>;
@@ -507,6 +616,12 @@ async function setProxyMode(
 const RECORDING_ID_HEADER: string; // 'x-test-rcrd-id'
 ```
 
+**Options Parameter:**
+- `number` - Legacy format: timeout in milliseconds
+- `ClientSideRecordingOptions & { timeout?: number }` - Object with optional client-side recording and timeout:
+  - `url?: string | RegExp` - URL pattern for client-side recording (uses Playwright's HAR format)
+  - `timeout?: number` - Auto-reset timeout in milliseconds
+
 ### Next.js Integration
 
 **IMPORTANT**: Use the `/nextjs` import path to avoid webpack bundling issues in Next.js:
@@ -541,31 +656,41 @@ function createHeadersWithRecordingId(
 
 ### Control Endpoint
 
-**Endpoint**: `POST http://localhost:8100/__control`
+The control endpoint supports both GET and POST methods.
 
-**Request Body**:
+**GET `/__control`** - Retrieve proxy configuration:
 
 ```typescript
+// Response
 {
-  mode: 'transparent' | 'record' | 'replay';
-  id?: string;      // Recording ID (required for record/replay)
-  timeout?: number; // Auto-reset timeout in ms (default: 120000)
+  recordingsDir: string;  // Path to recordings directory
+  mode: string;           // Current mode: 'transparent' | 'record' | 'replay'
+  id?: string;            // Active recording/replay session ID
 }
 ```
 
-**Note**: Switching to replay mode automatically resets session counters (clears served recordings tracker), allowing replay from the beginning.
-
-**Response**:
+**POST `/__control`** - Switch proxy mode:
 
 ```typescript
+// Request Body
+{
+  mode: 'transparent' | 'record' | 'replay';
+  id?: string;      // Recording ID (required for record/replay)
+  timeout?: number; // Auto-reset timeout in ms (default: 120000)
+}
+
+// Response
 {
   success: boolean;
   mode: string;
   id: string | null;
   timeout: number;
+  recordingsDir: string;
 }
 ```
 
+**Note**: Switching to replay mode automatically resets session counters (clears served recordings tracker), allowing replay from the beginning.
+
 ## Requirements
 
 - Node.js >= 22.0.0

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

@@ -8,9 +8,10 @@ declare const Modes: {
 };
 type Mode = (typeof Modes)[keyof typeof Modes];
 interface ControlRequest {
-    mode: Mode;
+    mode?: Mode;
     id?: string;
     timeout?: number;
+    cleanup?: boolean;
 }
 interface RecordedRequest {
     method: string;
@@ -56,6 +57,11 @@ type PlaywrightTestInfo = Pick<TestInfo, 'title' | 'titlePath'>;
  * @param timeout - Optional timeout in milliseconds
  */
 declare function setProxyMode(mode: Mode, sessionId?: string, timeout?: number): Promise<void>;
+/**
+ * Clean up a specific session - removes it from memory and resets counters
+ * @param sessionId - The session ID to clean up
+ */
+declare function cleanupSession(sessionId: string): Promise<void>;
 /**
  * Generate a session ID from test info
  * Uses titlePath to create folder structure with test file name
@@ -84,6 +90,15 @@ declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
  * Playwright test fixture helper for managing proxy mode
  * Use this in test functions with page.on('close') for automatic cleanup
  */
+interface ClientSideRecordingOptions {
+    /**
+     * URL pattern for client-side requests to record/replay
+     * Uses Playwright's native format (string or RegExp)
+     * Example: /cognito-.*amazonaws\.com|\.stream-io-api\.com/
+     * Example: 'https://api.example.com/**'
+     */
+    url?: string | RegExp;
+}
 declare const playwrightProxy: {
     /**
      * Setup before test - sets the proxy mode and configures page with custom header
@@ -91,9 +106,11 @@ declare const playwrightProxy: {
      * @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
+     * @param options - Optional configuration including timeout and client-side recording patterns
      */
-    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
+    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, options?: number | (ClientSideRecordingOptions & {
+        timeout?: number;
+    })): Promise<void>;
     /**
      * Global teardown - switches proxy to transparent mode
      * Use this in Playwright's globalTeardown to ensure clean state
@@ -101,4 +118,4 @@ declare const playwrightProxy: {
     teardown(): 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 };
+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, cleanupSession as e, type ClientSideRecordingOptions as f, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

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

@@ -8,9 +8,10 @@ declare const Modes: {
 };
 type Mode = (typeof Modes)[keyof typeof Modes];
 interface ControlRequest {
-    mode: Mode;
+    mode?: Mode;
     id?: string;
     timeout?: number;
+    cleanup?: boolean;
 }
 interface RecordedRequest {
     method: string;
@@ -56,6 +57,11 @@ type PlaywrightTestInfo = Pick<TestInfo, 'title' | 'titlePath'>;
  * @param timeout - Optional timeout in milliseconds
  */
 declare function setProxyMode(mode: Mode, sessionId?: string, timeout?: number): Promise<void>;
+/**
+ * Clean up a specific session - removes it from memory and resets counters
+ * @param sessionId - The session ID to clean up
+ */
+declare function cleanupSession(sessionId: string): Promise<void>;
 /**
  * Generate a session ID from test info
  * Uses titlePath to create folder structure with test file name
@@ -84,6 +90,15 @@ declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
  * Playwright test fixture helper for managing proxy mode
  * Use this in test functions with page.on('close') for automatic cleanup
  */
+interface ClientSideRecordingOptions {
+    /**
+     * URL pattern for client-side requests to record/replay
+     * Uses Playwright's native format (string or RegExp)
+     * Example: /cognito-.*amazonaws\.com|\.stream-io-api\.com/
+     * Example: 'https://api.example.com/**'
+     */
+    url?: string | RegExp;
+}
 declare const playwrightProxy: {
     /**
      * Setup before test - sets the proxy mode and configures page with custom header
@@ -91,9 +106,11 @@ declare const playwrightProxy: {
      * @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
+     * @param options - Optional configuration including timeout and client-side recording patterns
      */
-    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
+    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, options?: number | (ClientSideRecordingOptions & {
+        timeout?: number;
+    })): Promise<void>;
     /**
      * Global teardown - switches proxy to transparent mode
      * Use this in Playwright's globalTeardown to ensure clean state
@@ -101,4 +118,4 @@ declare const playwrightProxy: {
     teardown(): 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 };
+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, cleanupSession as e, type ClientSideRecordingOptions as f, generateSessionId as g, playwrightProxy as p, setProxyMode as s };