bmalph 1.0.0 → 2.2.1

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);
-```