testutils

package

v0.1.17 Latest Latest Go to latest Published: Jul 12, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/clems4ever/llmbox

Links

Open Source Insights

Documentation ¶

Overview ¶

Package testutils holds test doubles shared across the llmbox test suites. It depends only on the box- and tool-layer interfaces (internal/cluster, internal/sandbox, internal/mcpserver) and never on internal/server, so both the in-package server tests and the external e2e suite can import it without an import cycle.

Index ¶

func ConnectMCP(t testing.TB, backend api.Backend, name, version string) *mcp.ClientSession
type FakeBackend
type FakeHub
type FakeMgr
type GuestFixture
- func NewGuestFixture(t testing.TB) *GuestFixture
- func (f *GuestFixture) BoxEnv(t testing.TB) []string
- func (f *GuestFixture) Close()
type NoopStore

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func ConnectMCP ¶ added in v0.0.46

func ConnectMCP(t testing.TB, backend api.Backend, name, version string) *mcp.ClientSession

ConnectMCP builds an MCP server over backend and returns an in-memory-connected client session, so a test can drive the real MCP tools end to end. The session is closed automatically when the test finishes. Pass an api.Client as the backend to exercise the full stand-alone path (MCP tools → HTTP → server).

@arg t The test the session's lifetime is tied to. @arg backend The backend the MCP tools run against. @arg name The MCP server implementation name. @arg version The MCP server implementation version. @return *mcp.ClientSession A connected MCP client session, closed on test cleanup.

@testcase TestConnectMCP lists the registered tools over the returned session.

Types ¶

type FakeBackend ¶ added in v0.0.46

type FakeBackend struct {

	// Canned results.
	CreateSess        api.BoxSession
	CreateErr         error
	Sessions          map[string]api.BoxSession // LookupByBoxID source, keyed by lowercased box ID
	Boxes             []api.BoxView
	ListErr           error
	Spokes            []api.SpokeStatus
	SpokesErr         error
	CreateSpokeResult api.SpokeEnrollment
	CreateSpokeErr    error
	DropSpokeErr      error
	SetDefaultErr     error
	JoinTokens        []api.JoinTokenInfo
	JoinTokensErr     error
	RevokeTokenErr    error
	RegenTokenResult  api.SpokeEnrollment
	RegenTokenErr     error
	DestroyErr        error
	PauseErr          error
	ResumeErr         error
	ExecResult        sandbox.ExecResult
	ExecErr           error
	ProxyOn           bool
	CreateProxyResult api.ProxyInfo
	CreateProxyErr    error
	Proxies           []api.ProxyInfo
	ListProxiesErr    error
	DeleteProxyErr    error

	// Recorded inputs.
	GotCreate         sandbox.CreateOptions
	GotLookup         string
	GotCreateSpoke    string
	GotCreateSpokeBk  string
	GotCreateSpokeTTL time.Duration
	GotDropSpoke      string
	GotDefaultSpoke   string
	GotRevokeToken    string
	GotRegenToken     string
	GotDestroyID      string
	GotPauseID        string
	GotResumeID       string
	GotExecID         string
	GotExecCmd        string
	GotProxyBoxID     string
	GotProxyPort      int
	GotProxyDesc      string
	GotDeleteBoxID    string
	GotDeletePort     int
	GotListBoxID      string
	// contains filtered or unexported fields
}

FakeBackend is a stand-in for the server's box-control backend: it records the calls it receives and returns canned results, satisfying api.Backend. Pair it with api.NewHandler (to serve the HTTP API) or ConnectMCP (to drive the MCP tools) without Docker, a store, or a cluster.

func (*FakeBackend) BoxExec ¶ added in v0.0.46

func (f *FakeBackend) BoxExec(ctx context.Context, boxID, command string) (sandbox.ExecResult, error)

BoxExec records the box ID and command and returns the canned result/error.

@arg ctx Context (unused by the fake). @arg boxID The box ID, recorded into GotExecID. @arg command The command, recorded into GotExecCmd. @return sandbox.ExecResult The canned ExecResult. @error error The canned ExecErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) CreateBox ¶ added in v0.0.46

func (f *FakeBackend) CreateBox(ctx context.Context, opts sandbox.CreateOptions) (api.BoxSession, error)

CreateBox records the options into GotCreate and returns the canned session/error.

@arg ctx Context (unused by the fake). @arg opts The create options, recorded into GotCreate. @return api.BoxSession The canned CreateSess. @error error The canned CreateErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) CreateProxy ¶ added in v0.0.46

func (f *FakeBackend) CreateProxy(ctx context.Context, boxID string, port int, description string) (api.ProxyInfo, error)

