acctest

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: GPL-3.0 Imports: 10 Imported by: 1

Documentation

Overview

Package acctest drives an MCP server the way a client does, for a suite against a live one: calls counted for coverage, readers for the answers, waits on background work, put-backs for what a test changed, and a watch on everything the tools say for a key the suite gave the server. What a suite needs of the server itself, its environment and proxy, is in test/env.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BoolOf

func BoolOf(v any) bool

BoolOf pulls a JSON boolean out of a decoded field, false when it was omitted.

func Decimal

func Decimal(t *testing.T, v any, field string) float64

Decimal reads a number with a fraction, where rounding would pass a check that should fail.

func DecimalOr0 added in v0.6.0

func DecimalOr0(v any) float64

DecimalOr0 reads a number with a fraction, 0 when omitted; NumOr0 would read 1.5 as 1.

func Eventually

func Eventually(check func() bool) bool

Eventually reports whether check comes true within about twenty seconds.

func EventuallyWithin

func EventuallyWithin(patience time.Duration, check func() bool) bool

EventuallyWithin is Eventually with its own patience, for work queued behind a server's other work.

func Holds

func Holds(check func() bool) bool

Holds reports whether check stays true for a few seconds, long enough for a background refresh that would undo something to show.

func IsBool

func IsBool(v any, want bool) bool

IsBool says whether a decoded field is this boolean; an omitted field is neither.

func Num

func Num(t *testing.T, v any, field string) int

Num pulls a JSON number out of a decoded field.

func NumOr0

func NumOr0(v any) int

NumOr0 pulls a JSON number out of a decoded field, 0 when it was omitted.

func Object

func Object(t *testing.T, v any, field string) map[string]any

Object reads a nested object.

func OrEmptyList

func OrEmptyList(v any) any

OrEmptyList is a JSON list, or an empty one when the field is absent.

func Reversed

func Reversed(s []string) []string

Reversed is a copy of the strings, back to front.

func Rows

func Rows(t *testing.T, v any, field string) []map[string]any

Rows pulls a list of objects out of a decoded JSON field.

func RowsOf

func RowsOf(v any) []map[string]any

RowsOf is the objects in a decoded list, a missing field or a non-object entry tolerated.

func RowsOfAny

func RowsOfAny(v any) []any

RowsOfAny is a decoded list as it is, nil for a field that is no list.

func Sorted

func Sorted(s []string) []string

Sorted is a copy of the strings, sorted.

func SortedKeys

func SortedKeys(m map[string]int) []string

SortedKeys are a map's keys, sorted.

func Str

func Str(v any) string

Str pulls a string out of a decoded field, "" when absent.

func Strs

func Strs(t *testing.T, v any, field string) []string

Strs pulls a []string out of a decoded JSON field.

func Texts

func Texts(v any) []string

Texts is the strings in a decoded list, "" for anything else in it, nothing for a field that is no list.

func WholeRun

func WholeRun() bool

WholeRun reports whether every test was asked for: under -run or -skip an uncalled tool says nothing about coverage.

func WithoutName

func WithoutName(names []string, name string) []string

WithoutName is a copy of the names with one taken out, once.

Types

type Calls

type Calls struct {
	Answered, Failed int
}

Calls is how a tool's calls went: answered, or failed.

type Suite

type Suite struct {
	// Ctx is the run's context, not a test's, which is cancelled before the clean-ups that put things back run
	Ctx     context.Context //nolint:containedctx // the run's own context, which every call the suite makes is under
	Session *mcp.ClientSession
	// Ready says the server is there; a test that calls when it is not skips, saying NotReady
	Ready    bool
	NotReady string
	// CannotAnswer are the tools a throwaway server cannot answer, and why, so a failed call is all a test can make of them
	CannotAnswer map[string]string
	// contains filtered or unexported fields
}

Suite is one client session to the server under test, and the record of what it was asked.

func Connect

func Connect(ctx context.Context, server *mcp.Server) (*Suite, error)

Connect serves the server in this process and returns a suite with a client session to it, so the tools are driven as a client drives them.

func (*Suite) Call

func (s *Suite) Call(t *testing.T, name string, args map[string]any) map[string]any

Call invokes a tool, skipping the test when the server is not there and failing it on an error.

func (*Suite) CallErr

func (s *Suite) CallErr(t *testing.T, name string, args map[string]any) string

CallErr invokes a tool expecting it to fail, and returns the error message.

func (*Suite) Calls

func (s *Suite) Calls(name string) Calls

Calls is how a tool's calls have gone so far.

func (*Suite) CoverageReport

func (s *Suite) CoverageReport() (string, error)

CoverageReport is Uncovered as TestMain prints it: "" when every tool answered, else the tools never called and those that only failed. Only a whole run can say a tool was never called (WholeRun).

func (*Suite) DeleteLaterIfThere

func (s *Suite) DeleteLaterIfThere(t *testing.T, tool string, args map[string]any, gone string)

DeleteLaterIfThere deletes what a test made once it ends, unless the test already did: an answer containing gone ("no collection named") is fine, any other failure is reported.

func (*Suite) Invoke

func (s *Suite) Invoke(name string, args map[string]any) (map[string]any, error)

Invoke calls a tool and returns its structured answer. Every call comes through here, so this is where coverage is counted (Uncovered).

func (*Suite) LeakReport added in v0.6.2

func (s *Suite) LeakReport() string

LeakReport is what TestMain prints of the secrets given (Secret): "" when none was shown, else each place one was, with the tool and where in its words, the secret itself left out. It holds for a filtered run too. A suite that called tools and was given no secret reports that rather than "", since that is what a secret given to a stand-in looks like.

func (*Suite) PutBack

func (s *Suite) PutBack(t *testing.T, tool string, args map[string]any)

PutBack calls a tool once the test ends to undo what it changed, and reports one that never succeeds.

func (*Suite) Retried

func (s *Suite) Retried(tool string, args map[string]any) error

Retried calls a tool until it succeeds, for about a minute: a server can refuse a write while its own work holds the record. It returns the last error.

func (*Suite) Secret added in v0.6.2

func (s *Suite) Secret(secret string) string

Secret has everything a tool says from now on read for a key, and hands the key back, so a test wraps a key where it gives it to the server: "apiKey": suite.Secret(key). A server hands a key back where nobody thinks to test, so every call is read and LeakReport says what was shown. An empty secret is reported, not ignored. Give secrets to the suite Connect returned, not to a stand-in made before it.

func (*Suite) ToolNames

func (s *Suite) ToolNames(t *testing.T) []string

ToolNames lists every tool the server registered, so a test can hold a family complete.

func (*Suite) Uncovered

func (s *Suite) Uncovered() (never, onlyFailed []string, err error)

Uncovered names the tools no test saw answer: never called, or only ever failed. A tool only refused proves it checks its input, not that it works, so a new tool without a test fails the suite. Those in CannotAnswer still need a call.

func (*Suite) Undo

func (s *Suite) Undo(t *testing.T, tool string, args map[string]any)

Undo is PutBack for a call made in a clean-up already under way.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL