api-test-generator

When to use

Invoke this skill when:

• A team maintains an OpenAPI 3.0 / 3.1 document (openapi.yaml, openapi.json).
• CI needs a contract-drift guard that fails when responses diverge from the spec.
• You want property-based fuzzing (Schemathesis) without hand-writing input permutations.
• You need a fast port of the OpenAPI spec into an existing Java/Node test project.

Do NOT use when: the service has no machine-readable spec (write OpenAPI first); the flow is multi-step UI interaction (use e2e-test-generator); you need a load test (use performance-test or k6/Gatling — outside scope).

Inputs

• spec (required): Path or URL to OpenAPI 3.x document.
• target (required): schemathesis, rest-assured, or supertest.
• base_url (required): Origin to test against, e.g. https://staging.example.com/api.
• auth (optional): { type: "bearer" | "apiKey" | "basic", env: "TEST_TOKEN" }. Default bearer from TEST_TOKEN.
• rate_limit_threshold (optional): Requests/second to use in rate-limit test. Default 20.
• out_dir (optional): Where to write tests. Defaults per target: tests/contract/, src/test/java/contract/, test/api/.

Outputs

• For schemathesis: a pytest module test_contract.py, a conftest.py with auth fixture, and a shell command to invoke via CLI.
• For rest-assured: one Java class per tag in the spec plus a BaseApiTest with auth setup.
• For supertest: one .test.ts per resource with Jest/Vitest describe blocks.
• A coverage report mapping each (path, method, response code) in the spec to a generated test.

Tool dependencies

• Read, Write, Grep, Glob (always).
• WebFetch when spec is a URL.
• For schemathesis: user must have pip install schemathesis pytest in their test env.
• For rest-assured: Maven/Gradle dependency io.rest-assured:rest-assured:5.x.
• For supertest: npm i -D supertest @types/supertest jest ajv (or vitest).

Procedure

1. Load the spec. If URL, fetch. Parse YAML/JSON. Extract: servers, securitySchemes, paths, operationIds, tags, request/response schemas.
2. Bucket endpoints. Group by tag; one file per tag (rest-assured, supertest) or a single pytest module (schemathesis).
3. Resolve auth. Map securitySchemes to an auth fixture that reads the token from auth.env.
4. Generate positive tests. For each operation, produce a request with a minimal valid body (schemathesis does this automatically; for manual targets, instantiate from example or required-fields-only).
5. Generate negative tests.
   • Missing required fields → expect 400.
   • Wrong type (string where integer) → expect 400 or 422.
   • Unauthenticated call → expect 401.
   • Wrong scope / forbidden → expect 403.
   • Unknown resource id → expect 404.
6. Generate rate-limit test. Fire rate_limit_threshold * 2 requests in a burst against a GET endpoint; assert at least one 429 and that Retry-After is present.
7. Validate every response against schema. Use schemathesis built-in validation, rest-assured.matchesJsonSchema, or ajv in supertest.
8. Emit a coverage table. Markdown file listing endpoint × response code × covered/uncovered.
9. Write CI snippet. A Makefile target or GitHub Actions step to run the suite on every PR.