Documentation
Integrations
OpenAPI

OpenAPI

If your API already has an OpenAPI 3.0 or 3.1 document — hand-written, or generated by a framework like NestJS, FastAPI, or tsoa — Spectest can load it directly and run its operations as tests, without a parallel set of hand-written suites to keep in sync.

This page covers integrating Spectest into a project that already has a spec. For the full feature set (multi-example generation, negative/fuzz testing, links-based chaining, auth variants, coverage reporting), see the OpenAPI Testing guide.

Setup

No extra package is needed beyond spectest itself:

npm install --save-dev spectest

Point Spectest at the spec you already maintain, either on the command line or in spectest.config.js:

// spectest.config.js
export default {
  baseUrl: 'http://localhost:3000',
  openapi: './openapi.yaml',
};
npx spectest --openapi ./openapi.yaml --base-url=https://api.example.com

If your spec is generated at build time (e.g. via tsoa spec or a framework’s /openapi.json export), run that generation step before Spectest in CI so it always tests the current contract, not a stale checked-in copy.

Mixing with hand-written suites

Spec-generated tests and .spectest.js files under testDir share the same operationId namespace and dependency graph — a hand-written suite can dependsOn a spec-generated operation, and --coverage-report will report covered by hand-written test <operationId> for any spec operation your hand-written suite already exercises instead of double-testing it. This makes OpenAPI loading a good default for full contract coverage, with hand-written suites reserved for cases that need custom beforeSend/postTest logic.

Scaffolding editable suites

To turn spec-generated tests into a starting point you can hand-edit rather than running them purely in-memory:

npx spectest generate openapi-tests --openapi ./openapi.yaml --output ./test

CI/CD example 

- uses: actions/checkout@v3
- run: npm ci
- run: npm run build   # if your OpenAPI doc is generated at build time
- run: npx spectest --openapi ./openapi.yaml --coverage-report

Troubleshooting

  • Operation generated as skipped — Spectest couldn’t resolve a required value (missing example, unsupported media type/parameter serialization, unresolved external $ref, unsupported schema construct, or a missing openapiHooks/openapiAuth entry). Check the printed skipReason; it never fails the loader outright.
  • Duplicate operationId — a hand-written suite and the spec both define the same operationId; rename one or let the spec-generated test cover it.
  • Wrong server selected — if the document declares multiple servers entries, set openapiServer (URL or index) in config, --openapi-server on the CLI, or override with --base-url.

Related: OpenAPI Testing for the full guide, Zod for validating spec-driven responses with Zod schemas instead of raw JSON Schema.

VitestZod