SpecProof: Your OpenAPI spec, cross-checked against your tests

How it works

Three steps, one committed JSON report.

Read

Finds your OpenAPI spec, scans your tests. No configuration.

Compare

Matches every documented response to the assertions that check it.

Guard

The report is one committed file.
CI fails when it goes stale.

What it works with

Two things your repo already has. Nothing to annotate, no plugin, no runner integration.

Your OpenAPI spec

SpecProof reads every operation, along with every response status.

OpenAPI 3.x and Swagger 2.0: SpecProof finds and uses the shallowest openapi* or swagger* file in the repo.
Pass --spec when yours lives somewhere unusual.
JSON or YAML: Either format works, read exactly as it sits on disk.
Both produce the same proof, so converting between them never reads as drift.

Your tests

SpecProof reads the operations it exercises, along with the statuses it asserts.

TypeScript and JavaScript: SpecProof reads .test.ts, .test.tsx, .test.js, and .test.jsx files.
They can live anywhere in the repo.
Vitest, Jest, Bun test: Any runner that uses describe / it and expect is supported.
The HTTP client makes no difference, since SpecProof reads the assertion rather than the request.

Where the two meet

In a file like tests/tasks.test.ts, two lines do the work.

The describe title that names the operation.
The status the test asserts.

Both are matched back to the spec.

describe("POST /tasks", () => {           // the operation
  it("creates a task", async () => {
    expect(res.status).toBe(201);         // the response it proves
  });
});

Get started

Install as a dev dependency and run it from your repo.

Install

$ bun add -d specproof

$ npm install -D specproof

$ pnpm add -D specproof

$ yarn add -D specproof

Run

$ bunx specproof dev

$ npx specproof dev

$ pnpm exec specproof dev

$ yarn specproof dev

Serves the report at localhost:3001. Pass --port to host it somewhere else.

On CI

Add .github/workflows/specproof.yml and commit the report next to your code.

name: specproof
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install
      - run: npx specproof generate --out specproof.json --check

Prove your spec

One dev dependency, no configuration.

$ npm install -D specproof

View on GitHub ↗ View on npm ↗

Your OpenAPI spec,
cross-checked against your tests.

Auth

Tasks

Projects