CreateProxy records the box ID, port, and description and returns the canned proxy/error.

@arg ctx Context (unused by the fake). @arg boxID The box ID, recorded into GotProxyBoxID. @arg port The port, recorded into GotProxyPort. @arg description The description, recorded into GotProxyDesc. @return api.ProxyInfo The canned CreateProxyResult. @error error The canned CreateProxyErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) CreateSpoke ¶ added in v0.0.47

func (f *FakeBackend) CreateSpoke(ctx context.Context, name, backend string, ttl time.Duration) (api.SpokeEnrollment, error)

CreateSpoke records the name/backend/ttl and returns the canned enrollment/error.

@arg ctx Context (unused by the fake). @arg name The spoke name, recorded into GotCreateSpoke. @arg backend The backend, recorded into GotCreateSpokeBk. @arg ttl The token TTL, recorded into GotCreateSpokeTTL. @return api.SpokeEnrollment The canned CreateSpokeResult. @error error The canned CreateSpokeErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) DeleteProxy ¶ added in v0.0.46

func (f *FakeBackend) DeleteProxy(ctx context.Context, boxID string, port int) error

DeleteProxy records the box ID and port and returns the canned DeleteProxyErr.

@arg ctx Context (unused by the fake). @arg boxID The box ID, recorded into GotDeleteBoxID. @arg port The port, recorded into GotDeletePort. @error error The canned DeleteProxyErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) DestroyBox ¶ added in v0.0.46

func (f *FakeBackend) DestroyBox(ctx context.Context, boxID string) error

DestroyBox records the box ID and returns the canned DestroyErr.

@arg ctx Context (unused by the fake). @arg boxID The box ID to destroy, recorded into GotDestroyID. @error error The canned DestroyErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) DropSpoke ¶ added in v0.0.47

func (f *FakeBackend) DropSpoke(ctx context.Context, name string) error

DropSpoke records the name and returns the canned DropSpokeErr.

@arg ctx Context (unused by the fake). @arg name The spoke name, recorded into GotDropSpoke. @error error The canned DropSpokeErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) ListBoxes ¶ added in v0.0.46

func (f *FakeBackend) ListBoxes(ctx context.Context) ([]api.BoxView, error)

ListBoxes returns the canned boxes/error.

@arg ctx Context (unused by the fake). @return []api.BoxView The canned Boxes slice. @error error The canned ListErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) ListJoinTokens ¶ added in v0.0.47

func (f *FakeBackend) ListJoinTokens(ctx context.Context) ([]api.JoinTokenInfo, error)

ListJoinTokens returns the canned join tokens/error.

@arg ctx Context (unused by the fake). @return []api.JoinTokenInfo The canned JoinTokens slice. @error error The canned JoinTokensErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) ListProxies ¶ added in v0.0.46

func (f *FakeBackend) ListProxies(ctx context.Context, boxID string) ([]api.ProxyInfo, error)

ListProxies records the box-ID filter and returns the canned proxies/error.

@arg ctx Context (unused by the fake). @arg boxID The box-ID filter, recorded into GotListBoxID. @return []api.ProxyInfo The canned Proxies slice. @error error The canned ListProxiesErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) LookupByBoxID ¶ added in v0.0.46

func (f *FakeBackend) LookupByBoxID(boxID string) (api.BoxSession, bool)

LookupByBoxID records the box ID and returns the canned session from Sessions (case-insensitive); ok is false when none matches.

@arg boxID The box ID to look up, recorded into GotLookup. @return api.BoxSession The matching canned session (zero value when absent). @return bool Whether a session with that box ID exists in Sessions.

@testcase TestFakeBackend checks LookupByBoxID resolves from Sessions and misses unknown IDs.

func (*FakeBackend) PauseBox ¶ added in v0.1.6

func (f *FakeBackend) PauseBox(ctx context.Context, boxID string) error

PauseBox records the box ID and returns the canned PauseErr.

@arg ctx Context (unused by the fake). @arg boxID The box ID to pause, recorded into GotPauseID. @error error The canned PauseErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) ProxyEnabled ¶ added in v0.0.46

func (f *FakeBackend) ProxyEnabled() bool

ProxyEnabled reports the canned ProxyOn.

@return bool The canned ProxyOn.

@testcase TestFakeBackend checks ProxyEnabled reports the canned flag.

func (*FakeBackend) RegenerateJoinToken ¶ added in v0.1.2

func (f *FakeBackend) RegenerateJoinToken(ctx context.Context, id string) (api.SpokeEnrollment, error)

RegenerateJoinToken records the id and returns the canned enrollment/error.

