gaia-framework 1.57.0 → 1.57.2

package/_gaia/testing/knowledge/performance/k6-patterns.md

@@ -1,200 +0,0 @@
----
-name: k6-patterns
-tier: performance
-version: '1.0'
----
-
-# k6 Patterns
-
-## Principle
-
-k6 is a developer-centric load testing tool that uses JavaScript for test scripts.
-It runs locally or in CI, produces metrics in real-time, and integrates with monitoring
-systems. Write load tests as code, version them with your application, and run them
-as part of your deployment pipeline.
-
-## Rationale
-
-Performance problems discovered in production are expensive to fix. k6 enables
-shift-left performance testing — running load tests in CI catches regressions before
-deployment. Its JavaScript API is familiar to developers, reducing the barrier to
-writing and maintaining performance tests.
-
-## Pattern Examples
-
-### Basic Load Test
-
-```javascript
-import http from 'k6/http';
-import { check, sleep } from 'k6';
-
-export const options = {
-  stages: [
-    { duration: '2m', target: 50 },   // ramp up to 50 users
-    { duration: '5m', target: 50 },   // hold at 50
-    { duration: '2m', target: 0 },    // ramp down
-  ],
-  thresholds: {
-    http_req_duration: ['p(95)<500'],  // 95% of requests under 500ms
-    http_req_failed: ['rate<0.01'],    // less than 1% failure rate
-  },
-};
-
-export default function () {
-  const res = http.get('https://api.example.com/users');
-
-  check(res, {
-    'status is 200': (r) => r.status === 200,
-    'response time < 500ms': (r) => r.timings.duration < 500,
-    'body has users': (r) => JSON.parse(r.body).length > 0,
-  });
-
-  sleep(1); // think time between requests
-}
-```
-
-### Test Scenarios
-
-```javascript
-// Spike test — sudden traffic surge
-export const options = {
-  stages: [
-    { duration: '30s', target: 10 },
-    { duration: '1m', target: 500 },   // sudden spike
-    { duration: '30s', target: 500 },
-    { duration: '1m', target: 10 },    // recovery
-  ],
-};
-
-// Soak test — sustained load over time
-export const options = {
-  stages: [
-    { duration: '5m', target: 100 },
-    { duration: '4h', target: 100 },   // long duration
-    { duration: '5m', target: 0 },
-  ],
-};
-
-// Stress test — increasing load to find breaking point
-export const options = {
-  stages: [
-    { duration: '2m', target: 100 },
-    { duration: '2m', target: 200 },
-    { duration: '2m', target: 300 },
-    { duration: '2m', target: 400 },   // keep increasing
-    { duration: '2m', target: 500 },
-    { duration: '5m', target: 0 },
-  ],
-};
-```
-
-### Virtual User Profiles
-
-```javascript
-import { scenario } from 'k6/execution';
-
-export const options = {
-  scenarios: {
-    browse: {
-      executor: 'ramping-vus',
-      startVUs: 0,
-      stages: [{ duration: '5m', target: 100 }],
-      exec: 'browseProducts',
-    },
-    checkout: {
-      executor: 'constant-arrival-rate',
-      rate: 10,
-      timeUnit: '1s',
-      duration: '5m',
-      preAllocatedVUs: 50,
-      exec: 'completePurchase',
-    },
-    api: {
-      executor: 'constant-vus',
-      vus: 20,
-      duration: '5m',
-      exec: 'apiCalls',
-    },
-  },
-};
-
-export function browseProducts() {
-  http.get('https://api.example.com/products');
-  sleep(Math.random() * 3 + 1);
-}
-export function completePurchase() {
-  const cart = http.post('https://api.example.com/cart', JSON.stringify({
-    items: [{ id: 1, quantity: 1 }],
-  }), { headers: { 'Content-Type': 'application/json' } });
-  http.post('https://api.example.com/checkout', JSON.stringify({
-    cartId: JSON.parse(cart.body).id,
-  }), { headers: { 'Content-Type': 'application/json' } });
-}
-```
-
-### Thresholds and Custom Metrics
-
-```javascript
-export const options = {
-  thresholds: {
-    http_req_duration: ['p(50)<200', 'p(95)<500', 'p(99)<1000'],
-    http_req_failed: ['rate<0.01'],
-    'http_req_duration{name:login}': ['p(95)<300'],
-    checks: ['rate>0.99'],
-  },
-};
-```
-
-### Custom Metrics
-
-```javascript
-import { Trend, Counter, Rate } from 'k6/metrics';
-
-const loginDuration = new Trend('login_duration');
-const errorCount = new Counter('errors');
-const successRate = new Rate('success_rate');
-
-export default function () {
-  const start = Date.now();
-  const res = http.post('https://api.example.com/login', JSON.stringify({
-    email: 'test@example.com',
-    password: 'password',
-  }));
-
-  loginDuration.add(Date.now() - start);
-  errorCount.add(res.status !== 200 ? 1 : 0);
-  successRate.add(res.status === 200);
-}
-```
-
-### CI Integration (GitHub Actions)
-
-```yaml
-- name: Run k6 load test
-  uses: grafana/k6-action@v0.3.1
-  with:
-    filename: tests/performance/load-test.js
-```
-
-## Anti-Patterns
-
-1. **No think time** — Omitting `sleep()` between requests creates unrealistic load
-   patterns. Real users pause between actions.
-
-2. **Single endpoint testing** — Load testing only one endpoint misses interaction
-   effects. Test realistic user journeys across multiple endpoints.
-
-3. **Ignoring ramp-up** — Jumping straight to peak load triggers cold-start failures
-   that mask real issues. Always ramp up gradually.
-
-4. **Testing in development** — Load test results are only meaningful against
-   production-like infrastructure. Test against staging with realistic data.
-
-5. **No thresholds** — Running load tests without pass/fail criteria makes them
-   informational only. Define thresholds and fail CI on violations.
-
-## Integration Points
-
-- **Tools**: k6, Grafana Cloud, InfluxDB, GitHub Actions
-- **Workflows**: `performance-testing` (test plan), `ci-setup` (pipeline integration)
-- **Related fragments**: `lighthouse-ci` (frontend performance)

