← SpecCaster

Why your OpenAPI spec drifts — and how to make CI catch it

SpecCaster blog · 2026-09-11 · 3 min read

The worst bugs are the quiet ones. An API endpoint silently changes shape, and nothing on your team notices until the mobile app ships against a payload nobody documented anymore.

This is called spec drift. Your OpenAPI document stops matching both the code and the test suite. Here are the three patterns it usually takes.

Pattern 1: the code moves, the spec doesn't

A quick fix changes a response field from user_id to userId. The spec still says user_id. The spec now describes an API that doesn't exist.

Pattern 2: the test moves, neither notices

Someone relaxes an assertion to make a flaky test pass. The test still passes and now verifies nothing. For API tests this is how a 200 with the wrong body sails through every review.

Pattern 3: the spec moves, nothing regenerates

A new endpoint is added — spec updated, docs updated, test suite untouched. The contract test for the new endpoint simply doesn't exist. Green build, no coverage, happy silence.

In all three cases the failure mode is the same: the repository is internally inconsistent, and nothing in the pipeline is allowed to object.

The fix: make the committed suite the single source of truth

Hand-maintained test files drift because keeping them in sync is manual. Make the generated artifact the artifact, and CI becomes the referee:

# every PR: regenerate from the spec, then confirm nothing changed
npx speccaster drift --spec openapi.yaml --out speccaster/contract.test.js
# exit code 0  →  suite is in sync with the spec
# exit code 1  →  build fails, PR blocked, diff is visible

# then actually run the contract tests against a live server
SPECCASTER_BASE_URL=https://api.example.com/v1 \
  node --test speccaster/contract.test.js

Pattern 1 and 3 now fail the build on the first PR that touches the spec. Pattern 2 is the human part — but now the generated tests are plain, auditable node:test files, so a "relaxed assertion" diff is visible in every code review instead of hiding in a framework.

What the generated suite covers

For every path and operation, SpecCaster emits a test that calls the endpoint with sample payloads derived from your request schemas and asserts the response status and content-type match the spec. You extend the file with your own deeper assertions — it's your test, committed to your repo.

OpenAPI 3.0 and 3.1, JSON or YAML, Node 18+. No server, no credentials, no SaaS dashboard — the CLI makes zero network calls. Free, MIT, not crippled.

npx speccaster demo