gaia-framework 1.58.0 → 1.58.2

package/_gaia/testing/knowledge/core/deterministic-testing.md

@@ -0,0 +1,167 @@
+---
+name: deterministic-testing
+tier: core
+version: '1.0'
+---
+
+# Deterministic Testing
+
+## Principle
+
+A flaky test is worse than no test -- it erodes trust in the entire suite. Every test
+must produce the same result regardless of time, environment, execution order, or
+network state. Control time, intercept networks, disable animations, seed randomness,
+and fix root causes instead of adding retries.
+
+## Rationale
+
+Flaky tests train developers to ignore failures. Once the team starts dismissing red
+builds as "probably just flaky," real bugs slip through. Deterministic tests require
+more upfront effort but pay for themselves by maintaining trust in the CI pipeline --
+the single most important quality signal a team has.
+
+## Pattern Examples
+
+### Time Control
+
+```typescript
+// BAD: Test depends on system clock
+test('shows expiry warning', () => {
+  const token = createToken({ expiresAt: new Date('2025-12-31') });
+  expect(isExpiringSoon(token)).toBe(true); // Fails after 2025-12-31
+});
+
+// GOOD: Mock the clock
+test('shows expiry warning', () => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date('2025-12-25'));
+
+  const token = createToken({ expiresAt: new Date('2025-12-31') });
+  expect(isExpiringSoon(token)).toBe(true); // Always passes
+
+  vi.useRealTimers();
+});
+
+// Playwright: control browser time
+test('countdown displays correctly', async ({ page }) => {
+  await page.clock.install({ time: new Date('2025-06-01T12:00:00') });
+  await page.goto('/countdown');
+  await expect(page.getByTestId('timer')).toHaveText('30 days remaining');
+});
+```
+
+### Network Determinism
+
+```typescript
+// BAD: Navigate then hope the API responds in time
+await page.goto('/dashboard');
+await expect(page.getByText('Welcome')).toBeVisible(); // Race condition
+
+// GOOD: Intercept BEFORE navigate, wait for response
+const responsePromise = page.waitForResponse('**/api/dashboard');
+await page.goto('/dashboard');
+await responsePromise; // Deterministic -- waits for actual response
+await expect(page.getByText('Welcome')).toBeVisible();
+
+// BETTER: Mock for full control
+await page.route('**/api/dashboard', (route) => {
+  route.fulfill({
+    status: 200,
+    body: JSON.stringify({ user: { name: 'Alice' }, notifications: 3 }),
+  });
+});
+await page.goto('/dashboard');
+await expect(page.getByText('Welcome, Alice')).toBeVisible();
+```
+
+### Animation and Transition Handling
+
+```typescript
+// Disable animations globally in Playwright config
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    // Disable CSS animations and transitions
+    contextOptions: {
+      reducedMotion: 'reduce',
+    },
+  },
+});
+
+// Or wait for animations to complete
+await page.getByTestId('modal').waitFor({ state: 'visible' });
+await page.waitForFunction(() => {
+  const el = document.querySelector('[data-testid="modal"]');
+  return getComputedStyle(el!).opacity === '1';
+});
+```
+
+### Seeded Random Data
+
+```typescript
+// BAD: Random data changes every run
+test('processes order', () => {
+  const order = { id: Math.random().toString(), total: Math.random() * 100 };
+  // Fails intermittently when random values hit edge cases
+});
+
+// GOOD: Seeded faker for reproducible randomness
+import { faker } from '@faker-js/faker';
+
+beforeEach(() => {
+  faker.seed(12345); // Same "random" data every run
+});
+
+test('processes order', () => {
+  const order = {
+    id: faker.string.uuid(),       // Always the same UUID
+    total: faker.number.float({ min: 1, max: 100, fractionDigits: 2 }),
+  };
+  expect(processOrder(order)).toEqual(expect.objectContaining({ status: 'pending' }));
+});
+```
+
+### Retry vs Fix
+
+```typescript
+// BAD: Retries mask the root cause
+test('load dashboard', async ({ page }) => {
+  // Setting retries: 3 in config because this test is "flaky"
+  await page.goto('/dashboard');
+  await expect(page.getByText('Welcome')).toBeVisible();
+  // Root cause: race condition with API call. Fix the race, not the retry.
+});
+
+// GOOD: Fix the root cause
+test('load dashboard', async ({ page }) => {
+  const dataPromise = page.waitForResponse('**/api/dashboard');
+  await page.goto('/dashboard');
+  await dataPromise; // Wait for data, not a timeout
+  await expect(page.getByText('Welcome')).toBeVisible();
+});
+```
+
+## Anti-Patterns
+
+1. **Hard waits** -- `page.waitForTimeout(3000)` or `cy.wait(3000)` are never
+   deterministic. Use network waits, element state waits, or response promises.
+
+2. **Retries as a fix** -- Adding `retries: 3` to a flaky test hides the bug. Retries
+   are for CI resilience on infrastructure glitches, not for masking test design problems.
+
+3. **Uncontrolled randomness** -- `Math.random()` or unseeded faker produces different
+   data every run. Seed generators or use fixed values for determinism.
+
+4. **System clock dependency** -- Tests that use `new Date()` or `Date.now()` without
+   mocking will behave differently tomorrow. Always mock time.
+
+5. **Ignoring animation timing** -- Clicking elements mid-animation causes intermittent
+   failures. Disable animations in test config or wait for animation completion.
+
+## Integration Points
+
+- **Workflows**: `test-review` (flakiness audit), `test-automation` (deterministic
+  patterns in generated tests)
+- **Related fragments**: `test-isolation` (preventing state leaks),
+  `fixture-architecture` (cleanup patterns), `selector-resilience` (stable selectors
+  prevent false failures)

