gaia-framework 1.57.0 → 1.57.2

package/_gaia/testing/knowledge/extended/api-testing-patterns.md

@@ -1,196 +0,0 @@
----
-name: api-testing-patterns
-tier: extended
-version: '1.0'
----
-
-# API Testing Patterns
-
-## Principle
-
-Test APIs and backend services directly without browser overhead. Use Playwright's
-`request` context for HTTP operations and Zod schemas for runtime validation. API-first
-testing provides faster feedback, better stability, and more focused coverage than
-testing backend logic through UI layers.
-
-## Rationale
-
-Many teams over-rely on E2E browser tests when API tests would be faster, more stable,
-and more precise. If you are testing what the server returns (not how it looks), use API
-tests. They run in milliseconds, have no browser startup cost, and provide clear
-request/response debugging without DOM noise.
-
-## Pattern Examples
-
-### Pure API Test (No Browser)
-
-```typescript
-// tests/api/users.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Users API', () => {
-  test('creates user', async ({ request }) => {
-    const response = await request.post('/api/users', {
-      data: { name: 'John Doe', email: 'john@example.com', role: 'user' },
-    });
-    expect(response.status()).toBe(201);
-    const user = await response.json();
-    expect(user.id).toBeDefined();
-    expect(user.email).toBe('john@example.com');
-  });
-
-  test('returns 404 for missing user', async ({ request }) => {
-    const response = await request.get('/api/users/nonexistent');
-    expect(response.status()).toBe(404);
-    const error = await response.json();
-    expect(error.code).toBe('USER_NOT_FOUND');
-  });
-
-  test('validates required fields', async ({ request }) => {
-    const response = await request.post('/api/users', {
-      data: { name: 'Missing Email' },
-    });
-    expect(response.status()).toBe(400);
-    const error = await response.json();
-    expect(error.code).toBe('VALIDATION_ERROR');
-  });
-});
-```
-
-### Schema Validation with Zod
-
-```typescript
-import { z } from 'zod';
-
-const OrderSchema = z.object({
-  id: z.string().uuid(),
-  userId: z.string(),
-  items: z.array(z.object({
-    productId: z.string(),
-    quantity: z.number().positive(),
-    price: z.number().positive(),
-  })),
-  total: z.number().positive(),
-  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
-  createdAt: z.string().datetime(),
-});
-
-test('creates order with valid schema', async ({ request }) => {
-  const response = await request.post('/api/orders', {
-    data: {
-      userId: 'user-123',
-      items: [{ productId: 'prod-1', quantity: 2, price: 29.99 }],
-    },
-  });
-  expect(response.status()).toBe(201);
-  const body = await response.json();
-  const parsed = OrderSchema.parse(body); // Throws if schema mismatch
-  expect(parsed.status).toBe('pending');
-});
-```
-
-### Error Response Validation
-
-```typescript
-test.describe('Error handling', () => {
-  test('handles duplicate email (409)', async ({ request }) => {
-    await request.post('/api/users', { data: { email: 'dup@test.com' } });
-    const dup = await request.post('/api/users', { data: { email: 'dup@test.com' } });
-    expect(dup.status()).toBe(409);
-    const error = await dup.json();
-    expect(error.message).toContain('already exists');
-  });
-
-  test('handles malformed JSON (400)', async ({ request }) => {
-    const response = await request.post('/api/users', {
-      headers: { 'Content-Type': 'application/json' },
-      data: 'not-json',
-    });
-    expect(response.status()).toBe(400);
-  });
-
-  test('handles rate limiting (429)', async ({ request }) => {
-    // Trigger rate limit
-    for (let i = 0; i < 100; i++) {
-      await request.get('/api/users');
-    }
-    const response = await request.get('/api/users');
-    expect(response.status()).toBe(429);
-    expect(response.headers()['retry-after']).toBeDefined();
-  });
-});
-```
-
-### Authentication in API Tests
-
-```typescript
-test.describe('Authenticated API', () => {
-  let authToken: string;
-
-  test.beforeAll(async ({ request }) => {
-    const res = await request.post('/api/auth/login', {
-      data: { email: process.env.TEST_USER_EMAIL, password: process.env.TEST_USER_PASSWORD },
-    });
-    authToken = (await res.json()).token;
-  });
-
-  test('accesses protected endpoint', async ({ request }) => {
-    const response = await request.get('/api/me', {
-      headers: { Authorization: `Bearer ${authToken}` },
-    });
-    expect(response.status()).toBe(200);
-  });
-
-  test('rejects missing token', async ({ request }) => {
-    const response = await request.get('/api/me');
-    expect(response.status()).toBe(401);
-  });
-
-  test('rejects insufficient role', async ({ request }) => {
-    const response = await request.get('/api/admin/users', {
-      headers: { Authorization: `Bearer ${authToken}` },
-    });
-    expect(response.status()).toBe(403);
-  });
-});
-```
-
-### API-Only Playwright Config
-
-```typescript
-export default defineConfig({
-  testDir: './tests/api',
-  use: {
-    baseURL: process.env.API_URL || 'http://localhost:3000',
-    extraHTTPHeaders: { Accept: 'application/json' },
-  },
-  timeout: 30000,
-  workers: 4,
-  fullyParallel: true,
-});
-```
-
-## Anti-Patterns
-
-1. **Testing APIs through UI** -- Filling a form and clicking submit to test user
-   creation validates the UI, not the API. Test the API directly.
-
-2. **No dedicated API test suite** -- Assuming E2E tests cover the API. E2E tests one
-   happy path; API tests cover edge cases, error codes, and validation.
-
-3. **Hardcoded test data** -- Static emails and IDs cause parallel test collisions.
-   Use factory functions with unique values.
-
-4. **Ignoring error responses** -- Only testing 200 responses. Test 400, 401, 403, 404,
-   409, 429, and 500 scenarios explicitly.
-
-5. **No schema validation** -- Trusting response shapes without runtime verification.
-   Use Zod or AJV to validate response structures.
-
-## Integration Points
-
-- **Workflows**: `test-design` (API test planning), `test-automation` (API test generation),
-  `atdd` (acceptance criteria via API)
-- **Related fragments**: `test-pyramid` (API tests are integration level),
-  `data-factories` (test data for API requests), `contract-testing` (Pact for service
-  contracts)

