@delorenj/pjangler 1.2.25 → 1.3.0

package/templates/commonproject/_bmad/bmm/testarch/knowledge/data-factories.md

@@ -1,500 +0,0 @@
-# Data Factories and API-First Setup
-
-## Principle
-
-Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
-
-## Rationale
-
-Static fixtures (JSON files, hardcoded objects) create brittle tests that:
-
-- Fail when schemas evolve (missing new required fields)
-- Cause collisions in parallel execution (same user IDs)
-- Hide test intent (what matters for _this_ test?)
-
-Dynamic factories with overrides provide:
-
-- **Parallel safety**: UUIDs and timestamps prevent collisions
-- **Schema evolution**: Defaults adapt to schema changes automatically
-- **Explicit intent**: Overrides show what matters for each test
-- **Speed**: API setup is 10-50x faster than UI
-
-## Pattern Examples
-
-### Example 1: Factory Function with Overrides
-
-**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
-
-**Implementation**:
-
-```typescript
-// test-utils/factories/user-factory.ts
-import { faker } from '@faker-js/faker';
-
-type User = {
-  id: string;
-  email: string;
-  name: string;
-  role: 'user' | 'admin' | 'moderator';
-  createdAt: Date;
-  isActive: boolean;
-};
-
-export const createUser = (overrides: Partial<User> = {}): User => ({
-  id: faker.string.uuid(),
-  email: faker.internet.email(),
-  name: faker.person.fullName(),
-  role: 'user',
-  createdAt: new Date(),
-  isActive: true,
-  ...overrides,
-});
-
-// test-utils/factories/product-factory.ts
-type Product = {
-  id: string;
-  name: string;
-  price: number;
-  stock: number;
-  category: string;
-};
-
-export const createProduct = (overrides: Partial<Product> = {}): Product => ({
-  id: faker.string.uuid(),
-  name: faker.commerce.productName(),
-  price: parseFloat(faker.commerce.price()),
-  stock: faker.number.int({ min: 0, max: 100 }),
-  category: faker.commerce.department(),
-  ...overrides,
-});
-
-// Usage in tests:
-test('admin can delete users', async ({ page, apiRequest }) => {
-  // Default user
-  const user = createUser();
-
-  // Admin user (explicit override shows intent)
-  const admin = createUser({ role: 'admin' });
-
-  // Seed via API (fast!)
-  await apiRequest({ method: 'POST', url: '/api/users', data: user });
-  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
-
-  // Now test UI behavior
-  await page.goto('/admin/users');
-  await page.click(`[data-testid="delete-user-${user.id}"]`);
-  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
-});
-```
-
-**Key Points**:
-
-- `Partial<User>` allows overriding any field without breaking type safety
-- Faker generates unique values—no collisions in parallel tests
-- Override shows test intent: `createUser({ role: 'admin' })` is explicit
-- Factory lives in `test-utils/factories/` for easy reuse
-
-### Example 2: Nested Factory Pattern
-
-**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
-
-**Implementation**:
-
-```typescript
-// test-utils/factories/order-factory.ts
-import { createUser } from './user-factory';
-import { createProduct } from './product-factory';
-
-type OrderItem = {
-  product: Product;
-  quantity: number;
-  price: number;
-};
-
-type Order = {
-  id: string;
-  user: User;
-  items: OrderItem[];
-  total: number;
-  status: 'pending' | 'paid' | 'shipped' | 'delivered';
-  createdAt: Date;
-};
-
-export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
-  const product = overrides.product || createProduct();
-  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
-
-  return {
-    product,
-    quantity,
-    price: product.price * quantity,
-    ...overrides,
-  };
-};
-
-export const createOrder = (overrides: Partial<Order> = {}): Order => {
-  const items = overrides.items || [createOrderItem(), createOrderItem()];
-  const total = items.reduce((sum, item) => sum + item.price, 0);
-
-  return {
-    id: faker.string.uuid(),
-    user: overrides.user || createUser(),
-    items,
-    total,
-    status: 'pending',
-    createdAt: new Date(),
-    ...overrides,
-  };
-};
-
-// Usage in tests:
-test('user can view order details', async ({ page, apiRequest }) => {
-  const user = createUser({ email: 'test@example.com' });
-  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
-  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
-
-  // Explicit relationships
-  const order = createOrder({
-    user,
-    items: [
-      createOrderItem({ product: product1, quantity: 2 }), // $20
-      createOrderItem({ product: product2, quantity: 1 }), // $15
-    ],
-  });
-
-  // Seed via API
-  await apiRequest({ method: 'POST', url: '/api/users', data: user });
-  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
-  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
-  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
-
-  // Test UI
-  await page.goto(`/orders/${order.id}`);
-  await expect(page.getByText('Widget A x 2')).toBeVisible();
-  await expect(page.getByText('Widget B x 1')).toBeVisible();
-  await expect(page.getByText('Total: $35.00')).toBeVisible();
-});
-```
-
-**Key Points**:
-
-- Nested factories handle relationships (order → user, order → products)
-- Overrides cascade: provide custom user/products or use defaults
-- Calculated fields (total) derived automatically from nested data
-- Explicit relationships make test data clear and maintainable
-
-### Example 3: Factory with API Seeding
-
-**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
-
-**Implementation**:
-
-```typescript
-// playwright/support/helpers/seed-helpers.ts
-import { APIRequestContext } from '@playwright/test';
-import { User, createUser } from '../../test-utils/factories/user-factory';
-import { Product, createProduct } from '../../test-utils/factories/product-factory';
-
-export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
-  const user = createUser(overrides);
-
-  const response = await request.post('/api/users', {
-    data: user,
-  });
-
-  if (!response.ok()) {
-    throw new Error(`Failed to seed user: ${response.status()}`);
-  }
-
-  return user;
-}
-
-export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
-  const product = createProduct(overrides);
-
-  const response = await request.post('/api/products', {
-    data: product,
-  });
-
-  if (!response.ok()) {
-    throw new Error(`Failed to seed product: ${response.status()}`);
-  }
-
-  return product;
-}
-
-// Playwright globalSetup for shared data
-// playwright/support/global-setup.ts
-import { chromium, FullConfig } from '@playwright/test';
-import { seedUser } from './helpers/seed-helpers';
-
-async function globalSetup(config: FullConfig) {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  const context = page.context();
-
-  // Seed admin user for all tests
-  const admin = await seedUser(context.request, {
-    email: 'admin@example.com',
-    role: 'admin',
-  });
-
-  // Save auth state for reuse
-  await context.storageState({ path: 'playwright/.auth/admin.json' });
-
-  await browser.close();
-}
-
-export default globalSetup;
-
-// Cypress equivalent with cy.task
-// cypress/support/tasks.ts
-export const seedDatabase = async (entity: string, data: unknown) => {
-  // Direct database insert or API call
-  if (entity === 'users') {
-    await db.users.create(data);
-  }
-  return null;
-};
-
-// Usage in Cypress tests:
-beforeEach(() => {
-  const user = createUser({ email: 'test@example.com' });
-  cy.task('db:seed', { entity: 'users', data: user });
-});
-```
-
-**Key Points**:
-
-- API seeding is 10-50x faster than UI-based setup
-- `globalSetup` seeds shared data once (e.g., admin user)
-- Per-test seeding uses `seedUser()` helpers for isolation
-- Cypress `cy.task` allows direct database access for speed
-
-### Example 4: Anti-Pattern - Hardcoded Test Data
-
-**Problem**:
-
-```typescript
-// ❌ BAD: Hardcoded test data
-test('user can login', async ({ page }) => {
-  await page.goto('/login');
-  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
-  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
-  await page.click('[data-testid="submit"]');
-
-  // What if this user already exists? Test fails in parallel runs.
-  // What if schema adds required fields? Test breaks.
-});
-
-// ❌ BAD: Static JSON fixtures
-// fixtures/users.json
-{
-  "users": [
-    { "id": 1, "email": "user1@test.com", "name": "User 1" },
-    { "id": 2, "email": "user2@test.com", "name": "User 2" }
-  ]
-}
-
-test('admin can delete user', async ({ page }) => {
-  const users = require('../fixtures/users.json');
-  // Brittle: IDs collide in parallel, schema drift breaks tests
-});
-```
-
-**Why It Fails**:
-
-- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
-- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
-- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
-- **Slow setup**: UI-based data creation is 10-50x slower than API
-
-**Better Approach**: Use factories
-
-```typescript
-// ✅ GOOD: Factory-based data
-test('user can login', async ({ page, apiRequest }) => {
-  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
-
-  // Seed via API (fast, parallel-safe)
-  await apiRequest({ method: 'POST', url: '/api/users', data: user });
-
-  // Test UI
-  await page.goto('/login');
-  await page.fill('[data-testid="email"]', user.email);
-  await page.fill('[data-testid="password"]', user.password);
-  await page.click('[data-testid="submit"]');
-
-  await expect(page).toHaveURL('/dashboard');
-});
-
-// ✅ GOOD: Factories adapt to schema changes automatically
-// When `phoneNumber` becomes required, update factory once:
-export const createUser = (overrides: Partial<User> = {}): User => ({
-  id: faker.string.uuid(),
-  email: faker.internet.email(),
-  name: faker.person.fullName(),
-  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
-  role: 'user',
-  ...overrides,
-});
-```
-
-**Key Points**:
-
-- Factories generate unique, parallel-safe data
-- Schema evolution handled in one place (factory), not every test
-- Test intent explicit via overrides
-- API seeding is fast and reliable
-
-### Example 5: Factory Composition
-
-**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
-
-**Implementation**:
-
-```typescript
-// test-utils/factories/user-factory.ts (base)
-export const createUser = (overrides: Partial<User> = {}): User => ({
-  id: faker.string.uuid(),
-  email: faker.internet.email(),
-  name: faker.person.fullName(),
-  role: 'user',
-  createdAt: new Date(),
-  isActive: true,
-  ...overrides,
-});
-
-// Compose specialized factories
-export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
-
-export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
-
-export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
-
-// Account-level factories with feature flags
-type Account = {
-  id: string;
-  owner: User;
-  plan: 'free' | 'pro' | 'enterprise';
-  features: string[];
-  maxUsers: number;
-};
-
-export const createAccount = (overrides: Partial<Account> = {}): Account => ({
-  id: faker.string.uuid(),
-  owner: overrides.owner || createUser(),
-  plan: 'free',
-  features: [],
-  maxUsers: 1,
-  ...overrides,
-});
-
-export const createProAccount = (overrides: Partial<Account> = {}): Account =>
-  createAccount({
-    plan: 'pro',
-    features: ['advanced-analytics', 'priority-support'],
-    maxUsers: 10,
-    ...overrides,
-  });
-
-export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
-  createAccount({
-    plan: 'enterprise',
-    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
-    maxUsers: 100,
-    ...overrides,
-  });
-
-// Usage in tests:
-test('pro accounts can access analytics', async ({ page, apiRequest }) => {
-  const admin = createAdminUser({ email: 'admin@company.com' });
-  const account = createProAccount({ owner: admin });
-
-  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
-  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
-
-  await page.goto('/analytics');
-  await expect(page.getByText('Advanced Analytics')).toBeVisible();
-});
-
-test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
-  const user = createUser({ email: 'user@company.com' });
-  const account = createAccount({ owner: user }); // Defaults to free plan
-
-  await apiRequest({ method: 'POST', url: '/api/users', data: user });
-  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
-
-  await page.goto('/analytics');
-  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
-});
-```
-
-**Key Points**:
-
-- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
-- Defaults cascade: `createProAccount` sets plan + features automatically
-- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
-- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
-
-## Integration Points
-
-- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
-- **Related fragments**:
-  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
-  - `network-first.md` - API-first setup patterns
-  - `test-quality.md` - Parallel-safe, deterministic test design
-
-## Cleanup Strategy
-
-Ensure factories work with cleanup patterns:
-
-```typescript
-// Track created IDs for cleanup
-const createdUsers: string[] = [];
-
-afterEach(async ({ apiRequest }) => {
-  // Clean up all users created during test
-  for (const userId of createdUsers) {
-    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
-  }
-  createdUsers.length = 0;
-});
-
-test('user registration flow', async ({ page, apiRequest }) => {
-  const user = createUser();
-  createdUsers.push(user.id);
-
-  await apiRequest({ method: 'POST', url: '/api/users', data: user });
-  // ... test logic
-});
-```
-
-## Feature Flag Integration
-
-When working with feature flags, layer them into factories:
-
-```typescript
-export const createUserWithFlags = (
-  overrides: Partial<User> = {},
-  flags: Record<string, boolean> = {},
-): User & { flags: Record<string, boolean> } => ({
-  ...createUser(overrides),
-  flags: {
-    'new-dashboard': false,
-    'beta-features': false,
-    ...flags,
-  },
-});
-
-// Usage:
-const user = createUserWithFlags(
-  { email: 'test@example.com' },
-  {
-    'new-dashboard': true,
-    'beta-features': true,
-  },
-);
-```
-
-_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._