siesa-agents 2.1.40 → 2.1.42

package/bmad/bmm/testarch/knowledge/network-recorder.md

@@ -1,265 +1,265 @@
-# Network Recorder Utility
-
-## Principle
-
-Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
-
-## Rationale
-
-Traditional E2E tests require live backend services:
-
-- Slow (real network latency)
-- Flaky (backend instability affects tests)
-- Expensive (full stack running for UI tests)
-- Coupled (UI tests break when API changes)
-
-HAR-based recording/playback provides:
-
-- **True offline testing**: UI tests run without backend
-- **Deterministic behavior**: Same responses every time
-- **Fast execution**: No network latency
-- **Stateful mocking**: CRUD operations work naturally (not just read-only)
-- **Environment flexibility**: Map URLs for any environment
-
-## Pattern Examples
-
-### Example 1: Basic Record and Playback
-
-**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
-
-**Implementation**:
-
-```typescript
-import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
-
-// Set mode in test file (recommended)
-process.env.PW_NET_MODE = 'playback'; // or 'record'
-
-test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
-  // Setup recorder (records or plays back based on PW_NET_MODE)
-  await networkRecorder.setup(context);
-
-  await page.goto('/');
-
-  // First time (record mode): Records all network traffic to HAR
-  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
-  await page.fill('#movie-name', 'Inception');
-  await page.click('#add-movie');
-
-  // Intelligent CRUD detection makes this work offline!
-  await expect(page.getByText('Inception')).toBeVisible();
-});
-```
-
-**Key Points**:
-
-- `PW_NET_MODE=record` captures traffic to HAR files
-- `PW_NET_MODE=playback` replays from HAR files
-- Set mode in test file or via environment variable
-- HAR files auto-organized by test name
-- Stateful mocking detects CRUD operations
-
-### Example 2: Complete CRUD Flow with HAR
-
-**Context**: Full create-read-update-delete flow that works completely offline.
-
-**Implementation**:
-
-```typescript
-process.env.PW_NET_MODE = 'playback';
-
-test.describe('Movie CRUD - offline with network recorder', () => {
-  test.beforeEach(async ({ page, networkRecorder, context }) => {
-    await networkRecorder.setup(context);
-    await page.goto('/');
-  });
-
-  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
-    // Create
-    await page.fill('#movie-name', 'Inception');
-    await page.fill('#year', '2010');
-    await page.click('#add-movie');
-
-    // Verify create (reads from stateful HAR)
-    await expect(page.getByText('Inception')).toBeVisible();
-
-    // Update
-    await page.getByText('Inception').click();
-    await page.fill('#movie-name', "Inception Director's Cut");
-
-    const updateCall = interceptNetworkCall({
-      method: 'PUT',
-      url: '/movies/*',
-    });
-
-    await page.click('#save');
-    await updateCall; // Wait for update
-
-    // Verify update (HAR reflects state change!)
-    await page.click('#back');
-    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
-
-    // Delete
-    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
-
-    // Verify delete (HAR reflects removal!)
-    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
-  });
-});
-```
-
-**Key Points**:
-
-- Full CRUD operations work offline
-- Stateful HAR mocking tracks creates/updates/deletes
-- Combine with `interceptNetworkCall` for deterministic waits
-- First run records, subsequent runs replay
-
-### Example 3: Environment Switching
-
-**Context**: Record in dev environment, play back in CI with different base URLs.
-
-**Implementation**:
-
-```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',
-  },
-});
-
-// Test works in both environments
-test('cross-environment playback', async ({ page, context, networkRecorder }) => {
-  await networkRecorder.setup(context);
-
-  // In dev: hits http://localhost:3000/api/movies
-  // In CI: HAR replays with https://app.ci.example.com/api/movies
-  await page.goto('/movies');
-
-  // Network recorder auto-maps URLs
-  await expect(page.getByTestId('movie-list')).toBeVisible();
-});
-```
-
-**Key Points**:
-
-- HAR files record absolute URLs
-- Playback maps to current baseURL
-- Same HAR works across environments
-- No manual URL rewriting needed
-
-### Example 4: Automatic vs Manual Mode Control
-
-**Context**: Choose between environment-based switching or in-test mode control.
-
-**Implementation**:
-
-```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
-
-// Option 2: In-test control (recommended for development)
-process.env.PW_NET_MODE = 'record'  // Set at top of test file
-
-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
-})
-```
-
-**Key Points**:
-
-- 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
-
-## Why Use This Instead of Native Playwright?
-
-| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
-| ---------------------------------- | ------------------------------ |
-| ~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**          |
-| **Stateless**                      | **Stateful mocking**           |
-| Manual URL mapping                 | Automatic environment mapping  |
-
-**The game-changer: Stateful CRUD detection**
-
-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.
-
-## Integration with Other Utilities
-
-**With interceptNetworkCall** (deterministic waits):
-
-```typescript
-test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
-  await networkRecorder.setup(context);
-
-  const createCall = interceptNetworkCall({
-    method: 'POST',
-    url: '/api/movies',
-  });
-
-  await page.click('#add-movie');
-  await createCall; // Wait for create (works with HAR!)
-
-  // Network recorder provides playback, intercept provides determinism
-});
-```
-
-## Related Fragments
-
-- `overview.md` - Installation and fixture patterns
-- `intercept-network-call.md` - Combine for deterministic offline tests
-- `auth-session.md` - Record authenticated traffic
-- `network-first.md` - Core pattern for intercept-before-navigate
-
-## Anti-Patterns
-
-**❌ Mixing record and playback in same test:**
-
-```typescript
-process.env.PW_NET_MODE = 'record';
-// ... some test code ...
-process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
-```
-
-**✅ One mode per test:**
-
-```typescript
-process.env.PW_NET_MODE = 'playback'; // Set once at top
-
-test('my test', async ({ page, context, networkRecorder }) => {
-  await networkRecorder.setup(context);
-  // Entire test uses playback mode
-});
-```
-
-**❌ Forgetting to call setup:**
-
-```typescript
-test('broken', async ({ page, networkRecorder }) => {
-  await page.goto('/'); // HAR not active!
-});
-```
-
-**✅ Always call setup before navigation:**
-
-```typescript
-test('correct', async ({ page, context, networkRecorder }) => {
-  await networkRecorder.setup(context); // Must setup first
-  await page.goto('/'); // Now HAR is active
-});
-```
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Environment Switching
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**Implementation**:
+
+```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',
+  },
+});
+
+// Test works in both environments
+test('cross-environment playback', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+
+  // In dev: hits http://localhost:3000/api/movies
+  // In CI: HAR replays with https://app.ci.example.com/api/movies
+  await page.goto('/movies');
+
+  // Network recorder auto-maps URLs
+  await expect(page.getByTestId('movie-list')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files record absolute URLs
+- Playback maps to current baseURL
+- Same HAR works across environments
+- No manual URL rewriting needed
+
+### Example 4: Automatic vs Manual Mode Control
+
+**Context**: Choose between environment-based switching or in-test mode control.
+
+**Implementation**:
+
+```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
+
+// Option 2: In-test control (recommended for development)
+process.env.PW_NET_MODE = 'record'  // Set at top of test file
+
+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
+})
+```
+
+**Key Points**:
+
+- 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
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~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**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+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.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall** (deterministic waits):
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**❌ Mixing record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**✅ One mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**❌ Forgetting to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**✅ Always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```