package/_gaia/testing/knowledge/extended/data-factories.md

@@ -1,158 +0,0 @@
----
-name: data-factories
-tier: extended
-version: '1.0'
----
-
-# Data Factories
-
-## Principle
-
-Prefer factory functions that accept overrides and return complete objects. Seed test
-state through APIs or direct DB helpers before visiting the UI -- never via slow UI
-interactions. The UI is for validation only, not data setup. Factories should generate
-unique, parallel-safe data with explicit overrides that reveal test intent.
-
-## Rationale
-
-Static fixtures (JSON files, hardcoded objects) create brittle tests that fail when
-schemas evolve, cause collisions in parallel execution, and hide test intent. Dynamic
-factories with overrides provide parallel safety (UUIDs prevent collisions), schema
-evolution (defaults adapt automatically), explicit intent (overrides show what matters),
-and speed (API seeding is 10-50x faster than UI).
-
-## Pattern Examples
-
-### Factory Function with Overrides
-
-```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,
-});
-
-// Usage -- override shows intent
-const admin = createUser({ role: 'admin' });
-const inactive = createUser({ isActive: false });
-```
-
-### Nested Factory Pattern (Relationships)
-
-```typescript
-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: string };
-
-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',
-    ...overrides,
-  };
-};
-```
-
-### Composed Specialized Factories
-
-```typescript
-// Compose from base -- do not duplicate
-export const createAdminUser = (overrides: Partial<User> = {}) =>
-  createUser({ role: 'admin', ...overrides });
-
-export const createProAccount = (overrides: Partial<Account> = {}) =>
-  createAccount({
-    plan: 'pro',
-    features: ['analytics', 'priority-support'],
-    maxUsers: 10,
-    ...overrides,
-  });
-
-// Test intent is immediately clear
-test('pro accounts access analytics', async ({ page, apiRequest }) => {
-  const admin = createAdminUser();
-  const account = createProAccount({ owner: admin });
-  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
-  await page.goto('/analytics');
-  await expect(page.getByText('Advanced Analytics')).toBeVisible();
-});
-```
-
-### API Seeding Helper
-
-```typescript
-// helpers/seed-helpers.ts
-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(`Seed failed: ${response.status()}`);
-  return user;
-}
-
-// Cleanup pattern
-const createdIds: string[] = [];
-afterEach(async ({ request }) => {
-  for (const id of createdIds) {
-    await request.delete(`/api/users/${id}`);
-  }
-  createdIds.length = 0;
-});
-```
-
-## Anti-Patterns
-
-1. **Hardcoded test data** -- `email: 'test@test.com'` causes collisions in parallel
-   runs. Use faker with unique values per test.
-
-2. **Static JSON fixtures** -- `fixtures/users.json` with fixed IDs breaks when schemas
-   change or tests run in parallel. Use factory functions.
-
-3. **UI-based data setup** -- Filling forms to create test data is 10-50x slower than
-   API calls. Use the UI only for validation.
-
-4. **Hidden test intent** -- `createUser()` with no overrides when the test cares about
-   a specific role. Always override the fields the test depends on.
-
-5. **No schema evolution strategy** -- When a required field is added to the schema, every
-   test with static data breaks. Factories centralize defaults -- update once, all tests
-   adapt.
-
-## Integration Points
-
-- **Workflows**: `test-framework` (factory scaffold), `test-automation` (factory usage in
-  generated tests)
-- **Related fragments**: `fixture-architecture` (factories used inside fixtures),
-  `test-isolation` (per-test data prevents state leaks), `api-testing-patterns` (API
-  seeding patterns)

