bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/src/modules/bmm/testarch/knowledge/network-recorder.md

@@ -21,6 +21,46 @@ HAR-based recording/playback provides:
 - **Stateful mocking**: CRUD operations work naturally (not just read-only)
 - **Environment flexibility**: Map URLs for any environment
 
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
 ## Pattern Examples
 
 ### Example 1: Basic Record and Playback
@@ -115,74 +155,173 @@ test.describe('Movie CRUD - offline with network recorder', () => {
 - Combine with `interceptNetworkCall` for deterministic waits
 - First run records, subsequent runs replay
 
-### Example 3: Environment Switching
+### Example 3: Common Patterns
 
-**Context**: Record in dev environment, play back in CI with different base URLs.
+**Recording Only API Calls**:
 
-**Implementation**:
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\// // Only record API calls, ignore static assets
+  }
+});
+```
+
+**Playback with Fallback**:
 
 ```typescript
-// playwright.config.ts - Map URLs for different environments
-export default defineConfig({
-  use: {
-    baseURL: process.env.CI ? 'https://app.ci.example.com' : 'http://localhost:3000',
-  },
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true // Fall back to live requests if HAR entry missing
+  }
 });
+```
 
-// Test works in both environments
-test('cross-environment playback', async ({ page, context, networkRecorder }) => {
-  await networkRecorder.setup(context);
+**Custom HAR File Location**:
 
-  // In dev: hits http://localhost:3000/api/movies
-  // In CI: HAR replays with https://app.ci.example.com/api/movies
-  await page.goto('/movies');
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false // Optional: flatten directory structure
+  }
+});
+```
 
-  // Network recorder auto-maps URLs
-  await expect(page.getByTestId('movie-list')).toBeVisible();
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed' // Store content inline (default)
+  }
 });
 ```
 
-**Key Points**:
+**Pros:**
 
-- HAR files record absolute URLs
-- Playback maps to current baseURL
-- Same HAR works across environments
-- No manual URL rewriting needed
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
 
-### Example 4: Automatic vs Manual Mode Control
+**Cons:**
 
-**Context**: Choose between environment-based switching or in-test mode control.
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
 
-**Implementation**:
+**`attach` (Alternative):**
 
 ```typescript
-// Option 1: Environment variable (recommended for CI)
-PW_NET_MODE=record npm run test:pw   # Record traffic
-PW_NET_MODE=playback npm run test:pw # Playback traffic
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach' // Store content separately
+  }
+});
+```
 
-// Option 2: In-test control (recommended for development)
-process.env.PW_NET_MODE = 'record'  // Set at top of test file
+**Pros:**
 
-test('my test', async ({ page, context, networkRecorder }) => {
-  await networkRecorder.setup(context)
-  // ...
-})
-
-// Option 3: Auto-fallback (record if HAR missing, else playback)
-// This is the default behavior when PW_NET_MODE not set
-test('auto mode', async ({ page, context, networkRecorder }) => {
-  await networkRecorder.setup(context)
-  // First run: auto-records
-  // Subsequent runs: auto-plays back
-})
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when | Use `attach` when |
+|---------------------------|-------------------|
+| Recording API responses (JSON, XML) | Recording large images, videos |
+| Small to medium HTML pages | HAR file size >50MB |
+| You want a single, portable file | Maximum disk efficiency needed |
+| Sharing HAR files with team | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com'
+      }
+    }
+  }
+});
 ```
 
