Bmad Testarch Ci

CI/CD Pipeline Setup

Goal: Scaffold CI/CD quality pipeline with test execution, burn-in loops, and artifact collection.

Role: You are the Master Test Architect.

You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.

Conventions

• Bare paths (e.g. instructions.md) 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.
• Resolve sibling workflow files such as instructions.md, checklist.md, steps-c/..., steps-e/..., steps-v/..., and templates from {skill-root}.

On Activation

Step 1: Resolve the Workflow Block

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

If the script fails, resolve the workflow 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 {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs resolved from {project-root} — expand them and load every matching file in lexical path order as facts. All other entries are facts verbatim.

Step 4: Load Config

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

• user_name
• communication_language

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

Step 6: Execute Append Steps

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

Activation is complete. Begin the workflow below.

Workflow Architecture

This workflow uses tri-modal step-file architecture:

• Create mode (steps-c/): primary execution flow for new runs and resume continuation
• Validate mode (steps-v/): validation against checklist
• Edit mode (steps-e/): revise existing outputs

Initialization Sequence

1. Mode Determination

"Welcome to the workflow. What would you like to do?"

• [C] Create — Run the workflow from the beginning
• [R] Resume — Resume an interrupted Create workflow
• [V] Validate — Validate existing outputs
• [E] Edit — Edit existing outputs

2. Route to First Step

• If C: Load {skill-root}/steps-c/step-01-preflight.md
• If R: Load {skill-root}/steps-c/step-01b-resume.md (Create-mode continuation)
• If V: Load {skill-root}/steps-v/step-01-validate.md
• If E: Load {skill-root}/steps-e/step-01-assess.md

CI/CD Pipeline Setup - Validation Checklist

Prerequisites

• [ ] Git repository initialized (.git/ exists)
• [ ] Git remote configured (git remote -v shows origin)
• [ ] Test framework configured (appropriate config for detected stack type)
• [ ] Local tests pass (test command succeeds)
• [ ] Team agrees on CI platform
• [ ] Access to CI platform settings (if updating)

Multi-Stack Detection

• [ ] Test stack type detected or configured (frontend, backend, fullstack)
• [ ] Test framework detected or configured (Playwright, Cypress, Jest, Vitest, etc.)
• [ ] Stack-appropriate test commands identified

Multi-Platform Detection

• [ ] CI platform detected or configured
• [ ] Supported platform: GitHub Actions, GitLab CI, Jenkins, Azure DevOps, Harness, or Circle CI
• [ ] Platform-specific template selected

Note: CI setup is typically a one-time task per repo and can be run any time after the test framework is configured.

Process Steps

Step 1: Preflight Checks

• [ ] Git repository validated
• [ ] Framework configuration detected
• [ ] Local test execution successful
• [ ] CI platform detected or selected
• [ ] Node version identified (.nvmrc or default)
• [ ] No blocking issues found

Step 2: CI Pipeline Configuration

• [ ] CI configuration file created at platform-correct path
• GitHub Actions: .github/workflows/test.yml
• GitLab CI: .gitlab-ci.yml
• Jenkins: Jenkinsfile
• Azure DevOps: azure-pipelines.yml
• Harness: .harness/pipeline.yaml
• Circle CI: .circleci/config.yml
• [ ] File is syntactically valid (no YAML/Groovy errors)
• [ ] Correct framework commands configured for detected stack type
• [ ] Node version matches project
• [ ] Test directory paths correct
• [ ] Stack-conditional steps applied:
• [ ] Browser install included for frontend/fullstack stacks
• [ ] Browser install omitted for backend-only stacks
• [ ] Test commands match detected framework

Step 3: Parallel Sharding

• [ ] Matrix strategy configured (4 shards default)
• [ ] Shard syntax correct for framework
• [ ] fail-fast set to false
• [ ] Shard count appropriate for test suite size

Step 4: Burn-In Loop

• [ ] Burn-in job created (frontend/fullstack stacks) or intentionally skipped (backend-only)
• [ ] 10 iterations configured (when enabled)
• [ ] Proper exit on failure (|| exit 1)
• [ ] Runs on appropriate triggers (PR, cron)
• [ ] Failure artifacts uploaded
• [ ] Backend-only stacks: burn-in skipped by default (documented reason: targets UI flakiness)

Step 5: Caching Configuration

• [ ] Dependency cache configured (npm/yarn)
• [ ] Cache key uses lockfile hash
• [ ] Browser cache configured (Playwright/Cypress)
• [ ] Restore-keys defined for fallback
• [ ] Cache paths correct for platform

Step 6: Artifact Collection

• [ ] Artifacts upload on failure only
• [ ] Correct artifact paths (test-results/, traces/, etc.)
• [ ] Retention days set (30 default)
• [ ] Artifact names unique per shard
• [ ] No sensitive data in artifacts

Step 7: Retry Logic

• [ ] Retry action/strategy configured
• [ ] Max attempts: 2-3
• [ ] Timeout appropriate (30 min)
• [ ] Retry only on transient errors

Step 8: Helper Scripts

• [ ] scripts/test-changed.sh created
• [ ] scripts/ci-local.sh created
• [ ] scripts/burn-in.sh created (optional)
• [ ] Scripts are executable (chmod +x)
• [ ] Scripts use correct test commands
• [ ] Shebang present (#!/bin/bash)

Step 9: Documentation

• [ ] docs/ci.md created with pipeline guide
• [ ] docs/ci-secrets-checklist.md created
• [ ] Required secrets documented
• [ ] Setup instructions clear
• [ ] Troubleshooting section included
• [ ] Badge URLs provided (optional)

Output Validation

Configuration Validation

• [ ] CI file loads without errors
• [ ] All paths resolve correctly
• [ ] No hardcoded values (use env vars)
• [ ] Triggers configured (push, pull_request, schedule)
• [ ] Platform-specific syntax correct

Execution Validation

• [ ] First CI run triggered (push to remote)
• [ ] Pipeline starts without errors
• [ ] All jobs appear in CI dashboard
• [ ] Caching works (check logs for cache hit)
• [ ] Tests execute in parallel
• [ ] Artifacts collected on failure

Performance Validation

• [ ] Lint stage: <2 minutes
• [ ] Test stage (per shard): <10 minutes
• [ ] Burn-in stage: <30 minutes
• [ ] Total pipeline: <45 minutes
• [ ] Cache reduces install time by 2-5 minutes

Quality Checks

Best Practices Compliance

• [ ] Burn-in loop follows production patterns
• [ ] Parallel sharding configured optimally
• [ ] Failure-only artifact collection
• [ ] Selective testing enabled (optional)
• [ ] Retry logic handles transient failures only
• [ ] No secrets in configuration files

Knowledge Base Alignment

• [ ] Burn-in pattern matches ci-burn-in.md
• [ ] Selective testing matches selective-testing.md
• [ ] Artifact collection matches visual-debugging.md
• [ ] Test quality matches test-quality.md

Security Checks

• [ ] No credentials in CI configuration
• [ ] Secrets use platform secret management
• [ ] Environment variables for sensitive data
• [ ] Artifact retention appropriate (not too long)
• [ ] No debug output exposing secrets
• [ ] MUST: No ${{ inputs.* }} or user-controlled GitHub context (github.event.pull_request.title, github.event.issue.body, github.event.comment.body, github.head_ref) directly in run: blocks — all passed through env: intermediaries and referenced as "$ENV_VAR"

Integration Points

Status File Integration

• [ ] CI setup logged in Quality & Testing Progress section
• [ ] Status updated with completion timestamp
• [ ] Platform and configuration noted

Knowledge Base Integration

• [ ] Relevant knowledge fragments loaded
• [ ] Patterns applied from knowledge base
• [ ] Documentation references knowledge base
• [ ] Knowledge base references in README

Workflow Dependencies

• [ ] framework workflow completed first
• [ ] Can proceed to atdd workflow after CI setup
• [ ] Can proceed to automate workflow
• [ ] CI integrates with gate workflow

Completion Criteria

All must be true:

• [ ] All prerequisites met
• [ ] All process steps completed
• [ ] All output validations passed
• [ ] All quality checks passed
• [ ] All integration points verified
• [ ] First CI run successful
• [ ] Performance targets met
• [ ] Documentation complete

Post-Workflow Actions

User must complete:

1. [ ] Commit CI configuration 2. [ ] Push to remote repository 3. [ ] Configure required secrets in CI platform 4. [ ] Open PR to trigger first CI run 5. [ ] Monitor and verify pipeline execution 6. [ ] Adjust parallelism if needed (based on actual run times) 7. [ ] Set up notifications (optional)

Recommended next workflows:

1. [ ] Run atdd workflow for test generation 2. [ ] Run automate workflow for coverage expansion 3. [ ] Run gate workflow for quality gates

Rollback Procedure

If workflow fails:

1. [ ] Delete CI configuration file 2. [ ] Remove helper scripts directory 3. [ ] Remove documentation (docs/ci.md, etc.) 4. [ ] Clear CI platform secrets (if added) 5. [ ] Review error logs 6. [ ] Fix issues and retry workflow

Notes

Common Issues

Issue: CI file syntax errors

• Solution: Validate YAML syntax online or with linter

Issue: Tests fail in CI but pass locally

• Solution: Use scripts/ci-local.sh to mirror CI environment

Issue: Caching not working

• Solution: Check cache key formula, verify paths

Issue: Burn-in too slow

• Solution: Reduce iterations or run on cron only

Platform-Specific

GitHub Actions:

• Secrets: Repository Settings → Secrets and variables → Actions
• Runners: Ubuntu latest recommended
• Concurrency limits: 20 jobs for free tier

GitLab CI:

• Variables: Project Settings → CI/CD → Variables
• Runners: Shared or project-specific
• Pipeline quota: 400 minutes/month free tier

Jenkins:

• Credentials: Manage Jenkins → Manage Credentials
• Agents: Configure build agents with Node.js
• Plugins: Pipeline, JUnit, HTML Publisher recommended

Azure DevOps:

• Variables: Pipelines → Library → Variable groups
• Agent pools: Azure-hosted or self-hosted
• Parallel jobs: 1 free (Microsoft-hosted)

Harness:

• Connectors: Configure container registry and code repo connectors
• Delegates: Install Harness delegate in target infrastructure
• Steps: Use Run steps with appropriate container images

---

Checklist Complete: Sign off when all items validated.

Completed by: {name} Date: {date} Platform: {GitHub Actions, GitLab CI, Other} Notes: {notes}

<!-- Powered by BMAD-CORE™ -->

CI/CD Pipeline Setup

Version: 5.0 (Step-File Architecture)

---

Overview

Scaffold a production-ready CI/CD quality pipeline with test execution, burn-in loops for flaky detection, parallel sharding, artifact collection, and notifications.

---

WORKFLOW ARCHITECTURE

This workflow uses step-file architecture:

• Micro-file Design: Each step is self-contained
• JIT Loading: Only the current step file is in memory
• Sequential Enforcement: Execute steps in order

---

INITIALIZATION SEQUENCE

1. Configuration Loading

From workflow.yaml, resolve:

• config_source, test_artifacts, user_name, communication_language, document_output_language, date
• ci_platform, test_dir

2. First Step

Load, read completely, and execute: {skill-root}/steps-c/step-01-preflight.md

3. Resume Support

If the user selects Resume mode, load, read completely, and execute: {skill-root}/steps-c/step-01b-resume.md

This checks the output document for progress tracking frontmatter and routes to the next incomplete step.

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 }) => {
    /* ... */
  });
});

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