package/_gaia/testing/knowledge/core/fixture-architecture.md

@@ -0,0 +1,131 @@
+---
+name: fixture-architecture
+tier: core
+version: '1.0'
+---
+
+# Fixture Architecture
+
+## Principle
+
+Build test helpers as pure functions first, then wrap in framework-specific fixtures.
+Compose capabilities via `mergeTests` (Playwright) or layered commands (Cypress), not
+inheritance. Each fixture solves one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains
+(`BasePage -> LoginPage -> AdminPage`). When base classes change, all descendants break.
+Pure functions with fixture wrappers provide testability (unit-testable without the
+framework), composability (mix capabilities freely), reusability (export via package
+subpaths), and maintainability (one concern per fixture).
+
+## Pattern Examples
+
+### Pure Function into Fixture Pattern
+
+Always start with a pure function that accepts dependencies explicitly, then wrap it.
+
+```typescript
+// Step 1: Pure function (unit-testable without Playwright)
+// helpers/api-request.ts
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+};
+
+export async function apiRequest({ request, method, url, data }: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!response.ok()) {
+    throw new Error(`API ${method} ${url} failed: ${response.status()}`);
+  }
+  return response.json();
+}
+
+// Step 2: Fixture wrapper injects framework dependency
+// fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    await use((params) => apiRequest({ request, ...params }));
+  },
+});
+```
+
+### Composable Fixtures with mergeTests
+
+Compose multiple focused fixtures instead of monolithic helpers.
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+
+// Compose all capabilities -- no inheritance needed
+export const test = mergeTests(base, apiFixture, networkFixture, authFixture);
+export { expect } from '@playwright/test';
+
+// Usage: import { test, expect } from './merged-fixtures';
+// test('example', async ({ page, apiRequest, auth, network }) => { ... });
+```
+
+### Fixture Cleanup Pattern
+
+Track resources created during a test and auto-cleanup in teardown.
+
+```typescript
+export const test = base.extend<{ seedUser: (data: Partial<User>) => Promise<User> }>({
+  seedUser: async ({}, use) => {
+    const createdIds: string[] = [];
+
+    const seedUser = async (data: Partial<User>) => {
+      const user = await seedDatabase('users', data);
+      createdIds.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: delete all created users after test
+    for (const id of createdIds) {
+      await deleteRecord('users', id);
+    }
+  },
+});
+```
+
+## Anti-Patterns
+
+1. **Inheritance-based Page Objects** -- `AdminPage extends LoginPage extends BasePage`
+   creates fragile chains. Changes to `BasePage` break all descendants. Use pure
+   functions and fixture composition instead.
+
+2. **Monolithic fixture files** -- A single fixture providing auth, API, network, and
+   database concerns violates single responsibility. Split into focused fixtures and
+   compose with `mergeTests`.
+
+3. **Framework-coupled helpers** -- Writing helpers that directly import `page` or `cy`
+   makes them untestable in isolation. Accept dependencies as parameters.
+
+4. **No cleanup in fixtures** -- Fixtures that create resources (DB records, files)
+   without tracking and deleting them cause test pollution and flakiness.
+
+5. **Premature abstraction** -- Creating fixtures for code used only once. Use the
+   3+ uses rule: 3+ uses = fixture, 2-3 uses = utility module, 1 use = keep inline.
+
+## Integration Points
+
+- **Workflows**: `test-framework` (initial scaffold), `test-automation` (test generation),
+  `test-review` (fixture quality check)
+- **Related fragments**: `data-factories` (factory functions for test data),
+  `test-isolation` (dependency injection patterns), `deterministic-testing` (cleanup
+  prevents state leaks)

package/_gaia/testing/knowledge/core/test-isolation.md

@@ -0,0 +1,142 @@
+---
+name: test-isolation
+tier: core
+version: '1.0'
+---
+
+# Test Isolation
+
+## Principle
+
+Tests must be deterministic and independent. A test that depends on another test's side
+effects is a time bomb. Isolate via test doubles, dependency injection, per-test data
+cleanup, and network mocking. Each test must be runnable alone, in any order, at any time.
+
+## Rationale
+
+Shared mutable state between tests causes cascading failures that are nearly impossible
+to debug. Test A creates a user, test B assumes it exists, test C deletes it -- now B
+and C fail when run without A. Proper isolation eliminates this class of bugs entirely
+and enables parallel execution, which dramatically reduces CI time.
+
+## Pattern Examples
+
+### Test Doubles -- When to Use Each
+
+```typescript
+// STUB: Returns canned data. Use when you need controlled input.
+const priceService = { getPrice: () => 99.99 };
+
+// MOCK: Verifies interactions. Use when you need to assert calls happened.
+const emailService = { send: vi.fn() };
+await registerUser(user, emailService);
+expect(emailService.send).toHaveBeenCalledWith(user.email, expect.any(String));
+
+// SPY: Wraps real implementation, records calls. Use for observation without replacement.
+const spy = vi.spyOn(logger, 'warn');
+await processOrder(invalidOrder);
+expect(spy).toHaveBeenCalledWith('Invalid order data');
+
+// FAKE: Simplified working implementation. Use for complex dependencies.
+class InMemoryUserRepo implements UserRepository {
+  private users = new Map<string, User>();
+  async save(user: User) { this.users.set(user.id, user); }
+  async findById(id: string) { return this.users.get(id) ?? null; }
+}
+
+// DUMMY: Placeholder that is never used. Use to satisfy required parameters.
+const unusedLogger = {} as Logger;
+const calc = new PriceCalculator(unusedLogger); // logger not called in this test
+```
+
+### Dependency Injection for Testability
+
+```typescript
+// BAD: Hard dependency -- impossible to test without real DB
+class UserService {
+  async getUser(id: string) {
+    return await database.query('SELECT * FROM users WHERE id = ?', [id]);
+  }
+}
+
+// GOOD: Inject dependency -- testable with fake/mock
+class UserService {
+  constructor(private repo: UserRepository) {}
+
+  async getUser(id: string) {
+    return this.repo.findById(id);
+  }
+}
+
+// Test with fake
+const repo = new InMemoryUserRepo();
+await repo.save({ id: '1', name: 'Alice', email: 'alice@test.com' });
+const service = new UserService(repo);
+const user = await service.getUser('1');
+expect(user?.name).toBe('Alice');
+```
+
+### Database Isolation
+
+```typescript
+// Per-test truncation -- clean slate for every test
+beforeEach(async () => {
+  await db.query('TRUNCATE users, orders, products CASCADE');
+});
+
+// Test containers -- isolated DB per test suite
+import { PostgreSqlContainer } from '@testcontainers/postgresql';
+
+let container: StartedPostgreSqlContainer;
+beforeAll(async () => {
+  container = await new PostgreSqlContainer().start();
+  await runMigrations(container.getConnectionUri());
+});
+afterAll(async () => { await container.stop(); });
+
+// Transaction rollback -- fastest, wraps each test in a transaction
+beforeEach(async () => { await db.query('BEGIN'); });
+afterEach(async () => { await db.query('ROLLBACK'); });
+```
+
+### Network Isolation
+
+```typescript
+// Playwright: intercept all external calls
+await page.route('**/api/**', (route) => {
+  route.fulfill({
+    status: 200,
+    body: JSON.stringify({ users: [{ id: 1, name: 'Test User' }] }),
+  });
+});
+
+// Intercept BEFORE navigate to prevent race conditions
+const responsePromise = page.waitForResponse('**/api/dashboard');
+await page.goto('/dashboard');
+await responsePromise;
+```
+
+## Anti-Patterns
+
+1. **Shared mutable state** -- Global variables modified by tests. Use fresh instances
+   per test or factory functions that return new objects each time.
+
+2. **Order-dependent tests** -- Test B relies on data created by test A. Each test must
+   set up and tear down its own data.
+
+3. **Real network calls in tests** -- Tests hitting live APIs are slow, flaky, and
+   nondeterministic. Mock or intercept all external network calls.
+
+4. **Mocking what you do not own** -- Mocking third-party library internals creates
+   brittle tests. Wrap the library in your own adapter, then mock the adapter.
+
+5. **Over-mocking** -- Mocking every dependency reduces test confidence. Use fakes for
+   complex dependencies, mocks for interaction verification, and real implementations
+   when fast and deterministic.
+
+## Integration Points
+
+- **Workflows**: `test-framework` (isolation setup), `test-review` (isolation audit)
+- **Related fragments**: `fixture-architecture` (cleanup in fixtures),
+  `deterministic-testing` (preventing flakiness), `data-factories` (per-test data
+  generation)

package/_gaia/testing/knowledge/core/test-pyramid.md

@@ -0,0 +1,129 @@
+---
+name: test-pyramid
+tier: core
+version: '1.0'
+---
+
+# Test Pyramid
+
+## Principle
+
+Test at the lowest effective level. The pyramid is a risk allocation model, not a rigid
+ratio. Unit tests (70%) cover business logic fast. Integration tests (20%) validate
+component boundaries. E2E tests (10%) guard critical user journeys. Push tests down
+the pyramid whenever possible.
+
+## Rationale
+
+Over-reliance on E2E tests creates slow, brittle, expensive suites. Under-investment in
+unit tests means business logic bugs hide behind UI layers. The pyramid ensures fast
+feedback for logic, focused validation for boundaries, and high-confidence checks for
+critical paths -- without redundant coverage at multiple levels.
+
+## Pattern Examples
+
+### Unit Tests -- Pure Business Logic
+
+```typescript
+// src/utils/price-calculator.test.ts
+import { calculateDiscount, applyTaxes } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  it('applies percentage discount', () => {
+    expect(calculateDiscount(100, { type: 'percentage', value: 20 })).toBe(80);
+  });
+
+  it('floors discount at zero', () => {
+    expect(calculateDiscount(10, { type: 'fixed', value: 20 })).toBe(0);
+  });
+
+  it('calculates tax correctly', () => {
+    expect(applyTaxes(100, { country: 'US', rate: 0.08 })).toBe(108);
+  });
+});
+```
+
+**When to use**: Pure functions, algorithms, input validation, complex calculations,
+state machines. No external dependencies. Fast (milliseconds).
+
+### Integration Tests -- Service Boundaries
+
+```typescript
+// tests/integration/user-service.spec.ts
+test('creates user with role assignment via API', async ({ request }) => {
+  const response = await request.post('/api/users', {
+    data: { name: 'Jane', email: 'jane@example.com', role: 'admin' },
+  });
+
+  expect(response.status()).toBe(201);
+  const user = await response.json();
+  expect(user.role).toBe('admin');
+  expect(user.permissions).toContain('user:delete');
+});
+
+test('rejects duplicate email', async ({ request }) => {
+  await request.post('/api/users', { data: { email: 'dup@example.com' } });
+  const dup = await request.post('/api/users', { data: { email: 'dup@example.com' } });
+  expect(dup.status()).toBe(409);
+});
+```
+
+**When to use**: Database operations, API contracts, service-to-service communication,
+middleware behavior. Moderate speed.
+
+### E2E Tests -- Critical User Journeys
+
+```typescript
+// tests/e2e/checkout.spec.ts
+test('user completes purchase', async ({ page }) => {
+  const loginPromise = page.waitForResponse('**/api/auth/login');
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+  await loginPromise;
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="place-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+```
+
+**When to use**: Revenue-critical paths, cross-system workflows, visual regression,
+compliance requirements. Slowest -- reserve for what matters most.
+
+### Decision Matrix
+
+| Scenario               | Unit         | Integration   | E2E          |
+|------------------------|--------------|---------------|--------------|
+| Pure business logic    | Primary      | Overkill      | Overkill     |
+| Database operations    | Cannot test  | Primary       | Overkill     |
+| API contracts          | Cannot test  | Primary       | Supplement   |
+| User journeys          | Cannot test  | Cannot test   | Primary      |
+| Component props/events | Partial      | Component test| Overkill     |
+| Visual regression      | Cannot test  | Component test| Primary      |
+
+## Anti-Patterns
+
+1. **E2E testing business logic** -- Testing a discount calculation through the UI is
+   slow and brittle. Use a unit test. The UI is for validation, not computation.
+
+2. **Unit testing framework behavior** -- Testing that React renders a component or
+   Express routes a request validates the framework, not your code.
+
+3. **Duplicate coverage across levels** -- If a unit test covers discount math, do not
+   also write an integration test for the same math. Each level should test different
+   aspects.
+
+4. **Inverted pyramid** -- More E2E than unit tests means slow CI, flaky suites, and
+   developers avoiding the test suite entirely.
+
+5. **Skipping the duplicate coverage guard** -- Before adding any test, ask: is this
+   already tested at a lower level? Can a unit test cover this instead of integration?
+
+## Integration Points
+
+- **Workflows**: `test-design` (level selection), `teach-me-testing` (pyramid education)
+- **Related fragments**: `fixture-architecture` (test helpers per level),
+  `test-isolation` (isolation strategies per level), `api-testing-patterns` (integration
+  layer patterns)