siesa-agents 2.1.40 → 2.1.41

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

@@ -1,382 +1,382 @@
-# 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);
-```
+# 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);
+```