testutil

Documentation

Overview

Package testutil provides test helpers for MCP servers built with mcpkit.

Index

• func ForAllTransports(t *testing.T, srv *server.Server, fn func(t *testing.T, c *client.Client))
• func InitHandshake(d interface{ ... })
• func NewTestServer() *server.Server
• func PromptGetRequest(name string, args map[string]string) *core.Request
• func ResourceReadRequest(uri string) *core.Request
• func ToolCallRequest(name string, args map[string]any) *core.Request
• type TestClient
  • func NewTestClient(t *testing.T, srv *server.Server, opts ...client.ClientOption) *TestClient
  • func (tc *TestClient) Call(method string, params any) *client.CallResult
  • func (tc *TestClient) ListResourceTemplates() []core.ResourceTemplate
  • func (tc *TestClient) ListResources() []core.ResourceDef
  • func (tc *TestClient) ListTools() []core.ToolDef
  • func (tc *TestClient) ReadResource(uri string) string
  • func (tc *TestClient) SubscribeResource(uri string)
  • func (tc *TestClient) ToolCall(name string, args any) string
  • func (tc *TestClient) UnsubscribeResource(uri string)

Functions

func ForAllTransports

func ForAllTransports(t *testing.T, srv *server.Server, fn func(t *testing.T, c *client.Client))

ForAllTransports runs fn as a subtest against all 4 MCP transport types: Streamable HTTP, SSE, in-process memory, and stdio. Each subtest creates its own server instance, connected client, and cleanup handlers.

Use this for any test that should be transport-agnostic — the test logic runs identically regardless of the underlying transport.

The server parameter is used as a template: ForAllTransports creates a fresh server for each transport by calling NewTestServer(). If you need the exact server instance passed in (e.g., with custom tools), note that Streamable HTTP and SSE subtests create httptest.Servers from it directly, while memory and stdio create fresh copies via NewTestServer() to avoid shared state.

Example:

func TestEcho(t *testing.T) {
    testutil.ForAllTransports(t, testutil.NewTestServer(), func(t *testing.T, c *client.Client) {
        text, err := c.ToolCall("echo", map[string]any{"message": "hi"})
        if err != nil { t.Fatal(err) }
        assert.Equal(t, "echo: hi", text)
    })
}

func InitHandshake

func InitHandshake(d interface {
	Dispatch(context.Context, *core.Request) *core.Response
})

InitHandshake performs the MCP initialize + notifications/initialized handshake on any type that implements the Dispatch method (both server.Server and server.Dispatcher satisfy this).

This is required before the server will accept tool/resource requests. For client-based tests, prefer NewTestClient which handles the handshake automatically via client.Connect().

Example:

srv := server.NewServer(info)
srv.RegisterTool(...)
testutil.InitHandshake(srv)
resp := srv.Dispatch(ctx, toolCallRequest)

func NewTestServer

func NewTestServer() *server.Server

NewTestServer creates an MCP server pre-registered with standard test fixtures for use across unit and integration tests.

Standard fixtures:

• Tool "echo": echoes input message → "echo: <message>"
• Tool "fail": always returns an error result ("intentional failure")
• Resource "test://info": static text → "hello from test"
• ResourceTemplate "test://items/{id}": parameterized → "item <id>"

Additional tools, resources, or prompts can be registered on the returned server before passing it to NewTestClient or ForAllTransports.

Example:

srv := testutil.NewTestServer()
srv.RegisterTool(myCustomTool, myHandler) // add test-specific tools
tc := testutil.NewTestClient(t, srv)
result := tc.ToolCall("echo", map[string]any{"message": "hi"})

func PromptGetRequest

func PromptGetRequest(name string, args map[string]string) *core.Request

PromptGetRequest builds a JSON-RPC prompts/get request for direct dispatch testing.

func ResourceReadRequest

func ResourceReadRequest(uri string) *core.Request

ResourceReadRequest builds a JSON-RPC resources/read request for direct dispatch testing.

func ToolCallRequest

func ToolCallRequest(name string, args map[string]any) *core.Request

ToolCallRequest builds a JSON-RPC tools/call request for direct dispatch testing.

Types

type TestClient

type TestClient struct {
	*client.Client

	Server *httptest.Server
	// contains filtered or unexported fields
}

TestClient wraps a client.Client with testing.T error handling and an in-process httptest.Server. Methods call t.Fatal on errors.

func NewTestClient

func NewTestClient(t *testing.T, srv *server.Server, opts ...client.ClientOption) *TestClient

NewTestClient creates a TestClient from a server.Server. It starts an httptest.Server (Streamable HTTP), performs the MCP initialize handshake, and registers cleanup. Optional ClientOption values (e.g., client.WithClientBearerToken) are passed to the client.

For a server with standard test fixtures, use NewTestServer:

tc := testutil.NewTestClient(t, testutil.NewTestServer())

func (*TestClient) Call

func (tc *TestClient) Call(method string, params any) *client.CallResult

Call makes a raw JSON-RPC call. Calls t.Fatal on error.

func (*TestClient) ListResourceTemplates

func (tc *TestClient) ListResourceTemplates() []core.ResourceTemplate

ListResourceTemplates returns all registered resource templates. Calls t.Fatal on error.

func (*TestClient) ListResources

func (tc *TestClient) ListResources() []core.ResourceDef

ListResources returns all registered static resources. Calls t.Fatal on error.

func (*TestClient) ListTools

func (tc *TestClient) ListTools() []core.ToolDef

ListTools returns all registered tools. Calls t.Fatal on error.

func (*TestClient) ReadResource

func (tc *TestClient) ReadResource(uri string) string

ReadResource reads a resource URI and returns the text content. Calls t.Fatal on error.

func (*TestClient) SubscribeResource

func (tc *TestClient) SubscribeResource(uri string)

SubscribeResource subscribes to change notifications for a resource URI. Calls t.Fatal on error.

func (*TestClient) ToolCall

func (tc *TestClient) ToolCall(name string, args any) string

ToolCall invokes a tool and returns the first text content. Calls t.Fatal on error.

func (*TestClient) UnsubscribeResource

func (tc *TestClient) UnsubscribeResource(uri string)

UnsubscribeResource removes a subscription for a resource URI. Calls t.Fatal on error.