bmad-method 6.0.0-alpha.12 → 6.0.0-alpha.13

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

@@ -0,0 +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
+});
+```

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

@@ -0,0 +1,284 @@
+# Playwright Utils Overview
+
+## 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.
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **Production-tested utilities**: Used at SEON Technologies in production
+- **Functional-first design**: Core logic as pure functions, fixtures for convenience
+- **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
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `js-yaml` >= 4.0.0 (optional - for YAML schema support)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### 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      |
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** https://github.com/seontechnologies/playwright-utils
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.