Pact.js Utils Request Filter

Principle

Use createRequestFilter and noOpRequestFilter from @seontechnologies/pactjs-utils to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.

Rationale

Problems with manual request filters

• Express type gymnastics: Pact's requestFilter expects (req, res, next) => void with Express-compatible types — but Pact doesn't re-export these types
• Double-Bearer bug: Easy to write Authorization: Bearer Bearer ${token} when the token generator already includes the prefix
• Inline complexity: Auth logic mixed with verifier config makes tests harder to read
• No-op boilerplate: Providers without auth still need a pass-through function or undefined

Solutions

• `createRequestFilter`: Accepts { tokenGenerator: () => string } — generator returns raw token value synchronously, filter adds Bearer prefix
• `noOpRequestFilter`: Pre-built pass-through for providers without auth requirements
• Bearer prefix contract: tokenGenerator returns raw value (e.g., "abc123"), filter always adds "Bearer " — impossible to double-prefix

Pattern Examples

Example 1: Basic Auth Injection

import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';

const opts = buildVerifierOptions({
  provider: 'SampleMoviesAPI',
  port: '3001',
  includeMainAndDeployed: true,
  stateHandlers: {
    /* ... */
  },
  requestFilter: createRequestFilter({
    // tokenGenerator returns raw token — filter adds "Bearer " prefix
    tokenGenerator: () => 'test-auth-token-123',
  }),
});

