Test fixtures¶
Transport, inspect, diff, scenario, and watch tests reuse these fixtures instead of inventing ad hoc servers.
The laboratory lives in internal/testkit. Production packages (internal/app,
internal/cli, adapters) must not import it. The package does not import
github.com/modelcontextprotocol/go-sdk; that import stays in
internal/protocol.
Protocol eras and transports follow Compatibility.
Named fixtures¶
Look up a descriptor by catalog name. An unknown name is an error, not a silent default.
| Name | Era | Transport | What it exercises |
|---|---|---|---|
legacy-stdio |
2025-11-25 |
stdio | initialize, initialized, tools, prompts, resources, templates |
legacy-http |
2025-11-25 |
HTTP | Session id, MCP-Protocol-Version, same primitives |
legacy-paginate |
2025-11-25 |
stdio | nextCursor on tools/list |
legacy-notify |
2025-11-25 |
stdio | notifications/tools/list_changed after initialized |
modern-stdio |
2026-07-28 |
stdio | server/discover, per-request _meta, listings; initialize is -32601 |
modern-http |
2026-07-28 |
HTTP | Standard headers, GET/DELETE 405, HeaderMismatch |
modern-sse |
2026-07-28 |
HTTP | Request-scoped SSE on tools/call when Accept includes text/event-stream |
modern-auth |
2026-07-28 |
HTTP | Authorization: Bearer fixture-token |
modern-need-cap |
2026-07-28 |
stdio | server/discover returns -32021 MissingRequiredClientCapabilityError |
modern-version-retry |
2026-07-28 |
stdio | First server/discover returns -32022 with supported: ["2026-07-28"]; the next discover succeeds |
delay-stdio |
2025-11-25 |
stdio | Intentional delay before each RPC (cancellation tests) |
malformed-stdio |
2025-11-25 |
stdio | Non-JSON reply to the first RPC |
malformed-http |
2026-07-28 |
HTTP | 400 with an empty body |
unrecognized-http |
2025-11-25 |
HTTP | 400 with an unrecognized JSON-RPC error |
legacy-unsupported |
2025-11-25 |
stdio | initialize returns protocolVersion 1999-01-01 |
legacy-bad-caps |
2025-11-25 |
stdio | initialize returns capabilities as an array |
legacy-exit |
2025-11-25 |
stdio | Closes the stream after the first RPC |
Stable inventory (every well-formed catalog that advertises primitives):
- Tools:
echo,fail(isError: true). Pagination fixtures addextra-00… - Prompt:
greetwith required argumentname - Resources:
fixture://stable/note(text bodystable-note) andfixture://stable/blob(binary,application/octet-stream) - Template:
fixture://items/{id}
In-process stdio¶
d, err := testkit.Named("legacy-stdio")
if err != nil {
t.Fatal(err)
}
lab, err := testkit.StartStdio(d)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = lab.Close() })
StartStdio uses io.Pipe. Protocol JSON-RPC is newline-delimited on the
client's write/read ends. Diagnostics that would be child stderr are captured
in lab.Stderr. Close cancels the serve loop and waits for it; tests must
not time.Sleep for shutdown. Prefer testing/synctest for delay and
cancellation.
Subprocess stdio¶
testdata/servers/stdio-lab is a tiny main that calls testkit.RunStdio.
Set MCPDEV_FIXTURE to a catalog name (default legacy-stdio).
lab := testkit.StartProcess(t, "legacy-stdio")
The helper builds the binary into a temp dir, starts it, and registers cleanup. Stdout is only JSON-RPC. Stderr is a bounded buffer of fixture logs. Never treat stderr as protocol.
HTTP¶
lab := testkit.StartHTTP(t, d)
StartHTTP uses httptest.NewServer on loopback and registers Server.Close on the test.
testdata/servers/http-lab is the subprocess counterpart (MCPDEV_FIXTURE, URL written to ready.url in the process working directory). Official requirement-set scoring uses that helper; see Official MCP conformance.
StartHTTPS is the same with httptest.NewTLSServer (use lab.Server.Client() when the test must trust the fixture cert).
The server binds the fixture's era:
2025-11-25: optionalMcp-Session-Idafterinitialize; GET may hold an SSE stream withidfields.DropGETOncecloses the first GET after one event so reconnect tests can sendLast-Event-ID. DELETE tears the session down; later POST/GET/DELETE are404.2026-07-28: POST only; every request needs_metaplusMCP-Protocol-VersionandMcp-Method.tools/call,prompts/get, andresources/readalso needMcp-Name(Base64 sentinel when the value is not header-safe ASCII). Header/body version or name mismatch is-32020/ HTTP400. JSON-RPC notifications (noid) return202with an empty body. GET/DELETE are405.
Auth, empty-body, and unrecognized-error fixtures keep those defects explicit.
Callers must not treat an empty 400 as a successful catalog.
Add a fixture¶
- Add a
Descriptorto the catalog map ininternal/testkit/catalog.go. - Reuse
Capabilities,Delay,Malformed,Session,PageSize, andShutdowninstead of forking a new handler when a flag is enough. - If you need new RPC behavior, add a small handler file; do not grow a single kitchen-sink file past the architecture size guardrail.
- Add a focused
*_test.gothat proves the new path (including shutdown). - Document the name in the table above in the same change.
Commands¶
go test ./internal/testkit
xdrun matrix
xdrun ci
xdrun conformance
xdrun matrix is the OS-portable process, transport, and watch set also run on Ubuntu, macOS, and Windows in GitHub Actions. It must not skip those packages per GOOS. Full xdrun ci stays Ubuntu-oriented (Unix gofmt check, docs, security). Release archives and go install are documented in Installation.