api-testing
Test REST and GraphQL APIs with Playwright APIRequestContext, Supertest, or standalone HTTP clients. Covers schema validation with Zod 4/AJV, auth flow testing, CRUD lifecycle tests, error and header validation, pagination, and performance assertions. Use when: "API test," "endpoint test," "REST test," "GraphQL test," "schema validation," "Postman replacement." Not for: consumer-driven contract verification (Pact, broker) — use contract-testing; browser UI flows — use playwright-automation. Related: contract-testing, test-data-management, ci-cd-integration, playwright-automation.
petrkindlmann · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add petrkindlmann/qa-skills --skill api-testingAbout this skill
name: api-testing description: >- Test REST and GraphQL APIs with Playwright APIRequestContext, Supertest, or standalone HTTP clients. Covers schema validation with Zod 4/AJV, auth flow testing, CRUD lifecycle tests, error and header validation, pagination, and performance assertions. Use when: "API test," "endpoint test," "REST test," "GraphQL test," "schema validation," "Postman replacement." Not for: consumer-driven contract verification (Pact, broker) — use contract-testing; browser UI flows — use playwright-automation. Related: contract-testing, test-data-management, ci-cd-integration, playwright-automation. license: MIT metadata: author: kindlmann version: "2.0" category: automation
Discovery Questions
Check .agents/qa-project-context.md first — if it exists, use it and skip anything already answered there. Then:
- REST, GraphQL, or both? REST-only suites use standard HTTP assertions. GraphQL needs query/mutation builders and benefits from an introspection-diff snapshot.
- Auth mechanism? JWT, API key, OAuth 2.0, or session cookies — each needs a different fixture strategy.
- OpenAPI/Swagger spec available? If yes, auto-generate Zod schemas as contracts (
orval,openapi-zod-client) and consider spec-driven fuzzing with Schemathesis.
Core Principles
- Test contracts, not implementations. Assert on response shape, status codes, and headers — not on internal logic or database state.
- Schema validation catches drift before it breaks consumers. A failing schema test means you caught a breaking change before your frontend did.
- Auth flows are tests too — don't just hardcode tokens. Test login, refresh, expiration, and permission boundaries.
- Response time is a testable assertion. Performance regressions caught in CI are cheaper than production incidents.
Exploratory vs Automated: Tooling
API exploration (debugging, manual probing, OpenAPI playground) and automated API testing are different jobs. Use the right tool for each:
| Tool | Best for | Why |
|---|---|---|
| Bruno (v3.4+) | File-based collections, git-reviewable workflows, FOSS Postman replacement | Filesystem-first, no cloud sync required; gRPC + OAuth + GraphQL query builder |
| Hurl (8.x) | Plain-text HTTP testing, CI smoke checks | One file = many requests + assertions; runs anywhere curl runs; certificate + JSONPath (RFC 9535) queries |
| Hoppscotch | Web-based Postman-style exploration | Open source, runs in browser, good for quick checks |
Playwright APIRequestContext | Automated tests in your test runner | This skill's focus — covered below |
| Supertest (Node) / httpx (Python) | In-process API tests against your own app | Fastest feedback when you control both sides |
Skip Postman/Insomnia for new projects unless your team already has investment there — file-based tools (Bruno, Hurl) are easier to review in PRs and survive when collections drift.
Playwright API Testing
APIRequestContext supports standalone API tests without launching a browser and shares cookie/storage state with browser contexts. Use it for:
- Standalone API tests —
request.get/post/...with status, header, and body assertions. - Combined browser + API tests — seed data via API, assert it appears in the UI, then clean up via API.
- Authenticated fixtures — log in once in a fixture, hand a pre-authenticated
APIRequestContextto tests, and dispose it on teardown. Never hardcode tokens.
See references/playwright-setup.md for the playwright.config.ts, standalone tests, combined browser+API test, and the authenticated API fixture.
Schema Validation
Validate response shape against a schema rather than spot-checking individual fields with toHaveProperty. Two common approaches:
- Zod 4 — define a schema,
safeParsethe response, and assertresult.success. Logresult.error.issueson failure for a precise diff. Use the Zod 4 native string formats:z.email(),z.uuid(),z.iso.datetime()— the chainedz.string().email()forms are deprecated and slated for removal. - AJV with JSON Schema — when you already have JSON Schema (e.g. from an OpenAPI spec), compile and validate with
ajv+ajv-formats.
Schema-as-contract: have both the API and the tests import the same schema file. If the response shape changes, consumer tests fail immediately. With an OpenAPI spec, auto-generate the schema (orval or openapi-zod-client). For spec-first teams, add Schemathesis as a CI job to fuzz the live API against the spec and catch undocumented shapes and edge-case 500s.
See references/schema-validation.md for the Zod 4, AJV, schema-as-contract, and Schemathesis implementations.
Test Patterns
Cover each endpoint with a happy-path test plus at least one error-path test. The common patterns:
- CRUD lifecycle — a
describe.serialblock that creates, reads, updates, deletes, then verifies the 404. Carries the resource id across steps. - Auth flows — login success, invalid credentials (401), expired token (401), token refresh, and permission boundary (403). Treat auth as its own describe block.
- Error responses — 400 (malformed body), 422 (validation with field details), 429 (rate limit +
retry-after). Don't ship happy-path-only suites. - Response headers — assert
content-type,cache-control, and rate-limit headers directly (not behind a conditional that may never fire). See the pattern below. - Pagination — first-page metadata, ou