// Every request during verification will have:
// Authorization: Bearer test-auth-token-123

Key Points:

• tokenGenerator is synchronous (() => string) — if you need async token fetching, resolve the token before creating the filter
• Return the raw token value, NOT "Bearer ..." — the filter adds the prefix
• Filter sets Authorization header on every request during verification

Example 2: Dynamic Token (Pre-resolved)

import { createRequestFilter } from '@seontechnologies/pactjs-utils';

// Since tokenGenerator is synchronous, fetch the token before creating the filter
let cachedToken: string;

async function setupRequestFilter() {
  const response = await fetch('http://localhost:8080/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: process.env.TEST_CLIENT_ID,
      clientSecret: process.env.TEST_CLIENT_SECRET,
    }),
  });
  const { access_token } = await response.json();
  cachedToken = access_token;
}

const requestFilter = createRequestFilter({
  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
});

const opts = buildVerifierOptions({
  provider: 'SecureAPI',
  port: '3001',
  includeMainAndDeployed: true,
  stateHandlers: {
    /* ... */
  },
  requestFilter,
});

Example 3: No-Auth Provider

import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';

// For providers that don't require authentication
const opts = buildVerifierOptions({
  provider: 'PublicAPI',
  port: '3001',
  includeMainAndDeployed: true,
  stateHandlers: {
    /* ... */
  },
  requestFilter: noOpRequestFilter,
});

