testkit

Documentation

Overview

Package testkit provides testing utilities for ToolHive.

Its sole purpose is

• providing utilities to quickly spin-up an HTTP test server exposing either a Streamable-HTTP or (legacy) SSE MCP server
• providing utilities to ease the parsing of `text/event-stream` response bodies

The file `pkg/testkit/testkit_test.go` contains a few tests that exemplify how to use the framework. Ideally, it should allow the developer to add assertions in the test server as well, but for now it only allows configuring the returned JSON payloads.

Index

• Constants
• func NewSplitSSE(sep SSESep) bufio.SplitFunc
• type SSESep
• type TestMCPClient
  • func NewSSETestServer(options ...TestMCPServerOption) (*httptest.Server, TestMCPClient, error)
  • func NewStreamableTestServer(options ...TestMCPServerOption) (*httptest.Server, TestMCPClient, error)
• type TestMCPServer
• type TestMCPServerOption
  • func WithJSONClientType() TestMCPServerOption
  • func WithMiddlewares(middlewares ...func(http.Handler) http.Handler) TestMCPServerOption
  • func WithSSEClientType() TestMCPServerOption
  • func WithTool(name string, description string, handler func() string) TestMCPServerOption

Constants

const (
	// LFSep is the line feed separator for SSE responses.
	LFSep = iota
	// CRSep is the carriage return separator for SSE responses.
	CRSep
	// CRLFSep is the carriage return line feed separator for SSE responses.
	CRLFSep
)

Functions

func NewSplitSSE

func NewSplitSSE(sep SSESep) bufio.SplitFunc

NewSplitSSE is a function that can be used to create a new SSE split function. It's just a helper function to be used with bufio.Scanner.Split.

Types

type SSESep

type SSESep int

SSESep is a type that represents the separator for SSE responses.

type TestMCPClient

type TestMCPClient interface {
	// ToolsList returns the tools list response for the client.
	// Client implementations are expected to strip any non-JSON payloads
	// from the response, i.e. just return the JSON payload after a
	// `data:` prefix.
	ToolsList() ([]byte, error)
	// ToolsCall returns the tool call response for the client.
	// Client implementations are expected to strip any non-JSON payloads
	// from the response, i.e. just return the JSON payload after a
	// `data:` prefix.
	ToolsCall(name string) ([]byte, error)
}

TestMCPClient is the common interface that test MCP clients must implement. Client implementations are expected to abstract the underlying transport so that responses coming from the same TCP stream or from different ones are treated the same.

func NewSSETestServer

func NewSSETestServer(
	options ...TestMCPServerOption,
) (*httptest.Server, TestMCPClient, error)

NewSSETestServer creates a new SSE server, wraps it in an `httptest.Server`, and returns it.

func NewStreamableTestServer

func NewStreamableTestServer(
	options ...TestMCPServerOption,
) (*httptest.Server, TestMCPClient, error)

NewStreamableTestServer creates a new Streamable-HTTP server, wraps it in an `httptest.Server`, and returns it.

type TestMCPServer

type TestMCPServer interface {
	SetMiddlewares(middlewares ...func(http.Handler) http.Handler) error
	AddTool(tool tooldef) error
	SetClientType(clientType clientType) error
}

TestMCPServer is the common interface that test MCP servers must implement. This allows having a single set of options for all test MCP servers, regardless of the underlying implementation.

type TestMCPServerOption

type TestMCPServerOption func(TestMCPServer) error

TestMCPServerOption is a function that can be used to configure a test MCP server. It uses the TestMCPServer interface to configure the server.

func WithJSONClientType

func WithJSONClientType() TestMCPServerOption

WithJSONClientType configures the test MCP server to provide a client calling endpoints that return application/json responses.

func WithMiddlewares

func WithMiddlewares(middlewares ...func(http.Handler) http.Handler) TestMCPServerOption

WithMiddlewares is a function that can be used to configure a test MCP server with middlewares. The actual order of application of the middleware functions is determined by the server implementation, but is generally expected to be the same as the one provided.

func WithSSEClientType

func WithSSEClientType() TestMCPServerOption

WithSSEClientType configures the test MCP server to provide a client calling endpoints that return text/event-stream responses.

func WithTool

func WithTool(name string, description string, handler func() string) TestMCPServerOption

WithTool is a function that can be used to configure a test MCP server with a tool. The underlying implementation is expected to honor this and return the tool as part of the tools list response, as well as handle tool call requests using the given handler function.