package/_gaia/testing/knowledge/performance/lighthouse-ci.md

@@ -1,158 +0,0 @@
----
-name: lighthouse-ci
-tier: performance
-version: '1.0'
----
-
-# Lighthouse CI
-
-## Principle
-
-Lighthouse CI integrates Google Lighthouse into your CI/CD pipeline, enforcing
-performance budgets and Core Web Vitals targets on every build. It tracks scores
-over time, preventing gradual performance degradation that manual testing misses.
-
-## Rationale
-
-Frontend performance regressions are introduced incrementally — a new dependency here,
-an unoptimized image there. By the time the impact is noticed, dozens of changes
-contribute to the problem. Lighthouse CI creates a performance ratchet that catches
-regressions at the PR level, when they are cheapest to fix.
-
-## Pattern Examples
-
-### Lighthouse CI Configuration
-
-```javascript
-// lighthouserc.js
-module.exports = {
-  ci: {
-    collect: {
-      url: [
-        'http://localhost:3000/',
-        'http://localhost:3000/dashboard',
-        'http://localhost:3000/products',
-      ],
-      startServerCommand: 'npm run start',
-      numberOfRuns: 3, // median of 3 runs for stability
-    },
-    assert: {
-      assertions: {
-        'categories:performance': ['error', { minScore: 0.9 }],
-        'categories:accessibility': ['error', { minScore: 0.9 }],
-        'categories:best-practices': ['warn', { minScore: 0.85 }],
-        'categories:seo': ['warn', { minScore: 0.9 }],
-      },
-    },
-    upload: {
-      target: 'temporary-public-storage', // or 'lhci' for self-hosted
-    },
-  },
-};
-```
-
-### Core Web Vitals Targets
-
-```javascript
-// lighthouserc.js — CWV-focused assertions
-module.exports = {
-  ci: {
-    assert: {
-      assertions: {
-        // Largest Contentful Paint — under 2.5s
-        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
-
-        // Interaction to Next Paint (replaces FID) — under 200ms
-        'interactive': ['error', { maxNumericValue: 3800 }],
-
-        // Cumulative Layout Shift — under 0.1
-        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
-
-        // First Contentful Paint — under 1.8s
-        'first-contentful-paint': ['warn', { maxNumericValue: 1800 }],
-
-        // Total Blocking Time — under 200ms
-        'total-blocking-time': ['error', { maxNumericValue: 200 }],
-
-        // Speed Index — under 3.4s
-        'speed-index': ['warn', { maxNumericValue: 3400 }],
-      },
-    },
-  },
-};
-```
-
-### Performance Budgets
-
-```javascript
-// lighthouserc.js — resource budgets
-module.exports = {
-  ci: {
-    assert: {
-      assertions: {
-        'resource-summary:script:size': ['error', { maxNumericValue: 300000 }],  // 300KB JS
-        'resource-summary:stylesheet:size': ['warn', { maxNumericValue: 50000 }], // 50KB CSS
-        'resource-summary:image:size': ['warn', { maxNumericValue: 500000 }],     // 500KB images
-        'resource-summary:total:size': ['error', { maxNumericValue: 1000000 }],   // 1MB total
-        'resource-summary:third-party:size': ['warn', { maxNumericValue: 200000 }],
-      },
-    },
-  },
-};
-
-```
-
-### GitHub Actions Integration
-
-```yaml
-- name: Run Lighthouse CI
-  uses: treosh/lighthouse-ci-action@v11
-  with:
-    configPath: './lighthouserc.js'
-    uploadArtifacts: true
-    temporaryPublicStorage: true
-```
-
-### Bundle Analysis Integration
-
-```javascript
-// webpack.config.js
-const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
-module.exports = {
-  plugins: [
-    new BundleAnalyzerPlugin({
-      analyzerMode: process.env.CI ? 'static' : 'server',
-      reportFilename: 'bundle-report.html',
-    }),
-  ],
-};
-
-// Next.js — next.config.js
-const withBundleAnalyzer = require('@next/bundle-analyzer')({
-  enabled: process.env.ANALYZE === 'true',
-});
-module.exports = withBundleAnalyzer({ /* next config */ });
-```
-
-## Anti-Patterns
-
-1. **Warning-only thresholds** — Using `warn` for critical metrics lets regressions
-   through. Use `error` for Core Web Vitals and `warn` for secondary metrics.
-
-2. **Single-run results** — One Lighthouse run has high variance. Always use
-   `numberOfRuns: 3` or more and take the median.
-
-3. **Testing development builds** — Development builds include source maps and debug
-   code. Always test production builds for accurate results.
-
-4. **Ignoring third-party impact** — Third-party scripts (analytics, ads, widgets)
-   significantly affect performance. Budget for and track them separately.
-
-5. **No historical tracking** — Without a Lighthouse CI server, you lose trending data.
-   Set up self-hosted LHCI or use temporary public storage for PR comparisons.
-
-## Integration Points
-
-- **Tools**: Lighthouse CI, webpack-bundle-analyzer, @next/bundle-analyzer
-- **Workflows**: `performance-testing` (test plan), `ci-setup` (pipeline integration)
-- **Related fragments**: `k6-patterns` (backend performance)