-**Key Points**:
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' }
+      ]
+    }
+  }
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com')
+    }
+  }
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.seondev.space',
+        'admin-staging.seon.io': 'admin.seondev.space',
+        'admin.seon.io': 'admin.seondev.space',
+      },
+      patterns: [
+        { match: /admin-\d+\.seondev\.space/, replace: 'admin.seondev.space' },
+        { match: /admin-staging-pr-\w+-\d\.seon\.io/, replace: 'admin.seondev.space' }
+      ]
+    }
+  }
+});
+```
+
+**Benefits:**
 
-- Three mode options: record, playback, auto
-- `PW_NET_MODE` environment variable
-- In-test `process.env.PW_NET_MODE` assignment
-- Auto-fallback when no mode specified
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
 
 ## Why Use This Instead of Native Playwright?
 
@@ -191,7 +330,7 @@ test('auto mode', async ({ page, context, networkRecorder }) => {
 | ~80 lines setup boilerplate        | ~5 lines total                 |
 | Manual HAR file management         | Automatic file organization    |
 | Complex setup/teardown             | Automatic cleanup via fixtures |
-| **Read-only tests**                | **Full CRUD support**          |
+| **Read-only tests only**           | **Full CRUD support**          |
 | **Stateless**                      | **Stateful mocking**           |
 | Manual URL mapping                 | Automatic environment mapping  |
 
@@ -199,9 +338,132 @@ test('auto mode', async ({ page, context, networkRecorder }) => {
 
 Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
 
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                           |
+| -------------------- | ------------------------ | ----------------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context         |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory             |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information             |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message                    |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata                 |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string // Directory for HAR files (default: 'har-files')
+    baseName?: string // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean // Organize by test file (default: true)
+  }
+
+  recording?: {
+    content?: 'embed' | 'attach' // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp // URL filter for recording
+    update?: boolean // Update existing HAR files (default: false)
+  }
+
+  playback?: {
+    fallback?: boolean // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp // URL filter for playback
+    updateMode?: boolean // Update mode during playback (default: false)
+  }
+
+  forceMode?: 'record' | 'playback' | 'disabled'
+}
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
 ## Integration with Other Utilities
 
-**With interceptNetworkCall** (deterministic waits):
+**With interceptNetworkCall (deterministic waits):**
 
 ```typescript
 test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
@@ -228,7 +490,7 @@ test('use both utilities', async ({ page, context, networkRecorder, interceptNet
 
 ## Anti-Patterns
 
-**❌ Mixing record and playback in same test:**
+**DON'T mix record and playback in same test:**
 
 ```typescript
 process.env.PW_NET_MODE = 'record';
@@ -236,7 +498,7 @@ process.env.PW_NET_MODE = 'record';
 process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
 ```
 
-**✅ One mode per test:**
+**DO use one mode per test:**
 
 ```typescript
 process.env.PW_NET_MODE = 'playback'; // Set once at top
@@ -247,7 +509,7 @@ test('my test', async ({ page, context, networkRecorder }) => {
 });
 ```
 
-**❌ Forgetting to call setup:**
+**DON'T forget to call setup:**
 
 ```typescript
 test('broken', async ({ page, networkRecorder }) => {
@@ -255,7 +517,7 @@ test('broken', async ({ page, networkRecorder }) => {
 });
 ```
 
-**✅ Always call setup before navigation:**
+**DO always call setup before navigation:**
 
 ```typescript
 test('correct', async ({ page, context, networkRecorder }) => {

package/src/modules/bmm/testarch/knowledge/overview.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse.
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
 
 ## Rationale
 
@@ -20,6 +20,7 @@ Writing Playwright utilities from scratch for every project leads to:
 - **Composable fixtures**: Use `mergeTests` to combine utilities
 - **TypeScript support**: Full type safety with generic types
 - **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
 
 ## Installation
 
@@ -37,17 +38,19 @@ npm install -D @seontechnologies/playwright-utils
 
 ### Core Testing Utilities
 
-| Utility                    | Purpose                                    | Test Context  |
-| -------------------------- | ------------------------------------------ | ------------- |
-| **api-request**            | Typed HTTP client with schema validation   | API tests     |
-| **network-recorder**       | HAR record/playback for offline testing    | UI tests      |
-| **auth-session**           | Token persistence, multi-user auth         | Both UI & API |
-| **recurse**                | Cypress-style polling for async conditions | Both UI & API |
-| **intercept-network-call** | Network spy/stub with auto JSON parsing    | UI tests      |
-| **log**                    | Playwright report-integrated logging       | Both UI & API |
-| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation      | Both UI & API |
-| **burn-in**                | Smart test selection with git diff         | CI/CD         |
-| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection           | UI tests      |
+| Utility                    | Purpose                                              | Test Context       |
+| -------------------------- | ---------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation and retry   | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs        | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service    | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                 | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                   | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing              | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing              | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                     | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
 
 ## Design Patterns