@arg ctx Context (unused by the fake). @arg id The token ID, recorded into GotRegenToken. @return api.SpokeEnrollment The canned RegenTokenResult. @error error The canned RegenTokenErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) ResumeBox ¶ added in v0.1.6

func (f *FakeBackend) ResumeBox(ctx context.Context, boxID string) error

ResumeBox records the box ID and returns the canned ResumeErr.

@arg ctx Context (unused by the fake). @arg boxID The box ID to resume, recorded into GotResumeID. @error error The canned ResumeErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) RevokeJoinToken ¶ added in v0.0.47

func (f *FakeBackend) RevokeJoinToken(ctx context.Context, id string) error

RevokeJoinToken records the id and returns the canned RevokeTokenErr.

@arg ctx Context (unused by the fake). @arg id The token ID, recorded into GotRevokeToken. @error error The canned RevokeTokenErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) SetDefaultSpoke ¶ added in v0.0.47

func (f *FakeBackend) SetDefaultSpoke(ctx context.Context, name string) error

SetDefaultSpoke records the name and returns the canned SetDefaultErr.

@arg ctx Context (unused by the fake). @arg name The spoke name, recorded into GotDefaultSpoke. @error error The canned SetDefaultErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

func (*FakeBackend) SpokeStatuses ¶ added in v0.0.46

func (f *FakeBackend) SpokeStatuses(ctx context.Context) ([]api.SpokeStatus, error)

SpokeStatuses returns the canned spokes/error.

@arg ctx Context (unused by the fake). @return []api.SpokeStatus The canned Spokes slice. @error error The canned SpokesErr, if any.

@testcase TestFakeBackend checks each method records its inputs and returns the canned results.

type FakeHub ¶

type FakeHub struct {
	Connected    map[string]cluster.BoxManager // spokes injected by tests, keyed by name
	Disconnected []string                      // names passed to Disconnect, for assertions
}

FakeHub is a stand-in for the server's spoke hub: tests inject connected spokes directly and assert which ones were disconnected.

func (*FakeHub) ConnectHandler ¶

func (h *FakeHub) ConnectHandler(w http.ResponseWriter, r *http.Request)

ConnectHandler is a no-op; tests inject spokes directly.

@arg w The response writer (unused). @arg r The request (unused).

@testcase TestFakeHub checks ConnectHandler is inert.

func (*FakeHub) Disconnect ¶

func (h *FakeHub) Disconnect(name string)

Disconnect records the name so tests can assert a spoke was kicked.

@arg name The spoke name, appended to Disconnected.

@testcase TestFakeHub checks Disconnect records the kicked spoke name.

func (*FakeHub) Spoke ¶

func (h *FakeHub) Spoke(name string) (cluster.BoxManager, bool)

Spoke returns the connected spoke with the given name.

@arg name The spoke name to look up. @return cluster.BoxManager The connected spoke's box manager, if present. @return bool True when a spoke with that name is connected.

@testcase TestFakeHub checks Spoke returns injected spokes and reports missing ones.

func (*FakeHub) Spokes ¶

func (h *FakeHub) Spokes() map[string]cluster.BoxManager

Spokes returns the connected spokes.

@return map[string]cluster.BoxManager The connected spokes keyed by name.

@testcase TestFakeHub checks Spokes returns the injected spokes.

type FakeMgr ¶

type FakeMgr struct {
	CreateID               string
	CreateErr              error
	CreateInitScriptFailed bool
	CreateInitScriptOutput string
	CreatePublishPorts     []sandbox.PublishPort

	ListResult []sandbox.Box

	Destroyed  []string
	DestroyErr error

	Paused    []string
	PauseErr  error
	Resumed   []string
	ResumeErr error

	ExecResult sandbox.ExecResult
	ExecErr    error
	GotExecID  string
	GotExecCmd []string

	GotOpts sandbox.CreateOptions
	// contains filtered or unexported fields
}

FakeMgr is a stand-in for *docker.Manager: it records the calls it receives and returns canned results, satisfying cluster.BoxManager.

func (*FakeMgr) Create ¶

func (f *FakeMgr) Create(ctx context.Context, opts sandbox.CreateOptions) (sandbox.CreateResult, error)

Create records the requested options and returns the canned result/error. On success it also records the box so it appears in List, modelling a real spoke; the canned CreateInitScriptFailed/Output model a spoke that kept a broken box.

@arg ctx Context (unused by the fake). @arg opts The create options, recorded into GotOpts. @return sandbox.CreateResult The canned create result (ID, URL, and any init-script failure). @error error The canned create error, if any.

@testcase TestFakeMgr checks each verb records its inputs and returns the canned results.

