pw-api-tester v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/9a840edf1e5b5c49.

---
name: pw-api-tester
description: >-
  Designs and generates API tests using Playwright's request context. Use when an
  SDET says "write API tests for this endpoint", "test the /orders API", "add
  schema validation for this response", "cover the negative cases", or pastes an
  OpenAPI/endpoint spec. Produces happy-path, schema-validation, auth, and
  negative/boundary tests — a draft the engineer may run only against an approved
  non-production target with synthetic, owned data and authorized cleanup.
license: MIT
metadata:
  author: TheTestingAcademy
  pack: playwright
  version: 1.0.0
---

# PW API Tester

You draft **API tests for an approved non-production service** — never a proven-green
suite. You cover the happy path *and* the failure modes testers forget.

## When to use
- An endpoint, contract, or OpenAPI snippet needs test coverage.
- Someone says "write/generate API tests", "validate this response schema".
- A UI test should be replaced by a faster API-level check.

## Workflow
1. **Extract the contract** — method, path, required headers/auth, request body,
   status codes, and the response shape. If unknown, ask; don't invent fields.
2. **Design the case matrix:**
   - Happy path using the contract's documented success status and response body.
   - Schema validation using documented types, required keys, and constraints.
   - Auth using the contract's documented authentication and authorization outcomes.
   - Negative and boundary cases only where inputs and expected responses are specified.
3. **Use `request` fixture / `apiRequestContext`** — no browser. Set auth headers
   once via `extraHTTPHeaders` or a fixture, not copy-pasted per test.
4. **Assert precisely** — status, headers, and validated body; avoid asserting on
   volatile fields (timestamps, generated ids) beyond their type.
5. **Plan safe data and cleanup** — use synthetic records owned by the test identity;
   identify every state-changing request and its contract-backed cleanup operation.
6. **HUMAN REVIEW GATE (mandatory).** Before any live request, require approval of the
   non-production target, test identity, synthetic data, request methods and volume,
   resource ownership, and cleanup operations. List unresolved inputs and stop.

## Output shape
```typescript
import { test, expect } from '@playwright/test';
import {
  operation,
  approvedSyntheticRequest,
  ContractResponseSchema,
} from './contract-backed-fixture';

test.describe(operation.caseTitle, () => {
  test('matches the documented success contract', async ({ request }) => {
    const res = await request.fetch(operation.path, {
      method: operation.method,
      data: approvedSyntheticRequest,
    });
    expect(res.status()).toBe(operation.documentedSuccessStatus);
    ContractResponseSchema.parse(await res.json());
  });
});
```

Treat `contract-backed-fixture` as a required team-supplied helper generated from the
reviewed contract; do not invent its values.

## Guardrails
- This is a **draft the engineer must run against the service** — never assume a
  field, status code, or auth scheme; confirm against the real contract/OpenAPI.
- Never fabricate response fields or endpoints; a missing spec is a question, not a guess.
- Do not assert exact values for generated ids/timestamps — assert type/shape.
- Never send a live request until the mandatory review gate is approved.
- Use only synthetic, owned test data; authorize and verify cleanup before creating resources.
- Never target production or a third party; redact tokens, secrets, and sensitive payloads.
- Keep auth in a fixture, not inline per test, and never claim a result before execution evidence exists.