siesa-agents 2.1.78 → 2.1.80

package/bmad/bmm/testarch/knowledge/fixtures-composition.md

@@ -1,382 +0,0 @@
-# Fixtures Composition with mergeTests
-
-## Principle
-
-Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
-
-## Rationale
-
-Using fixtures from multiple sources requires combining them:
-
-- Importing from multiple fixture files is verbose
-- Name conflicts between fixtures
-- Duplicate fixture definitions
-- No clear single test object
-
-Playwright's `mergeTests` provides:
-
-- **Single test object**: All fixtures in one import
-- **Conflict resolution**: Handles name collisions automatically
-- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
-- **Type safety**: Full TypeScript support for merged fixtures
-- **Maintainability**: One place to manage all fixtures
-
-## Pattern Examples
-
-### Example 1: Basic Fixture Merging
-
-**Context**: Combine multiple playwright-utils fixtures into single test object.
-
-**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';
-
-// Merge all fixtures
-export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
-
-export { expect } from '@playwright/test';
-```
-
-```typescript
-// In your tests - import from merged fixtures
-import { test, expect } from '../support/merged-fixtures';
-
-test('all utilities available', async ({
-  apiRequest, // From api-request fixture
-  authToken, // From auth fixture
-  recurse, // From recurse fixture
-}) => {
-  // All fixtures available in single test signature
-  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**:
-
-- Create one `merged-fixtures.ts` per project
-- Import test object from merged fixtures in all test files
-- All utilities available without multiple imports
-- Type-safe access to all fixtures
-
-### Example 2: Combining with Custom Fixtures
-
-**Context**: Add project-specific fixtures alongside playwright-utils.
-
-**Implementation**:
-
-```typescript
-// playwright/support/custom-fixtures.ts - Your project fixtures
-import { test as base } from '@playwright/test';
-import { createUser } from './factories/user-factory';
-import { seedDatabase } from './helpers/db-seeder';
-
-export const test = base.extend({
-  // Custom fixture 1: Auto-seeded user
-  testUser: async ({ request }, use) => {
-    const user = await createUser({ role: 'admin' });
-    await seedDatabase('users', [user]);
-    await use(user);
-    // Cleanup happens automatically
-  },
-
-  // Custom fixture 2: Database helpers
-  db: async ({}, use) => {
-    await use({
-      seed: seedDatabase,
-      clear: () => seedDatabase.truncate(),
-    });
-  },
-});
-
-// playwright/support/merged-fixtures.ts - Combine everything
-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 customFixtures } from './custom-fixtures';
-
-export const test = mergeTests(
-  apiRequestFixture,
-  authFixture,
-  customFixtures, // Your project fixtures
-);
-
-export { expect } from '@playwright/test';
-```
-
-```typescript
-// In tests - all fixtures available
-import { test, expect } from '../support/merged-fixtures';
-
-test('using mixed fixtures', async ({
-  apiRequest, // playwright-utils
-  authToken, // playwright-utils
-  testUser, // custom
-  db, // custom
-}) => {
-  // Use playwright-utils
-  const { body } = await apiRequest({
-    method: 'GET',
-    path: `/api/users/${testUser.id}`,
-    headers: { Authorization: `Bearer ${authToken}` },
-  });
-
-  // Use custom fixture
-  await db.clear();
-});
-```
-
-**Key Points**:
-
-- Custom fixtures extend `base` test
-- Merge custom with playwright-utils fixtures
-- All available in one test signature
-- Maintainable separation of concerns
-
-### Example 3: Full Utility Suite Integration
-
-**Context**: Production setup with all core playwright-utils and custom fixtures.
-
-**Implementation**:
-
-```typescript
-// playwright/support/merged-fixtures.ts
-import { mergeTests } from '@playwright/test';
-
-// Playwright utils fixtures
-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 interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
-import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
-import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
-
-// Custom project fixtures
-import { test as customFixtures } from './custom-fixtures';
-
-// Merge everything
-export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
-
-export { expect } from '@playwright/test';
-```
-
-```typescript
-// In tests
-import { test, expect } from '../support/merged-fixtures';
-
-test('full integration', async ({
-  page,
-  context,
-  apiRequest,
-  authToken,
-  interceptNetworkCall,
-  recurse,
-  networkRecorder,
-  testUser, // custom
-}) => {
-  // All utilities + custom fixtures available
-  await networkRecorder.setup(context);
-
-  const usersCall = interceptNetworkCall({ url: '**/api/users' });
-
-  await page.goto('/users');
-  const { responseJson } = await usersCall;
-
-  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
-});
-```
-
-**Key Points**:
-
-- One merged-fixtures.ts for entire project
-- Combine all playwright-utils you use
-- Add custom project fixtures
-- Single import in all test files
-
-### Example 4: Fixture Override Pattern
-
-**Context**: Override default options for specific test files or describes.
-
-**Implementation**:
-
-```typescript
-import { test, expect } from '../support/merged-fixtures';
-
-// Override auth options for entire file
-test.use({
-  authOptions: {
-    userIdentifier: 'admin',
-    environment: 'staging',
-  },
-});
-
-test('uses admin on staging', async ({ authToken }) => {
-  // Token is for admin user on staging environment
-});
-
-// Override for specific describe block
-test.describe('manager tests', () => {
-  test.use({
-    authOptions: {
-      userIdentifier: 'manager',
-    },
-  });
-
-  test('manager can access reports', async ({ page }) => {
-    // Uses manager token
-    await page.goto('/reports');
-  });
-});
-```
-
-**Key Points**:
-
-- `test.use()` overrides fixture options
-- Can override at file or describe level
-- Options merge with defaults
-- Type-safe overrides
-
-### Example 5: Avoiding Fixture Conflicts
-
-**Context**: Handle name collisions when merging fixtures with same names.
-
-**Implementation**:
-
-```typescript
-// If two fixtures have same name, last one wins
-import { test as fixture1 } from './fixture1'; // has 'user' fixture
-import { test as fixture2 } from './fixture2'; // also has 'user' fixture
-
-const test = mergeTests(fixture1, fixture2);
-// fixture2's 'user' overrides fixture1's 'user'
-
-// Better: Rename fixtures before merging
-import { test as base } from '@playwright/test';
-import { test as fixture1 } from './fixture1';
-
-const fixture1Renamed = base.extend({
-  user1: fixture1._extend.user, // Rename to avoid conflict
-});
-
-const test = mergeTests(fixture1Renamed, fixture2);
-// Now both 'user1' and 'user' available
-
-// Best: Design fixtures without conflicts
-// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
-// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
-```
-
-**Key Points**:
-
-- Last fixture wins in conflicts
-- Rename fixtures to avoid collisions
-- Design fixtures with unique names
-- Playwright-utils uses descriptive names (no conflicts)
-
-## Recommended Project Structure
-
-```
-playwright/
-├── support/
-│   ├── merged-fixtures.ts        # ⭐ Single test object for project
-│   ├── custom-fixtures.ts        # Your project-specific fixtures
-│   ├── auth/
-│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
-│   │   └── custom-auth-provider.ts
-│   ├── fixtures/
-│   │   ├── user-fixture.ts
-│   │   ├── db-fixture.ts
-│   │   └── api-fixture.ts
-│   └── utils/
-│       └── factories/
-└── tests/
-    ├── api/
-    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
-    ├── e2e/
-    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
-    └── component/
-        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
-```
-
-## Benefits of Fixture Composition
-
-**Compared to direct imports:**
-
-```typescript
-// ❌ Without mergeTests (verbose)
-import { test as base } from '@playwright/test';
-import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
-import { getAuthToken } from './auth';
-import { createUser } from './factories';
-
-test('verbose', async ({ request }) => {
-  const token = await getAuthToken();
-  const user = await createUser();
-  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
-  // Manual wiring everywhere
-});
-
-// ✅ With mergeTests (clean)
-import { test } from '../support/merged-fixtures';
-
-test('clean', async ({ apiRequest, authToken, testUser }) => {
-  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
-  // All fixtures auto-wired
-});
-```
-
-**Reduction:** ~10 lines per test → ~2 lines
-
-## Related Fragments
-
-- `overview.md` - Installation and design principles
-- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
-- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
-
-## Anti-Patterns
-
-**❌ Importing test from multiple fixture files:**
-
-```typescript
-import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
-// Also need auth...
-import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
-// Name conflict! Which test to use?
-```
-
-**✅ Use merged fixtures:**
-
-```typescript
-import { test } from '../support/merged-fixtures';
-// All utilities available, no conflicts
-```
-
-**❌ Merging too many fixtures (kitchen sink):**
-
-```typescript
-// Merging 20+ fixtures makes test signature huge
-const test = mergeTests(...20 different fixtures)
-
-test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
-  // Cognitive overload
-})
-```
-
-**✅ Merge only what you actually use:**
-
-```typescript
-// Merge the 4-6 fixtures your project actually needs
-const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
-```

package/bmad/bmm/testarch/knowledge/intercept-network-call.md

@@ -1,280 +0,0 @@
-# Intercept Network Call Utility
-
-## Principle
-
-Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
-
-## Rationale
-
-Vanilla Playwright's network interception requires multiple steps:
-
-- `page.route()` to setup, `page.waitForResponse()` to capture
-- Manual JSON parsing
-- Verbose syntax for conditional handling
-- Complex filter predicates
-
-The `interceptNetworkCall` utility provides:
-
-- **Single declarative call**: Setup and wait in one statement
-- **Automatic JSON parsing**: Response pre-parsed, strongly typed
-- **Flexible URL patterns**: Glob matching with picomatch
-- **Spy or stub modes**: Observe real traffic or mock responses
-- **Concise API**: Reduces boilerplate by 60-70%
-
-## Pattern Examples
-
-### Example 1: Spy on Network (Observe Real Traffic)
-
-**Context**: Capture and inspect real API responses for validation.
-
-**Implementation**:
-
-```typescript
-import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
-
-test('should spy on users API', async ({ page, interceptNetworkCall }) => {
-  // Setup interception BEFORE navigation
-  const usersCall = interceptNetworkCall({
-    url: '**/api/users', // Glob pattern
-  });
-
-  await page.goto('/dashboard');
-
-  // Wait for response and access parsed data
-  const { responseJson, status } = await usersCall;
-
-  expect(status).toBe(200);
-  expect(responseJson).toHaveLength(10);
-  expect(responseJson[0]).toHaveProperty('name');
-});
-```
-
-**Key Points**:
-
-- Intercept before navigation (critical for race-free tests)
-- Returns Promise with `{ responseJson, status, requestBody }`
-- Glob patterns (`**` matches any path segment)
-- JSON automatically parsed
-
-### Example 2: Stub Network (Mock Response)
-
-**Context**: Mock API responses for testing UI behavior without backend.
-
-**Implementation**:
-
-```typescript
-test('should stub users API', async ({ page, interceptNetworkCall }) => {
-  const mockUsers = [
-    { id: 1, name: 'Test User 1' },
-    { id: 2, name: 'Test User 2' },
-  ];
-
-  const usersCall = interceptNetworkCall({
-    url: '**/api/users',
-    fulfillResponse: {
-      status: 200,
-      body: mockUsers,
-    },
-  });
-
-  await page.goto('/dashboard');
-  await usersCall;
-
-  // UI shows mocked data
-  await expect(page.getByText('Test User 1')).toBeVisible();
-  await expect(page.getByText('Test User 2')).toBeVisible();
-});
-```
-
-**Key Points**:
-
-- `fulfillResponse` mocks the API
-- No backend needed
-- Test UI logic in isolation
-- Status code and body fully controllable
-
-### Example 3: Conditional Response Handling
-
-**Context**: Different responses based on request method or parameters.
-
-**Implementation**:
-
-```typescript
-test('conditional mocking', async ({ page, interceptNetworkCall }) => {
-  await interceptNetworkCall({
-    url: '**/api/data',
-    handler: async (route, request) => {
-      if (request.method() === 'POST') {
-        // Mock POST success
-        await route.fulfill({
-          status: 201,
-          body: JSON.stringify({ id: 'new-id', success: true }),
-        });
-      } else if (request.method() === 'GET') {
-        // Mock GET with data
-        await route.fulfill({
-          status: 200,
-          body: JSON.stringify([{ id: 1, name: 'Item' }]),
-        });
-      } else {
-        // Let other methods through
-        await route.continue();
-      }
-    },
-  });
-
-  await page.goto('/data-page');
-});
-```
-
-**Key Points**:
-
-- `handler` function for complex logic
-- Access full `route` and `request` objects
-- Can mock, continue, or abort
-- Flexible for advanced scenarios
-
-### Example 4: Error Simulation
-
-**Context**: Testing error handling in UI when API fails.
-
-**Implementation**:
-
-```typescript
-test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
-  // Simulate 500 error
-  const errorCall = interceptNetworkCall({
-    url: '**/api/users',
-    fulfillResponse: {
-      status: 500,
-      body: { error: 'Internal Server Error' },
-    },
-  });
-
-  await page.goto('/dashboard');
-  await errorCall;
-
-  // Verify UI shows error state
-  await expect(page.getByText('Failed to load users')).toBeVisible();
-  await expect(page.getByTestId('retry-button')).toBeVisible();
-});
-
-// Simulate network timeout
-test('should handle timeout', async ({ page, interceptNetworkCall }) => {
-  await interceptNetworkCall({
-    url: '**/api/slow',
-    handler: async (route) => {
-      // Never respond - simulates timeout
-      await new Promise(() => {});
-    },
-  });
-
-  await page.goto('/slow-page');
-
-  // UI should show timeout error
-  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
-});
-```
-
-**Key Points**:
-
-- Mock error statuses (4xx, 5xx)
-- Test timeout scenarios
-- Validate error UI states
-- No real failures needed
-
-### Example 5: Multiple Intercepts (Order Matters!)
-
-**Context**: Intercepting different endpoints in same test - setup order is critical.
-
-**Implementation**:
-
-```typescript
-test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
-  // ✅ CORRECT: Setup all intercepts BEFORE navigation
-  const usersCall = interceptNetworkCall({ url: '**/api/users' });
-  const productsCall = interceptNetworkCall({ url: '**/api/products' });
-  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
-
-  // THEN navigate
-  await page.goto('/dashboard');
-
-  // Wait for all (or specific ones)
-  const [users, products] = await Promise.all([usersCall, productsCall]);
-
-  expect(users.responseJson).toHaveLength(10);
-  expect(products.responseJson).toHaveLength(50);
-});
-```
-
-**Key Points**:
-
-- Setup all intercepts before triggering actions
-- Use `Promise.all()` to wait for multiple calls
-- Order: intercept → navigate → await
-- Prevents race conditions
-
-## URL Pattern Matching
-
-**Supported glob patterns:**
-
-```typescript
-'**/api/users'; // Any path ending with /api/users
-'/api/users'; // Exact match
-'**/users/*'; // Any users sub-path
-'**/api/{users,products}'; // Either users or products
-'**/api/users?id=*'; // With query params
-```
-
-**Uses picomatch library** - same pattern syntax as Playwright's `page.route()` but cleaner API.
-
-## Comparison with Vanilla Playwright
-
-| Vanilla Playwright                                          | intercept-network-call                                       |
-| ----------------------------------------------------------- | ------------------------------------------------------------ |
-| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
-| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
-| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
-| `const status = resp.status()`                              | `const { status } = await call`                              |
-| Complex filter predicates                                   | Simple glob patterns                                         |
-
-**Reduction:** ~5-7 lines → ~2-3 lines per interception
-
-## Related Fragments
-
-- `network-first.md` - Core pattern: intercept before navigate
-- `network-recorder.md` - HAR-based offline testing
-- `overview.md` - Fixture composition basics
-
-## Anti-Patterns
-
-**❌ Intercepting after navigation:**
-
-```typescript
-await page.goto('/dashboard'); // Navigation starts
-const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
-```
-
-**✅ Intercept before navigate:**
-
-```typescript
-const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
-await page.goto('/dashboard'); // Then navigate
-const { responseJson } = await usersCall; // Then await
-```
-
-**❌ Ignoring the returned Promise:**
-
-```typescript
-interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
-await page.goto('/dashboard');
-// No deterministic wait - race condition
-```
-
-**✅ Always await the intercept:**
-
-```typescript
-const usersCall = interceptNetworkCall({ url: '**/api/users' });
-await page.goto('/dashboard');
-await usersCall; // Deterministic wait
-```