package/_gaia/testing/knowledge/extended/risk-governance.md

@@ -1,119 +0,0 @@
----
-name: risk-governance
-tier: extended
-version: '1.0'
----
-
-# Risk Governance
-
-## Principle
-
-Risk governance transforms subjective "should we ship?" debates into objective,
-data-driven decisions. Score risk as probability (1-3) times impact (1-3) for a total
-of 1-9. Scores of 6 or above demand documented mitigation. A score of 9 blocks the
-release. Every acceptance criterion maps to a test, and gaps require explicit waivers.
-
-## Rationale
-
-Without formal risk governance, releases become political -- loud voices win, quiet risks
-hide, and teams discover critical issues in production. Risk scoring creates shared
-language, removes ambiguity, identifies true blockers early, distributes responsibility
-with owners and deadlines, and creates an audit trail for compliance (SOC2, ISO, FDA).
-
-## Pattern Examples
-
-### Risk Scoring Matrix
-
-```typescript
-type RiskScore = {
-  id: string;
-  category: 'TECH' | 'SEC' | 'PERF' | 'DATA' | 'BUS' | 'OPS';
-  title: string;
-  probability: 1 | 2 | 3;  // 1=Low, 2=Medium, 3=High
-  impact: 1 | 2 | 3;        // 1=Low, 2=Medium, 3=High
-  score: number;             // probability * impact (1-9)
-  owner: string;
-  mitigationPlan?: string;
-  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
-};
-
-function classifyRisk(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
-  if (score === 9) return 'CRITICAL';   // Blocks release
-  if (score >= 6) return 'HIGH';         // Requires mitigation plan
-  if (score >= 4) return 'MEDIUM';       // Monitor
-  return 'LOW';                          // Accept
-}
-```
-
-### Gate Decision Framework
-
-```typescript
-type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
-
-function evaluateGate(risks: RiskScore[], coverageGaps: CoverageGap[]): GateDecision {
-  const criticalOpen = risks.filter(r => r.score === 9 && r.status === 'OPEN');
-  const highOpen = risks.filter(r => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
-  const unresolvedGaps = coverageGaps.filter(g => !g.waiverReason);
-
-  // FAIL: Any critical (9) open risk or unresolved coverage gap
-  if (criticalOpen.length > 0 || unresolvedGaps.length > 0) return 'FAIL';
-
-  // CONCERNS: High risks (6-8) exist but have mitigation plans and owners
-  if (highOpen.length > 0 && highOpen.every(r => r.mitigationPlan && r.owner)) {
-    return 'CONCERNS';
-  }
-
-  // PASS: No critical issues, all high risks mitigated
-  return 'PASS';
-}
-```
-
-### Coverage Traceability
-
-```typescript
-type CoverageGap = {
-  acceptanceCriteria: string;
-  testMissing: string;
-  priority: 'P0' | 'P1' | 'P2' | 'P3';
-  waiverReason?: string;
-};
-
-function validateCoverage(
-  criteria: AcceptanceCriterion[],
-  tests: TestCase[]
-): { gaps: CoverageGap[]; passRate: number } {
-  const gaps = criteria
-    .filter(ac => !tests.some(t => t.criteriaIds.includes(ac.id)))
-    .map(ac => ({
-      acceptanceCriteria: ac.criterion,
-      testMissing: `Missing test for: ${ac.criterion}`,
-      priority: ac.priority,
-    }));
-
-  const passRate = ((criteria.length - gaps.length) / criteria.length) * 100;
-  return { gaps, passRate };
-}
-```
-
-## Anti-Patterns
-
-1. **No scoring system** -- "I think it's fine" is not risk management. Use the
-   probability x impact matrix consistently.
-
-2. **Unowned risks** -- Risks without assigned owners never get mitigated. Every risk
-   scoring 4 or above needs a named owner and a deadline.
-
-3. **Waivers without expiry** -- Permanent waivers accumulate tech debt silently. Every
-   waiver needs an approver, a reason, and an expiry date.
-
-4. **Coverage gaps without waivers** -- Untested acceptance criteria that nobody has
-   explicitly accepted as a risk. Make the decision visible.
-
-5. **Gate theater** -- Running gates but always overriding failures. If the gate never
-   blocks, it provides no value. Enforce the gate or remove it.
-
-## Integration Points
-
-- **Workflows**: `test-design` (risk identification), `nfr-assessment` (risk scoring)
-- **Related fragments**: `test-pyramid` (risk-based level selection),
-  `api-testing-patterns` (testing high-risk API paths)

