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

package/src/modules/bmm/testarch/knowledge/intercept-network-call.md

@@ -183,7 +183,31 @@ test('should handle timeout', async ({ page, interceptNetworkCall }) => {
 - Validate error UI states
 - No real failures needed
 
-### Example 5: Multiple Intercepts (Order Matters!)
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
 
 **Context**: Intercepting different endpoints in same test - setup order is critical.
 
@@ -191,7 +215,7 @@ test('should handle timeout', async ({ page, interceptNetworkCall }) => {
 
 ```typescript
 test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
-  // ✅ CORRECT: Setup all intercepts BEFORE navigation
+  // Setup all intercepts BEFORE navigation
   const usersCall = interceptNetworkCall({ url: '**/api/users' });
   const productsCall = interceptNetworkCall({ url: '**/api/products' });
   const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
@@ -211,11 +235,85 @@ test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
 
 - Setup all intercepts before triggering actions
 - Use `Promise.all()` to wait for multiple calls
-- Order: intercept → navigate → await
+- Order: intercept -> navigate -> await
 - Prevents race conditions
 
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
 ## URL Pattern Matching
 
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
 **Supported glob patterns:**
 
 ```typescript
@@ -226,7 +324,59 @@ test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
 '**/api/users?id=*'; // With query params
 ```
 
-**Uses picomatch library** - same pattern syntax as Playwright's `page.route()` but cleaner API.
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return (
+    url.endsWith('/api/users') ||
+    url.match(/\/api\/users\/\d+/) ||
+    (url.includes('/api/users/') && url.includes('/profile'))
+  );
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
 
 ## Comparison with Vanilla Playwright
 
@@ -238,7 +388,7 @@ test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
 | `const status = resp.status()`                              | `const { status } = await call`                              |
 | Complex filter predicates                                   | Simple glob patterns                                         |
 
-**Reduction:** ~5-7 lines → ~2-3 lines per interception
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
 
 ## Related Fragments
 
@@ -248,14 +398,14 @@ test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
 
 ## Anti-Patterns
 
-**❌ Intercepting after navigation:**
+**DON'T intercept after navigation:**
 
 ```typescript
 await page.goto('/dashboard'); // Navigation starts
 const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
 ```
 
-**✅ Intercept before navigate:**
+**DO intercept before navigate:**
 
 ```typescript
 const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
@@ -263,7 +413,7 @@ await page.goto('/dashboard'); // Then navigate
 const { responseJson } = await usersCall; // Then await
 ```
 
-**❌ Ignoring the returned Promise:**
+**DON'T ignore the returned Promise:**
 
 ```typescript
 interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
@@ -271,7 +421,7 @@ await page.goto('/dashboard');
 // No deterministic wait - race condition
 ```
 
-**✅ Always await the intercept:**
+**DO always await the intercept:**
 
 ```typescript
 const usersCall = interceptNetworkCall({ url: '**/api/users' });

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

@@ -21,6 +21,20 @@ The `log` utility provides:
 - **Multiple levels**: info, step, success, warning, error, debug
 - **Optional console**: Can disable console output but keep report logs
 
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
 ## Pattern Examples
 
 ### Example 1: Basic Logging Levels
@@ -143,41 +157,105 @@ test('organized with steps', async ({ page, apiRequest }) => {
 - Steps visible in Playwright trace viewer
 - Better debugging when tests fail
 
-### Example 4: Conditional Logging
+### Example 4: Test Step Decorators
 
-**Context**: Log different messages based on environment or test conditions.
+**Context**: Create collapsible test steps in Playwright UI using decorators.
 
-**Implementation**:
+**Page Object Methods with @methodTestStep:**
 
 ```typescript
-test('conditional logging', async ({ page }) => {
-  const isCI = process.env.CI === 'true';
+import { methodTestStep } from '@seontechnologies/playwright-utils';
 
-  if (isCI) {
-    await log.info('Running in CI environment');
-  } else {
-    await log.debug('Running locally');
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
   }
 
-  const isKafkaWorking = await checkKafkaHealth();
+  readonly name: string;
 
-  if (!isKafkaWorking) {
-    await log.warning('Kafka unavailable - skipping event checks');
-  } else {
-    await log.step('Verifying Kafka events');
-    // ... event verification
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
   }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
 });
+
+const checkNumberOfTodosInLocalStorage = functionTestStep(
+  'Check total todos count fn-step',
+  async (page: Page, expected: number) => {
+    await log.info(`Verifying todo count: ${expected}`);
+    const result = await page.waitForFunction(
+      (e) => JSON.parse(localStorage['react-todos']).length === e,
+      expected
+    );
+    await log.success(`Verified todo count: ${expected}`);
+    return result;
+  }
+);
 ```
 
-**Key Points**:
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
 
-- Log based on environment
-- Skip logging with conditionals
-- Use appropriate log levels
-- Debug info for local, minimal for CI
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [async ({}, use, testInfo) => {
+    captureTestContext(testInfo);
+    await use(undefined);
+  }, { auto: true }],
+});
+```
 
-### Example 5: Integration with Auth and API
+### Example 6: Integration with Auth and API
 
 **Context**: Log authenticated API requests with tokens (safely).
 
@@ -221,16 +299,73 @@ test('should log auth flow', async ({ authToken, apiRequest }) => {
 - Combine with auth and API utilities
 - Log at appropriate detail level
 
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
 ## Log Levels Guide
 
-| Level     | When to Use                         | Shows in Report      | Shows in Console |
-| --------- | ----------------------------------- | -------------------- | ---------------- |
-| `step`    | Test organization, major actions    | ✅ Collapsible steps | ✅ Yes           |
-| `info`    | General information, state changes  | ✅ Yes               | ✅ Yes           |
-| `success` | Successful operations               | ✅ Yes               | ✅ Yes           |
-| `warning` | Non-critical issues, skipped checks | ✅ Yes               | ✅ Yes           |
-| `error`   | Failures, exceptions                | ✅ Yes               | ✅ Configurable  |
-| `debug`   | Detailed data, objects              | ✅ Yes (attached)    | ✅ Configurable  |
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
 
 ## Comparison with console.log
 
@@ -251,34 +386,34 @@ test('should log auth flow', async ({ authToken, apiRequest }) => {
 
 ## Anti-Patterns
 
-**❌ Logging objects in steps:**
+**DON'T log objects in steps:**
 
 ```typescript
 await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
 ```
 
-**✅ Use strings for steps, objects for debug:**
+**DO use strings for steps, objects for debug:**
 
 ```typescript
 await log.step('Creating user: test'); // Readable in UI
 await log.debug({ user: 'test', action: 'create' }); // Detailed data
 ```
 
-**❌ Logging sensitive data:**
+**DON'T log sensitive data:**
 
 ```typescript
 await log.info(`Password: ${password}`); // Security risk!
 await log.info(`Token: ${authToken}`); // Full token exposed!
 ```
 
-**✅ Use previews or omit sensitive data:**
+**DO use previews or omit sensitive data:**
 
 ```typescript
 await log.info('User authenticated successfully'); // No sensitive data
 await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
 ```
 
-**❌ Excessive logging in loops:**
+**DON'T log excessively in loops:**
 
 ```typescript
 for (const item of items) {
@@ -286,7 +421,7 @@ for (const item of items) {
 }
 ```
 
-**✅ Log summary or use debug level:**
+**DO log summary or use debug level:**
 
 ```typescript
 await log.step(`Processing ${items.length} items`);