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

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.

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

@@ -0,0 +1,296 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Polling with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // Use assertions instead of boolean returns
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // If assertions pass, predicate succeeds
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Key Points**:
+
+- Predicate can use `expect()` assertions
+- If assertions throw, polling continues
+- If assertions pass, polling succeeds
+- More expressive than boolean returns
+
+### Example 3: Custom Error Messages
+
+**Context**: Provide context-specific error messages for timeout failures.
+
+**Implementation**:
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `error` option provides custom message
+- Replaces default "Timed out after X ms"
+- Include debugging hints in error message
+- Helps diagnose failures faster
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## Enhanced Error Types
+
+The utility categorizes errors for easier debugging:
+
+```typescript
+// TimeoutError - Predicate never returned true
+Error: Polling timed out after 30000ms: Job never completed
+
+// CommandError - Command function threw
+Error: Command failed: Request failed with status 500
+
+// PredicateError - Predicate function threw (not from assertions)
+Error: Predicate failed: Cannot read property 'status' of undefined
+```
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- ✅ Background job completion
+- ✅ Webhook/event processing
+- ✅ Database eventual consistency
+- ✅ Cache propagation
+- ✅ State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+
+## Anti-Patterns
+
+**❌ Using hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**✅ Poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**❌ Polling too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**✅ Reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```

package/src/modules/bmm/testarch/tea-index.csv

@@ -20,3 +20,14 @@ test-priorities,Test Priorities Matrix,"P0–P3 criteria, coverage targets, exec
 test-healing-patterns,Test Healing Patterns,"Common failure patterns and automated fixes","healing,debugging,patterns",knowledge/test-healing-patterns.md
 selector-resilience,Selector Resilience,"Robust selector strategies and debugging techniques","selectors,locators,debugging",knowledge/selector-resilience.md
 timing-debugging,Timing Debugging,"Race condition identification and deterministic wait fixes","timing,async,debugging",knowledge/timing-debugging.md
+overview,Playwright Utils Overview,"Installation, design principles, fixture patterns","playwright-utils,fixtures",knowledge/overview.md
+api-request,API Request,"Typed HTTP client, schema validation","api,playwright-utils",knowledge/api-request.md
+network-recorder,Network Recorder,"HAR record/playback, CRUD detection","network,playwright-utils",knowledge/network-recorder.md
+auth-session,Auth Session,"Token persistence, multi-user","auth,playwright-utils",knowledge/auth-session.md
+intercept-network-call,Intercept Network Call,"Network spy/stub, JSON parsing","network,playwright-utils",knowledge/intercept-network-call.md
+recurse,Recurse Polling,"Async polling, condition waiting","polling,playwright-utils",knowledge/recurse.md
+log,Log Utility,"Report logging, structured output","logging,playwright-utils",knowledge/log.md
+file-utils,File Utilities,"CSV/XLSX/PDF/ZIP validation","files,playwright-utils",knowledge/file-utils.md
+burn-in,Burn-in Runner,"Smart test selection, git diff","ci,playwright-utils",knowledge/burn-in.md
+network-error-monitor,Network Error Monitor,"HTTP 4xx/5xx detection","monitoring,playwright-utils",knowledge/network-error-monitor.md
+fixtures-composition,Fixtures Composition,"mergeTests composition patterns","fixtures,playwright-utils",knowledge/fixtures-composition.md

package/src/modules/bmm/workflows/1-analysis/product-brief/product-brief.template.md

@@ -0,0 +1,8 @@
+# Product Brief: {{project_name}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+
+---
+
+<!-- Content will be appended sequentially through collaborative workflow steps -->