package/_gaia/testing/knowledge/specialized/contract-testing.md

@@ -1,173 +0,0 @@
----
-name: contract-testing
-tier: specialized
-version: '1.0'
----
-
-# Contract Testing
-
-## Principle
-
-Contract testing validates API contracts between consumer and provider services without
-requiring integrated end-to-end tests. Consumers define expectations as pact files,
-providers verify against them independently. This enables parallel development, catches
-breaking changes before merge, and documents API behavior as executable specifications.
-
-## Rationale
-
-Traditional integration testing requires running consumer and provider simultaneously,
-creating slow and flaky tests with complex setup. Contract testing decouples services:
-consumers define expectations (pact files), providers verify independently. The Pact
-Broker acts as a central contract registry, enabling `can-i-deploy` safety checks before
-production deployment.
-
-## Pattern Examples
-
-### Consumer Test (Frontend defines expectations)
-
-```typescript
-// tests/contract/user-api.pact.spec.ts
-import { PactV3, MatchersV3 } from '@pact-foundation/pact';
-import { getUserById } from '@/api/user-service';
-
-const { like, string, integer } = MatchersV3;
-
-const provider = new PactV3({
-  consumer: 'user-management-web',
-  provider: 'user-api-service',
-  dir: './pacts',
-});
-
-describe('User API Contract', () => {
-  it('returns user when exists', async () => {
-    await provider
-      .given('user with id 1 exists')       // Provider state
-      .uponReceiving('a request for user 1')
-      .withRequest({
-        method: 'GET',
-        path: '/users/1',
-        headers: { Authorization: like('Bearer token123') },
-      })
-      .willRespondWith({
-        status: 200,
-        body: like({
-          id: integer(1),
-          name: string('John Doe'),
-          email: string('john@example.com'),
-        }),
-      })
-      .executeTest(async (mockServer) => {
-        const user = await getUserById(1, { baseURL: mockServer.url });
-        expect(user.name).toBe('John Doe');
-      });
-  });
-
-  it('handles 404 when user missing', async () => {
-    await provider
-      .given('user with id 999 does not exist')
-      .uponReceiving('a request for non-existent user')
-      .withRequest({ method: 'GET', path: '/users/999' })
-      .willRespondWith({
-        status: 404,
-        body: { error: 'User not found', code: 'USER_NOT_FOUND' },
-      })
-      .executeTest(async (mockServer) => {
-        await expect(getUserById(999, { baseURL: mockServer.url }))
-          .rejects.toThrow('User not found');
-      });
-  });
-});
-```
-
-### Provider Verification
-
-```typescript
-// tests/contract/user-api.provider.spec.ts
-import { Verifier } from '@pact-foundation/pact';
-import { seedDatabase, resetDatabase } from '../support/db-helpers';
-
-describe('Provider Verification', () => {
-  it('verifies pacts from all consumers', async () => {
-    await new Verifier({
-      provider: 'user-api-service',
-      providerBaseUrl: `http://localhost:${PORT}`,
-      pactBrokerUrl: process.env.PACT_BROKER_URL,
-      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
-      publishVerificationResult: process.env.CI === 'true',
-      providerVersion: process.env.GIT_SHA,
-
-      stateHandlers: {
-        'user with id 1 exists': async () => {
-          await seedDatabase({ users: [{ id: 1, name: 'John Doe' }] });
-        },
-        'user with id 999 does not exist': async () => {
-          await resetDatabase();
-        },
-      },
-
-      requestFilter: (req, res, next) => {
-        req.headers['authorization'] = 'Bearer valid-test-token';
-        next();
-      },
-    }).verifyProvider();
-  });
-});
-```
-
-### CI Integration
-
-```yaml
-# Consumer: publish pacts on merge
-- name: Run consumer contract tests
-  run: npm run test:contract
-- name: Publish pacts
-  run: |
-    npx pact-broker publish ./pacts \
-      --consumer-app-version ${{ github.sha }} \
-      --branch ${{ github.head_ref || github.ref_name }}
-
-# Provider: verify on PR + webhook trigger
-- name: Verify pacts
-  run: npm run test:contract:provider
-- name: Can I Deploy?
-  run: |
-    npx pact-broker can-i-deploy \
-      --pacticipant user-api-service \
-      --version ${{ github.sha }} \
-      --to-environment production
-```
-
-### When Contract vs Integration
-
-| Scenario                      | Contract    | Integration |
-|-------------------------------|-------------|-------------|
-| API shape validation          | Primary     | Supplement  |
-| Cross-team service boundaries | Primary     | Overkill    |
-| Same-team microservices       | Supplement  | Primary     |
-| Database interactions         | Cannot test | Primary     |
-| Breaking change detection     | Primary     | Cannot test |
-
-## Anti-Patterns
-
-1. **Skipping provider states** -- Consumer tests that do not define `given()` states
-   leave the provider guessing about what data to set up. Always define states explicitly.
-
-2. **Testing implementation details** -- Contracts should define the API shape, not
-   internal behavior. Avoid asserting on exact header values or response timing.
-
-3. **No can-i-deploy check** -- Publishing pacts without checking compatibility before
-   deploy defeats the purpose. Always gate deployments on `can-i-deploy`.
-
-4. **Contract sprawl** -- Old pacts from deleted branches clutter the broker. Set up
-   weekly cleanup with retention policies (keep 30 days, production tags, branch latest).
-
-5. **Replacing all integration tests** -- Contract tests verify shape, not behavior.
-   Keep integration tests for data integrity, transactions, and business logic that
-   crosses service boundaries.
-
-## Integration Points
-
-- **Workflows**: `test-design` (deciding when to use contracts), `ci-setup` (Pact broker
-  integration)
-- **Related fragments**: `api-testing-patterns` (API test structure),
-  `test-pyramid` (where contracts fit), `risk-governance` (contracts as quality gates)

package/_gaia/testing/knowledge/specialized/test-healing.md

@@ -1,129 +0,0 @@
----
-name: test-healing
-tier: specialized
-version: '1.0'
----
-
-# Test Healing
-
-## Principle
-
-Common test failures follow predictable patterns: stale selectors, race conditions,
-dynamic data assertions, network errors, and hard waits. Catalog these failure signatures
-and apply pattern-based fixes. Automated healing identifies the failure type and suggests
-or applies the corresponding fix. Retries mask bugs -- fix the root cause instead.
-
-## Rationale
-
-Test failures waste developer time on repetitive debugging. Teams manually fix the same
-selector issues, timing bugs, and data mismatches across test suites. By cataloging
-common failure patterns with diagnostic signatures and fixes, maintenance shifts from
-reactive debugging to proactive pattern application, reducing repair time by 60-80%.
-
-## Pattern Examples
-
-### Failure Pattern Catalog
-
-| Failure Type   | Diagnostic Signature                        | Fix Strategy                          |
-|----------------|---------------------------------------------|---------------------------------------|
-| Stale selector | "locator resolved to 0 elements"            | Replace with data-testid or ARIA role |
-| Race condition | "timeout waiting for element"               | Add network-first interception        |
-| Dynamic data   | "Expected 'User 123' got 'User 456'"        | Use regex or capture dynamic values   |
-| Network error  | "API call failed", "500 error"              | Add route mocking                     |
-| Hard wait      | Code contains `waitForTimeout()` / `wait(n)`| Replace with event-based waits        |
-
-### Selector Fallback Strategy
-
-```typescript
-// Detect stale selector failure
-function isSelectorFailure(error: Error): boolean {
-  return /locator.*resolved to 0 elements|element not found/i.test(error.message);
-}
-
-// Suggest better selector based on what failed
-function suggestFix(badSelector: string): string {
-  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
-    return `page.getByTestId('...') // Replace CSS class with data-testid`;
-  }
-  if (badSelector.includes('.nth(')) {
-    return `page.locator('...').filter({ hasText: '...' }) // Replace nth with filter`;
-  }
-  if (badSelector.includes('>') || badSelector.includes('+')) {
-    return `page.getByRole('button', { name: '...' }) // Replace complex CSS with ARIA`;
-  }
-  return `page.getByTestId('...') // Add data-testid attribute to element`;
-}
-```
-
-### Auto-Wait Pattern (Replacing Hard Waits)
-
-```typescript
-// BEFORE: Flaky hard wait
-// await page.waitForTimeout(3000);
-
-// AFTER: Deterministic event-based wait
-// Option A: Wait for network response
-await page.waitForResponse(resp =>
-  resp.url().includes('/api/dashboard') && resp.ok()
-);
-
-// Option B: Wait for element state change
-await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
-
-// Option C: Network-first pattern (intercept before navigate)
-const dataPromise = page.waitForResponse('**/api/data');
-await page.goto('/page');
-await dataPromise;
-```
-
-### When Healing Hides Real Issues
-
-```typescript
-// DANGEROUS: Auto-retry on any failure
-test('dashboard loads', async ({ page }) => {
-  // retries: 3 in config -- masks the actual race condition
-  await page.goto('/dashboard');
-  await expect(page.getByText('Welcome')).toBeVisible();
-});
-
-// CORRECT: Fix the root cause
-test('dashboard loads', async ({ page }) => {
-  const dataPromise = page.waitForResponse('**/api/dashboard');
-  await page.goto('/dashboard');
-  await dataPromise; // Wait for actual data, not a timer
-  await expect(page.getByText('Welcome')).toBeVisible();
-});
-```
-
-### Healing Workflow
-
-1. **Run test** -- capture failure message and stack trace
-2. **Identify pattern** -- match error against diagnostic signatures
-3. **Apply fix** -- use pattern-based healing strategy
-4. **Re-run test** -- validate fix works (max 3 iterations)
-5. **Mark unfixable** -- use `test.fixme()` if healing fails after 3 attempts
-
-## Anti-Patterns
-
-1. **Retry as healing** -- Adding `retries: 3` to flaky tests hides bugs. Retries are
-   for CI infrastructure glitches, not test design problems.
-
-2. **Silent selector fallback** -- Auto-switching selectors without logging makes
-   debugging harder. Always log what was healed and why.
-
-3. **Healing without root cause analysis** -- Applying a fix without understanding why
-   the test broke means it will break again. Document the root cause.
-
-4. **Over-healing** -- Some test failures indicate real bugs. If a test fails because the
-   feature is broken, do not heal the test -- fix the feature.
-
-5. **No iteration limit** -- Healing loops without a max attempt count can run forever.
-   Cap at 3 attempts, then mark as `test.fixme()` for human review.
-
-## Integration Points
-
-- **Workflows**: `test-review` (healing recommendations), `test-automation` (auto-healing
-  after generation)
-- **Related fragments**: `selector-resilience` (resilient selector patterns),
-  `deterministic-testing` (preventing failures that need healing),
-  `fixture-architecture` (clean fixtures prevent state-related failures)