What is Specmatic?

If you keep an OpenAPI file but your running service slowly drifts away from it, Specmatic is built for exactly that gap. It treats your spec as an executable contract, then tests a real service against it and runs the same spec as a smart stub. This guide explains what Specmatic does, how contract testing differs from example-based testing, and where the tool fits, with a note on how it compares to a broader platform approach like Apidog’s API contract testing. For the spec format underneath it all, the OpenAPI Specification is the source of truth Specmatic reads from.

What Specmatic is

Specmatic is an open-source tool for contract-driven development. The core idea is short: your API specification is the contract, and Specmatic makes that contract executable. Point it at an OpenAPI file and it can do two complementary jobs.

• Run the spec as tests against a live service, checking that the service honors every path, status code, and schema the spec promises.
• Run the spec as a stub server, so consumers can develop against a mock that responds exactly as the contract says.

Both jobs read the same file. There’s no separate “test definition” and “spec” to keep in sync, which is the whole point. Specmatic also reaches beyond OpenAPI. Version 2.0 added GraphQL and gRPC, and it supports AsyncAPI for Kafka-style event contracts, plus formats like WSDL and Avro. For most teams, though, the entry point is a plain OpenAPI YAML or JSON file.

You run it from the command line or a Docker image, so it drops into CI without much ceremony. The company behind it offers commercial add-ons, but the contract engine itself is free and open source.

Contract testing vs example testing

This is the distinction that confuses most people, so it’s worth being precise.

Example-based testing is what you do in most API clients. You write a request, you assert on the response you got back, maybe you check a status code and a field or two. Each test is a hand-written example. If your spec has 40 endpoints, you write and maintain a lot of examples, and gaps are easy to miss.

Contract testing flips the model. Instead of asserting on specific examples, you assert that the service matches the contract. Specmatic reads the schema and generates tests from it. It checks that responses conform to the declared types, that required fields are present, that status codes line up, and that the service rejects malformed requests the way the spec implies. You don’t write the assertions one by one. The spec is the assertion.

There’s a second axis worth naming. Contract testing comes in flavors, and Specmatic sits in a specific one. Pact-style consumer-driven contract testing has consumers publish their expectations to a broker, and providers verify against those. Specmatic does contract-driven testing instead: the spec is the single contract that both sides agree to, and Specmatic validates the provider against it and stubs the provider for consumers. It’s not a Pact broker, and it doesn’t manage consumer-published pacts. If you want the broader picture, see this overview of API contract testing and mocking tools.

How Specmatic runs

You can install the CLI directly or pull the Docker image. Docker is the common choice in CI because it avoids local runtime setup.

Running contract tests

The test command points Specmatic at a spec and a running service. A minimal local run looks like this.

# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080

# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080

Specmatic reads api.yaml, generates requests for the operations it describes, sends them to the base URL, and validates every response against the schema. A failing test means the service and the contract disagree. You fix one or the other. That’s the loop.

Running the spec as a stub

The stub server is the other half. Start it and Specmatic serves responses that match the contract, so a front-end or a downstream service can build against it before the real backend exists.

specmatic stub api.yaml --port=9000

By default it generates schema-valid responses on the fly. You can also save concrete examples in an _examples directory next to the spec, and the stub will return those when a request matches. This gives you realistic, controllable data without standing up a real backend. If you’re comparing stub-and-mock options across tools, the roundup of contract testing and mock servers puts Specmatic in context.

Specmatic can also help you create the spec in the first place. It can sit as a proxy in front of an existing service, capture real traffic, and generate an OpenAPI document plus example files from what it sees. That’s handy when you have a service but no spec yet.

The spec-as-contract and stub model

Here’s why running one file as both test and stub matters. When the spec is the contract, the test side and the stub side can never disagree, because they read the same document.

• The provider team runs specmatic test in CI. If they change the API without updating the spec, the contract tests fail.
• The consumer team runs specmatic stub locally. They develop against responses that are guaranteed to match the same contract.

So the spec becomes a live agreement, not a stale document that nobody trusts. This is the difference between a stub and a richer mock, and it’s worth understanding the underlying ideas in API stubbing vs mocking before you design a workflow around it.

Specmatic also adds backward-compatibility checking. The backward-compatibility-check command starts a stub from the new version of a spec, generates tests from the previous version, and runs them against the new stub. If something that used to work no longer does, you find out before you ship. That’s a strong guardrail for microservices that deploy independently, and it’s a flavor of the broader idea covered in bidirectional contract testing.

Where Specmatic fits

Specmatic earns its place when these things are true for your team:

• Your OpenAPI (or AsyncAPI, GraphQL, gRPC) spec is real and reasonably complete.
• You have separate provider and consumer teams or services that need to stay in sync.
• You want spec drift to fail a build automatically, not get caught in review.
• You’re comfortable with a CLI- and CI-first workflow.

It’s less of a fit if you don’t keep a spec, if you want a visual workspace for designing and exploring APIs, or if you want one tool to also handle ad-hoc debugging, documentation, and team collaboration. Specmatic is focused on the contract engine, and it does that one job well.

That focus is also where a platform like Apidog takes a different shape. Apidog is schema-driven the same way: it reads your OpenAPI spec, validates responses against the schema, and spins up a mock server from your OpenAPI schema without code. The honest difference is scope. Specmatic is a sharp, CLI-native contract tool. Apidog wraps design, testing, mocking, and docs into one workspace with a visual editor, so the spec, the tests, and the mock live together and stay in sync as you work. Apidog is not a Pact-style consumer-driven contract broker either, so if your team specifically needs a pact broker, neither tool is that.

If you want to generate runnable tests straight from a spec inside that kind of workspace, see how Apidog handles API test collection generation from OpenAPI specs.

Frequently asked questions

Is Specmatic free?

Yes. The core contract engine is open source and free to use from the CLI or Docker. There are commercial offerings around it, but you can run contract tests and stub servers from OpenAPI specs without paying. Check the official site and GitHub for current details on the paid tiers.

Does Specmatic only work with OpenAPI?

No. OpenAPI is the most common entry point, but Specmatic also supports AsyncAPI for event-driven contracts, plus GraphQL and gRPC since version 2.0, along with formats like WSDL and Avro. The model is the same across all of them: the spec is the executable contract. If you’re new to the format itself, start with this OpenAPI Specification tutorial.

Is Specmatic the same as Pact?

Not quite. Pact is consumer-driven: consumers publish expectations to a broker and providers verify against them. Specmatic is contract-driven: the spec is the single shared contract, and Specmatic validates the provider against it while stubbing the provider for consumers. Both reduce integration surprises, but they organize the contract differently.

Can Specmatic generate an OpenAPI spec for me?

Yes. Specmatic can run as a proxy in front of an existing service, capture real request and response traffic, and generate an OpenAPI document plus example files from it. That’s useful when you have a working service but no formal spec to test against yet.

Conclusion

Specmatic answers a specific, real problem: keeping a running service honest against the OpenAPI spec it’s supposed to follow. By making the spec executable, it gives you contract tests and a matching stub from one file, with backward-compatibility checks on top. If you live in the terminal and CI and you keep a solid spec, it’s a clean fit.

If you’d rather have the contract, the tests, the mock, and the docs in one visual workspace that reads the same OpenAPI file, try Apidog. It validates responses against your schema, mocks endpoints with no code, and turns specs into runnable test collections. Download Apidog to point it at your spec and see the full design-to-test loop in one place.