// noOpRequestFilter is equivalent to: (req, res, next) => next()

Example 4: Integration with buildVerifierOptions

import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
import type { StateHandlers } from '@seontechnologies/pactjs-utils';

// Complete provider verification setup
const stateHandlers: StateHandlers = {
  'user is authenticated': async () => {
    // Auth state is handled by the request filter, not state handler
  },
  'movie exists': {
    setup: async (params) => {
      await db.seed({ movies: [{ id: params?.id }] });
    },
    teardown: async () => {
      await db.clean('movies');
    },
  },
};

const requestFilter = createRequestFilter({
  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
});

const opts = buildVerifierOptions({
  provider: 'SampleMoviesAPI',
  port: process.env.PORT ?? '3001',
  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
  stateHandlers,
  requestFilter,
});

// Run verification
await new Verifier(opts).verifyProvider();

Key Points

• Bearer prefix contract: tokenGenerator returns raw value → filter adds "Bearer " → impossible to double-prefix
• Synchronous only: tokenGenerator must return string (not Promise<string>) — pre-resolve async tokens before creating the filter
• Separation of concerns: Auth logic in createRequestFilter, verification logic in buildVerifierOptions
• noOpRequestFilter: Use for providers without auth — cleaner than undefined or inline no-op
• Express compatible: The returned filter matches Pact's expected (req, res, next) => void signature

Related Fragments

• pactjs-utils-overview.md — installation, utility table, decision tree
• pactjs-utils-provider-verifier.md — buildVerifierOptions integration
• contract-testing.md — foundational patterns with raw Pact.js

Anti-Patterns

Wrong: Manual Bearer prefix with double-prefix risk

// ❌ Risk of double-prefix: "Bearer Bearer token"
requestFilter: (req, res, next) => {
  const token = getToken(); // What if getToken() returns "Bearer abc123"?
  req.headers['authorization'] = `Bearer ${token}`;
  next();
};

Right: Use createRequestFilter with raw token

// ✅ tokenGenerator returns raw value — filter handles prefix
requestFilter: createRequestFilter({
  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
});

Wrong: Inline auth logic in verifier config

// ❌ Auth logic mixed with verifier config
const opts: VerifierOptions = {
  provider: 'my-api',
  providerBaseUrl: 'http://localhost:3001',
  requestFilter: (req, res, next) => {
    const clientId = process.env.CLIENT_ID;
    const clientSecret = process.env.CLIENT_SECRET;
    // 10 lines of token fetching logic...
    req.headers['authorization'] = `Bearer ${token}`;
    next();
  },
  // ... rest of config
};

Right: Separate auth into createRequestFilter

// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
async function setupVerifierOptions() {
  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter

  const requestFilter = createRequestFilter({
    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
  });

  return buildVerifierOptions({
    provider: 'my-api',
    port: '3001',
    includeMainAndDeployed: true,
    requestFilter,
    stateHandlers: {
      /* ... */
    },
  });
}

// In tests/hooks, callers can await setupVerifierOptions():
// const opts = await setupVerifierOptions();

_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_

Workflow Plan: testarch-ci

Create Mode (steps-c)

• step-01-preflight.md

• step-02-generate-pipeline.md
• step-03-configure-quality-gates.md
• step-04-validate-and-summary.md

Validate Mode (steps-v)

• step-01-validate.md

Edit Mode (steps-e)

• step-01-assess.md
• step-02-apply-edit.md

Outputs

• CI config (e.g., {project-root}/.github/workflows/test.yml)

• Pipeline guidance and artifacts configuration