bmad-studio 0.1.0 → 0.2.0

package/_bmad/tea/testarch/knowledge/overview.md

@@ -1,286 +0,0 @@
-# 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. **Works equally well for pure API testing (no browser) and UI testing.**
-
-## 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**: Used in enterprise production environments
-- **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
-- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
-
-## 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)
-- `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, retry, and operation-based overload | **API/Backend**    |
-| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
-| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
-| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
-| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
-| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
-| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
-| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
-| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
-
-**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
-
-## 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/_bmad/tea/testarch/knowledge/pact-consumer-di.md

@@ -1,310 +0,0 @@
-# Pact Consumer DI Pattern
-
-## Principle
-
-Inject the Pact mock server URL into consumer code via an optional `baseUrl` field on the API context type instead of using raw `fetch()` inside `executeTest()`. This ensures contract tests exercise the real consumer HTTP client — including retry logic, header assembly, timeout configuration, error handling, and metrics — rather than testing Pact itself.
-
-The base URL is typically a module-level constant evaluated at import time (`export const API_BASE_URL = env.API_BASE_URL`), but `mockServer.url` is only available at runtime inside `executeTest()`. Dependency injection solves this timing mismatch cleanly: add one optional field to the context type, use nullish coalescing in the HTTP client factory, and inject the mock server URL in tests.
-
-## Rationale
-
-### The Problem
-
-Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
-
-### Why NOT vi.mock
-
-`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
-
-### Comparison
-
-| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
-| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
-| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
-| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
-| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
-
-## Pattern Examples
-
-### Example 1: Production Code Change (2 Lines Total)
-
-**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
-
-**Implementation**:
-
-```typescript
-// src/types.ts
-export type ApiContext = {
-  jwtToken: string;
-  customerId: number;
-  adminUserId?: number;
-  correlationId?: string;
-  baseUrl?: string; // Override for testing (Pact mock server)
-};
-```
-
-```typescript
-// src/http-client.ts
-import axios from 'axios';
-import type { AxiosInstance } from 'axios';
-import type { ApiContext } from './types.js';
-import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
-
-function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
-  return axios.create({
-    baseURL: context.baseUrl ?? API_BASE_URL,
-    timeout: REQUEST_TIMEOUT,
-    headers: {
-      'Content-Type': 'application/json',
-      Accept: 'application/json',
-      Authorization: `Bearer ${context.jwtToken}`,
-      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
-    },
-  });
-}
-```
-
-**Key Points**:
-
-- `baseUrl` is optional — existing production code never sets it
-- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
-- Zero production behavior change — only test code provides the override
-- Two lines added total: one type field, one `??` fallback
-
-### Example 2: Shared Test Context Helper
-
-**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
-
-**Implementation**:
-
-```typescript
-// pact/support/test-context.ts
-import type { ApiContext } from '../../src/types.js';
-
-export function createTestContext(mockServerUrl: string): ApiContext {
-  return {
-    jwtToken: 'test-jwt-token',
-    customerId: 1,
-    baseUrl: `${mockServerUrl}/api/v2`,
-  };
-}
-```
-
-**Key Points**:
-
-- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
-- Single helper shared across all consumer test files — no repetition
-- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
-- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
-
-### Example 3: Before/After for a Simple Test
-
-**Context**: Migrating an existing raw-fetch test to call real consumer code.
-
-**Before** (raw fetch — tests Pact mock, not consumer code):
-
-```typescript
-.executeTest(async (mockServer: V3MockServer) => {
-  const response = await fetch(
-    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
-    {
-      headers: {
-        Authorization: "Bearer test-jwt-token",
-        "Content-Type": "application/json",
-      },
-    },
-  );
-  expect(response.status).toBe(200);
-  const body = (await response.json()) as Record<string, unknown>[];
-  expect(body).toEqual(expect.arrayContaining([...]));
-});
-```
-
-**After** (real consumer code):
-
-```typescript
-.executeTest(async (mockServer: V3MockServer) => {
-  const api = createApiClient(createTestContext(mockServer.url));
-  const result = await api.getFilterFields();
-  expect(result).toEqual(
-    expect.arrayContaining([
-      expect.objectContaining({
-        id: expect.any(String),
-        readable: expect.any(String),
-        filterType: expect.any(String),
-      }),
-    ]),
-  );
-});
-```
-
-**Key Points**:
-
-- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
-- Assertions validate the return value shape, not transport details
-- The real client's headers, timeout, and retry logic are exercised transparently
-- Less code, more coverage — the test is shorter and tests more
-
-### Example 4: Contract Accuracy Fix
-
-**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
-
-The real `getCustomerActivityCount(transactionId, dateRange)` sends:
-
-```json
-{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
-```
-
-The old test with raw fetch sent:
-
-```json
-{ "transactionId": "txn-123", "filters": {} }
-```
-
-This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
-
-**Implementation** — fix the contract to match reality:
-
-```typescript
-// WRONG — old contract with empty filters
-.withRequest({
-  method: "POST",
-  path: "/api/v2/customers/activity/count",
-  body: { transactionId: "txn-123", filters: {} },
-})
-
-// CORRECT — matches what real code actually sends
-.withRequest({
-  method: "POST",
-  path: "/api/v2/customers/activity/count",
-  body: {
-    transactionId: "txn-123",
-    filters: { dateRange: "last_30_days" },
-  },
-})
-```
-
-**Key Points**:
-
-- Contracts become discoverable truth, not hand-maintained guesses
-- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
-- The 500 Request-Mismatch from Pact was immediate and clear
-- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
-
-### Example 5: Parallel-Endpoint Methods
-
-**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
-
-**Implementation**:
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import type { V3MockServer } from '@pact-foundation/pact';
-import { makeApiRequestWithContext } from '../../src/http-client.js';
-import type { CountStatistics } from '../../src/types.js';
-import { createTestContext } from '../support/test-context.js';
-
-describe('Transaction Statistics - Count Endpoint', () => {
-  // ... provider setup ...
-
-  it('should return count statistics', async () => {
-    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
-
-    await provider
-      .given('transaction statistics exist')
-      .uponReceiving('a request for transaction count statistics')
-      .withRequest({
-        method: 'POST',
-        path: '/api/v2/transactions/statistics/count',
-        body: statsRequest,
-      })
-      .willRespondWith({
-        status: 200,
-        body: { count: 42, period: 'daily' },
-      })
-      .executeTest(async (mockServer: V3MockServer) => {
-        const context = createTestContext(mockServer.url);
-        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
-        expect(result.count).toBeDefined();
-      });
-  });
-});
-```
-
-**Key Points**:
-
-- Each Pact interaction verifies one endpoint contract
-- The `Promise.all` orchestration is internal logic, not a contract concern
-- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
-- Separate `it` blocks keep contracts independent and debuggable
-
-## Anti-Patterns
-
-### Wrong: Raw fetch — tests Pact mock, not consumer code
-
-```typescript
-// BAD: Raw fetch duplicates headers and URL assembly
-const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
-  method: 'GET',
-  headers: {
-    Authorization: 'Bearer test-jwt-token',
-    'Content-Type': 'application/json',
-  },
-});
-expect(response.status).toBe(200);
-```
-
-### Wrong: vi.mock with getter — fragile ESM hoisting
-
-```typescript
-// BAD: ESM hoisting makes this non-obvious and brittle
-vi.mock('../../src/constants.js', async (importOriginal) => ({
-  ...(await importOriginal()),
-  get API_BASE_URL() {
-    return mockBaseUrl;
-  },
-}));
-```
-
-### Wrong: Asserting HTTP status instead of return value
-
-```typescript
-// BAD: Status 200 tells you nothing about the consumer's parsing logic
-expect(response.status).toBe(200);
-```
-
-### Right: Call real consumer code, assert return values
-
-```typescript
-// GOOD: Exercises real client, validates parsed return value
-const api = createApiClient(createTestContext(mockServer.url));
-const result = await api.searchTransactions(request);
-expect(result.transactions).toBeDefined();
-```
-
-## Rules
-
-1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
-2. Zero production behavior change — existing code never sets `baseUrl`
-3. Assertions validate return values from consumer methods, not HTTP status codes
-4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
-5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
-6. Create a single shared test context helper — no repetition across test files
-7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
-
-## Integration Points
-
-- `contract-testing.md` — Foundational Pact.js patterns and provider verification
-- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
-- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
-- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
-- `api-testing-foundations.md` — API testing best practices
-
-Used in workflows:
-
-- `automate` — Consumer contract test generation
-- `test-review` — Contract test quality checks
-
-## Source
-
-Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.