Project XML or extracted service directories.
ReadyAPI mock drift detection
Stop shipping false-green tests.
MockDoctor compares ReadyAPI REST virtual-service files with an OpenAPI spec or a JSON contract and shows exactly where the mock drift starts. It catches stale operations, wrong status codes, content-type drift, invalid JSON, and schema mismatches before that fake green build buys you a real outage.
Dereferenced OpenAPI or repo-friendly contract JSON.
Shareable drift artifacts without custom glue code.
Drift example from the repo
$ mockdoctor compare \
--readyapi ./orders-project-schema-drift.xml \
--openapi ./orders-openapi.yaml
MockDoctor
ReadyAPI: ./orders-project-schema-drift.xml
Contract: ./orders-openapi.yaml (openapi)
Services checked: 1
Operations checked: 3
Responses checked: 4
Issues found: 1
GET /api/orders/{id} | service=OrdersService
- [response-body-schema-mismatch]
ReadyAPI response OK Response does not match the contract schema.
$.amount: must be integerTry it
Start with a real command, then go deeper if you need to.
If you want to see MockDoctor work, run the checked-in example first. If you want more context before installing anything, jump to the release notes or the configuration docs.
Run locally
Use the checked-in example.
npm install
npm run build
node ./dist/cli.js compare --config ./examples/openapi/mockdoctor.config.jsonThis is the shortest repo-local path that works today. No npm publish step required.
Read more
Choose the next stop.
The problem
Your mocks keep passing after reality changed.
Teams commit mock services because they make UI, QA, and contract work faster. Then the API changes, the mock does not, and the test suite stays green for the wrong reasons. MockDoctor exists to catch that drift in the committed files before anyone trusts the result.
False confidence
The API drops or renames a field, but the mock still returns the old shape. Tests pass against a response that production never sends anymore.
Slow review cycles
Reviewers can spot code changes. They usually cannot spot that a `restMockAction` or a stored response body quietly drifted away from the current contract.
Hidden fixture debt
Schema mismatches, invalid JSON, and stale content types pile up over time until a later change breaks the wrong layer and nobody trusts the failure.
What it checks
File-to-contract comparison with useful failure modes.
MockDoctor normalizes both sides to the same operation model, then compares what matters in practice: paths, response codes, content types, and JSON body shape.
ReadyAPI contains an operation that is not in the contract.
The contract expects an operation that the mock service does not expose.
ReadyAPI returns a status code that the contract does not describe.
The contract defines a concrete status code the mock does not provide.
The response shape might be fine, but the declared media type is wrong.
The JSON body parses, but it no longer matches the contract schema.
Interactive demo
Flip between real drift cases.
These are the same categories covered by the checked-in fixtures in the repository. The presentation swaps the example so you can explain the tool without screen-sharing a terminal.
Most common catch
The body parses, but the types drifted.
The contract says `amount` is an integer. The ReadyAPI response still returns it as a string. That is the kind of bug that creates a false-green UI test fast.
- Compares `GET /api/orders/{id}` by normalized method and path.
- Loads the OpenAPI schema for the `200` response.
- Validates the stored mock body with Ajv and reports the failing path.
MockDoctor output
How it works
A small pipeline with one job: prove the mock still matches the contract.
The code stays readable because parsing, normalization, comparison, and reporting live in separate modules. That also keeps the site honest: it is presenting the actual pipeline, not a marketing sketch.
Load ReadyAPI files
Read a project XML file or an extracted REST service directory. Pull out services, operations, responses, media types, and JSON bodies when present.
Load the contract
Dereference OpenAPI or read a JSON contract. Normalize each operation to `METHOD + path` and preserve source paths for reporting.
Compare responses
Match status codes, wildcard statuses, content types, and JSON schemas. Record mismatch codes that are stable enough for CI and human review.
Render the result
Print a text or JSON summary to stdout and optionally write an HTML drift report when issues are found.
Current scope
Focused on one job: compare committed mocks to committed contracts.
- ReadyAPI REST project XML and extracted service directories
- OpenAPI and repo-friendly JSON contracts
- Text, JSON, and HTML output
- CI-friendly exit codes and checked-in smoke examples
Known limits
Small surface area, explicit tradeoffs.
- REST only in `v0.1.0`
- Non-JSON bodies are compared by status code and media type only
- No dispatch-script execution or runtime virtualization
- No extra route-template inference beyond normalized literal paths
Next step
See the release, try the repo, or inspect the docs.
MockDoctor is small on purpose. Start with the release if you want scope and version notes, open the repo if you want to run it, or inspect the docs if you want the details before installing anything.