Repository navigation
JOONS MCP Contract Test Runner 0.1.0 Preview
Pre-releaseJOONS MCP Contract Test Runner 0.1.0 is the first Preview release.
Define, execute, and validate behavioral contracts for MCP tools. Write a JSON test suite, and the runner starts a JOONS MCP Mock Server from your snapshot and fixtures, calls the tools through the official MCP SDK client, and checks every result against your expectations.
Safety: 0.1.0 runs only against a JOONS MCP Mock Server. The runner starts it itself (argv only, fresh empty working directory, minimal environment) and checks that the server identifies as a JOONS MCP Mock Server before any tool call; otherwise it calls nothing. Real-server execution is planned for a later version with explicit opt-in and an exact per-tool allowlist.
Highlights
- Strictly validated JSON suites: unknown keys, duplicate ids and invalid references are errors.
- Assertions: outcome, isError, text (equals/contains/startsWith), contentCount, structuredContent (equals or subset match), fields (exists, equals, captured value, type, length bounds), maxDurationMs, errorCode, errorMessageContains. A missing input never passes.
- Captures pass values from a passing test to later tests explicitly; tests are otherwise independent.
- Per-test and total time limits, concurrency for independent tests, deterministic
--stablereports. - Terminal, JSON and Markdown reports with CI exit codes; captured values and secret-looking keys are redacted.
Requires the Mock Server: npm install -g github:dbdefault/joons-mcp-mock-server#v0.1.0
Install: npm install -g github:dbdefault/joons-mcp-contract-runner#v0.1.0
Formats may change before 1.0. Not published to npm.