Skip to content

JOONS MCP Contract Test Runner 0.1.0 Preview

Pre-release
Pre-release

Choose a tag to compare

@dbdefault dbdefault released this 12 Nov 13:48

JOONS 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 --stable reports.
  • 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.