package/_gaia/testing/knowledge/extended/selector-resilience.md

@@ -1,109 +0,0 @@
----
-name: selector-resilience
-tier: extended
-version: '1.0'
----
-
-# Selector Resilience
-
-## Principle
-
-Robust selectors follow a strict hierarchy: data-testid (best) > ARIA roles (good) >
-text content (acceptable) > CSS classes/IDs (last resort). Selectors must survive UI
-changes (styling, layout, content updates) and remain human-readable for maintenance.
-
-## Rationale
-
-Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes,
-elements are reordered, or design updates occur. This causes a test maintenance burden
-and false negatives. Semantic selectors that reflect user intent (ARIA roles, accessible
-names, test IDs) are resilient, improve accessibility, and self-document what the test
-is verifying.
-
-## Pattern Examples
-
-### Selector Hierarchy
-
-```typescript
-// LEVEL 1: data-testid (BEST -- survives all UI changes)
-await page.getByTestId('email-input').fill('user@example.com');
-await page.getByTestId('login-button').click();
-
-// LEVEL 2: ARIA roles (GOOD -- enforces accessibility)
-await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
-await page.getByRole('button', { name: 'Sign In' }).click();
-
-// LEVEL 3: Text content (ACCEPTABLE -- user-centric)
-await page.getByText('Create New Order').click();
-
-// LEVEL 4: CSS/ID (LAST RESORT -- brittle)
-// await page.locator('.btn-primary').click();  // Breaks with design updates
-```
-
-### Dynamic Content Patterns
-
-```typescript
-// Regex for variable content (IDs, timestamps)
-await expect(page.getByText(/User \d+/)).toBeVisible();
-await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
-
-// Filter instead of nth() -- content-based, not index-based
-await page.locator('[data-testid="product-card"]')
-  .filter({ hasText: 'Premium Plan' })
-  .click();
-
-// Scoped locators for disambiguation
-const shippingSection = page.getByTestId('shipping-section');
-await shippingSection.getByLabel('City').fill('New York');
-```
-
-### Refactoring Guide (Before/After)
-
-```typescript
-// CSS class -> data-testid
-// BEFORE: await page.locator('.bg-blue-500.px-4.rounded').click()
-// AFTER:
-await page.getByTestId('add-to-cart-button').click();
-
-// nth() index -> filter()
-// BEFORE: await page.locator('.user-row').nth(2).click()
-// AFTER:
-await page.locator('[data-testid="user-row"]')
-  .filter({ hasText: 'john@example.com' }).click();
-
-// Complex XPath -> ARIA role
-// BEFORE: await page.locator('xpath=//div[@id="payment"]//form//button').click()
-// AFTER:
-await page.getByRole('button', { name: 'Complete Payment' }).click();
-
-// Deep nesting -> scoped data-testid
-// BEFORE: await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
-// AFTER:
-const sidebar = page.getByTestId('sidebar');
-await sidebar.getByRole('link', { name: 'Settings' }).click();
-```
-
-## Anti-Patterns
-
-1. **CSS class selectors** -- `.btn-primary`, `.form-input-lg` break with every design
-   system update or Tailwind class change.
-
-2. **Arbitrary nth() indexes** -- `.product-card:nth(3)` breaks when items are reordered,
-   added, or removed. Use `filter({ hasText })` instead.
-
-3. **Complex XPath** -- `//div[@class="container"]//section[2]//button` is unreadable
-   and breaks with any HTML restructuring.
-
-4. **HTML ID selectors** -- `#user-settings-form` seems stable but IDs change during
-   accessibility improvements or component refactoring.
-
-5. **No scoping** -- Selecting `getByLabel('Name')` without scoping fails when multiple
-   forms have a "Name" field. Scope with `getByTestId('shipping-form').getByLabel('Name')`.
-
-## Integration Points
-
-- **Workflows**: `test-automation` (generate tests with robust selectors), `test-review`
-  (selector quality audit)
-- **Related fragments**: `test-healing` (selector fallback strategies),
-  `deterministic-testing` (stable selectors prevent flakiness),
-  `fixture-architecture` (fixtures as alternative to page objects)