跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add petrkindlmann/qa-skills --skill api-testing

技能说明


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:

  1. REST, GraphQL, or both? REST-only suites use standard HTTP assertions. GraphQL needs query/mutation builders and benefits from an introspection-diff snapshot.
  2. Auth mechanism? JWT, API key, OAuth 2.0, or session cookies — each needs a different fixture strategy.
  3. 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

  1. Test contracts, not implementations. Assert on response shape, status codes, and headers — not on internal logic or database state.
  2. Schema validation catches drift before it breaks consumers. A failing schema test means you caught a breaking change before your frontend did.
  3. Auth flows are tests too — don't just hardcode tokens. Test login, refresh, expiration, and permission boundaries.
  4. 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:

ToolBest forWhy
Bruno (v3.4+)File-based collections, git-reviewable workflows, FOSS Postman replacementFilesystem-first, no cloud sync required; gRPC + OAuth + GraphQL query builder
Hurl (8.x)Plain-text HTTP testing, CI smoke checksOne file = many requests + assertions; runs anywhere curl runs; certificate + JSONPath (RFC 9535) queries
HoppscotchWeb-based Postman-style explorationOpen source, runs in browser, good for quick checks
Playwright APIRequestContextAutomated tests in your test runnerThis skill's focus — covered below
Supertest (Node) / httpx (Python)In-process API tests against your own appFastest 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 APIRequestContext to 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, safeParse the response, and assert result.success. Log result.error.issues on failure for a precise diff. Use the Zod 4 native string formats: z.email(), z.uuid(), z.iso.datetime() — the chained z.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.serial block 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
阅读完整来源 ↗