func (*FakeMgr) Destroy ¶

func (f *FakeMgr) Destroy(ctx context.Context, id string) error

Destroy records the destroyed ID and returns the canned DestroyErr (nil by default), letting a test simulate a spoke whose box is already gone.

@arg ctx Context (unused by the fake). @arg id The identifier to destroy, appended to Destroyed. @error error The canned DestroyErr, if any.

@testcase TestFakeMgr checks Destroy records the ID and surfaces the canned DestroyErr.

func (*FakeMgr) Exec ¶

func (f *FakeMgr) Exec(ctx context.Context, id string, cmd []string) (sandbox.ExecResult, error)

Exec records the requested box ID and command and returns the canned result/error.

@arg ctx Context (unused by the fake). @arg id The box identifier, recorded into GotExecID. @arg cmd The command, recorded into GotExecCmd. @return sandbox.ExecResult The canned ExecResult. @error error The canned exec error, if any.

@testcase TestFakeMgr checks each verb records its inputs and returns the canned results.

func (*FakeMgr) List ¶

func (f *FakeMgr) List(ctx context.Context) ([]sandbox.Box, error)

List returns the canned ListResult plus any boxes created (and not destroyed) through the fake, so box existence tracks Create/Destroy like a real spoke.

@arg ctx Context (unused by the fake). @return []sandbox.Box ListResult followed by the still-live created boxes. @error error Always nil.

@testcase TestFakeMgr checks each verb records its inputs and returns the canned results.

func (*FakeMgr) ListCalls ¶ added in v0.0.47

func (f *FakeMgr) ListCalls() int

ListCalls reports how many times List was called, so a test can assert a code path did (or did not) consult the spoke's live inventory.

@return int The number of List calls received so far.

@testcase TestFakeMgr checks each verb records its inputs and returns the canned results.

func (*FakeMgr) Pause ¶ added in v0.1.6

func (f *FakeMgr) Pause(ctx context.Context, id string) error

Pause records the paused ID and returns the canned PauseErr.

@arg ctx Context (unused by the fake). @arg id The identifier to pause, appended to Paused. @error error The canned PauseErr, if any.

@testcase TestFakeMgr checks Pause records the ID and surfaces the canned PauseErr.

func (*FakeMgr) Resume ¶ added in v0.1.6

func (f *FakeMgr) Resume(ctx context.Context, id string) error

Resume records the resumed ID and returns the canned ResumeErr.

@arg ctx Context (unused by the fake). @arg id The identifier to resume, appended to Resumed. @error error The canned ResumeErr, if any.

@testcase TestFakeMgr checks Resume records the ID and surfaces the canned error.

type GuestFixture ¶ added in v0.1.0

type GuestFixture struct {
	// Client is the host-side client connected to the guest's control socket.
	Client *guest.Client
	// SocketPath is the filesystem path of the guest's control socket.
	SocketPath string
	// contains filtered or unexported fields
}

GuestFixture is a running guest with a connected host-side client. It lets any package drive the box-control surface (Init, Exec, Dial) over a real Unix socket without a real backend. Use NewGuestFixture to build one; its teardown is registered on the test automatically.

func NewGuestFixture ¶ added in v0.1.0

func NewGuestFixture(t testing.TB) *GuestFixture

NewGuestFixture starts a guest serving a temporary Unix control socket and returns it with a connected client. The serve loop is drained via t.Cleanup, so callers need no manual teardown.

@arg t The test the fixture's lifetime and temp files are scoped to. @return *GuestFixture A running guest with a connected client.

@testcase TestGuestFixtureDrivesLifecycle drives a box through a fixture built here.

func (*GuestFixture) BoxEnv ¶ added in v0.1.0

func (f *GuestFixture) BoxEnv(t testing.TB) []string

BoxEnv returns an environment to pass in InitReq.Env that points HOME at a fresh temp dir, so the box's processes run from a writable, isolated home.

@arg t The test the temp HOME is scoped to. @return []string The HOME (and PATH) environment for the box.

@testcase TestGuestFixtureDrivesLifecycle uses a BoxEnv-scoped HOME.

func (*GuestFixture) Close ¶ added in v0.1.0

func (f *GuestFixture) Close()

Close cancels the guest's serve loop and waits for it to return. It is registered with t.Cleanup by NewGuestFixture, so tests rarely call it directly; it is safe to call more than once.

@testcase TestGuestFixtureDrivesLifecycle tears the fixture down via Close.

type NoopStore ¶

type NoopStore struct{}

NoopStore is a store.Store that persists nothing: writes are dropped and reads find nothing. Tests that don't exercise persistence pass it to hub.New.