testinfra

package
v0.34.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package testinfra is the extendable integration-test harness for a servicepack app. Its baseline builds the servicepack image from the repo Dockerfile and runs it, so a test exercises the real, containerized application with whatever services it registers, and nothing more.

Extend it with the external dependencies your services need (a database, a cache, a broker via testcontainers-go): give Infra a field, start it in Setup, wire the app container to it, and tear it down in Teardown. The DIND runner already supports this: DEV_RUN_DIND uses the host network, so testcontainers' host-published ports are reachable.

Index

Constants

View Source
const (

	// ConfigInstructions is the AGENTS.md the app container's config
	// directory holds.
	ConfigInstructions = "Follow the request and use available tools."

	// TestAPIToken is the deliberately fake bearer token injected into the
	// production container for API integration tests.
	TestAPIToken = "EXAMPLE-DO-NOT-USE"

	// TestProviderKey is the deliberately fake provider credential the
	// controller holds in the variable named by the test provider's
	// apiKeyEnv. A command the agent runs must never see it.
	TestProviderKey = "EXAMPLE-PROVIDER-KEY-DO-NOT-USE"

	// ProviderKeyEnvName is the variable that holds TestProviderKey.
	ProviderKeyEnvName = "PEEN_TEST_PROVIDER_KEY"

	// These fixed call IDs let tests pair durable tool messages and SSE blocks.
	ScriptedCallIDReadFile   = "call-scripted-read-file"
	ScriptedCallIDEditFile   = "call-scripted-edit-file"
	ScriptedCallIDApplyPatch = "call-scripted-apply-patch"
	ScriptedCallIDRunCommand = "call-scripted-run-command"

	// ContainerWorkingDirectory is the process working directory used by the
	// application container, so a test can seed and read back fixture files
	// under the immutable tool workspace without duplicating the path.
	ContainerWorkingDirectory = appWorkingDirectory

	// DefaultProviderReasoning is the visible reasoning emitted by ordinary
	// provider completions in API integration tests.
	DefaultProviderReasoning = "integration reasoning"
)

Variables

This section is empty.

Functions

func ScriptedCallID added in v0.18.1

func ScriptedCallID(index int) string

ScriptedCallID is the tool call ID the provider mock gives the call at index in a ScriptedToolTurn's Calls.

func ToolOutputText added in v0.34.0

func ToolOutputText(content string) string

ToolOutputText returns the result text inside the <toolOutput> wrapper Peen puts around a tool result. Text without the wrapper is returned as it is.

Types

type CompletionHold

type CompletionHold struct {
	Observed  <-chan struct{}
	Cancelled <-chan struct{}
	// contains filtered or unexported fields
}

CompletionHold exposes the point where a provider completion has reached the mock and a release operation for tests that need an active agent turn.

func (*CompletionHold) Release

func (h *CompletionHold) Release()

Release allows the held provider completion to emit its deterministic stream.

type Infra

type Infra struct {
	App testcontainers.Container
	// contains filtered or unexported fields
}

Infra holds the containers a test package brought up. At the baseline that is just the application image; extend it with one field per external dependency (for example: Postgres *PostgresResource) as your services grow.

func Setup

func Setup(ctx context.Context) (*Infra, error)

Setup builds Peen's app image and starts it against a local OpenAI-compatible provider mock. API readiness proves production config, migrations, provider discovery, and the HTTP service all completed.

func (*Infra) APIURL

func (i *Infra) APIURL(path string) string

APIURL returns the production API endpoint reachable from the Go test process.

func (*Infra) AppLogs

func (i *Infra) AppLogs(ctx context.Context) (string, error)

AppLogs returns the current production container logs for failed API-test diagnostics. Test code must use them only to explain a failed contract.

func (*Infra) CrashAndRestart added in v0.25.0

func (i *Infra) CrashAndRestart(ctx context.Context) (resultErr error)

CrashAndRestart kills this fixture's container without graceful cleanup, then starts it with the same files and waits for HTTP readiness.

func (*Infra) DefaultModel added in v0.17.0

func (i *Infra) DefaultModel() string

DefaultModel returns the qualified model reference the production container runs a turn on when a message names none.

func (*Infra) DisableScriptedToolTurn

func (i *Infra) DisableScriptedToolTurn()

DisableScriptedToolTurn restores the default fixed-text completion.

func (*Infra) EnableScriptedToolTurn

func (i *Infra) EnableScriptedToolTurn(script ScriptedToolTurn)

EnableScriptedToolTurn makes every subsequent provider completion follow script's fixed tool conversation instead of the default single fixed text response. Off by default, so a test that never calls this sees byte-identical behavior to before this method existed. Call DisableScriptedToolTurn (for example via t.Cleanup) once the scripted conversation is over, so later tests see the default behavior again.

func (*Infra) HTTPClient

func (i *Infra) HTTPClient() *http.Client

HTTPClient returns the client used to drive the production API container.

func (*Infra) HoldNextCompletion

func (i *Infra) HoldNextCompletion() (*CompletionHold, error)

HoldNextCompletion blocks one provider completion until Release is called or the application cancels the upstream request.

func (*Infra) LastReasoningEffort added in v0.14.0

func (i *Infra) LastReasoningEffort() string

LastReasoningEffort returns the reasoning_effort of the most recent provider request, or an empty string when the request carried none.

func (*Infra) LastSystemPrompt

func (i *Infra) LastSystemPrompt() string

LastSystemPrompt returns the most recent provider request's system prompt.

func (*Infra) MetricsURL

func (i *Infra) MetricsURL(path string) string

MetricsURL returns the private metrics endpoint reachable from the Go test process over the application container's loopback listener.

func (*Infra) ModelDiscoveryObserved

func (i *Infra) ModelDiscoveryObserved() bool

ModelDiscoveryObserved reports whether the app called the configured models endpoint during startup.

func (*Infra) ProviderRequests added in v0.18.1

func (i *Infra) ProviderRequests() [][]ProviderMessage

ProviderRequests returns every completion request the provider mock has received, oldest first, each as its full message list. A test notes the length before it acts and reads the requests after that index.

func (*Infra) Restart

func (i *Infra) Restart(ctx context.Context) error

Restart stops and starts the production application container, then waits for its already-configured HTTP listener to become ready again.

func (*Infra) StartVariant added in v0.18.1

func (i *Infra) StartVariant(
	ctx context.Context,
	options VariantOptions,
) (*Infra, error)

StartVariant starts another container from the base image with its own provider mock, listeners, and state, so a test can exercise configuration the base container does not carry. The variant shares the image, so its Teardown leaves the image to the base Infra's Teardown.

func (*Infra) Teardown

func (i *Infra) Teardown(ctx context.Context) error

Teardown terminates every started container. It is safe to call after a partially completed setup and returns any application cleanup failure.

func (*Infra) WriteWorkspaceFile

func (i *Infra) WriteWorkspaceFile(
	ctx context.Context,
	name string,
	content []byte,
) error

WriteWorkspaceFile adds or replaces one relative fixture file below the production container's configured default workspace.

type ProviderMessage added in v0.18.1

type ProviderMessage struct {
	Role       string
	Content    string
	ToolCallID string
}

ProviderMessage is one message of a completion request the provider mock received. Content is the message text as sent, or the raw JSON when the content is not a plain string.

type ProviderMock

type ProviderMock struct {
	// contains filtered or unexported fields
}

ProviderMock is a deterministic local OpenAI-compatible provider for process-form tests. It exposes no credentials and accepts only Peen's fixed integration model.

func NewProviderMock

func NewProviderMock() *ProviderMock

NewProviderMock starts a local deterministic provider fixture.

func (*ProviderMock) BaseURL

func (m *ProviderMock) BaseURL() string

BaseURL returns the fixture's OpenAI-compatible endpoint.

func (*ProviderMock) Close

func (m *ProviderMock) Close()

Close stops the fixture server.

func (*ProviderMock) DefaultModel

func (m *ProviderMock) DefaultModel() string

DefaultModel returns the qualified model reference accepted by the fixture.

func (*ProviderMock) DisableScriptedToolTurn

func (m *ProviderMock) DisableScriptedToolTurn()

DisableScriptedToolTurn restores the fixture's ordinary text response.

func (*ProviderMock) EnableScriptedToolTurn

func (m *ProviderMock) EnableScriptedToolTurn(script ScriptedToolTurn)

EnableScriptedToolTurn makes later completions issue the supplied tool sequence before returning its final answer.

func (*ProviderMock) LastSystemPrompt

func (m *ProviderMock) LastSystemPrompt() string

LastSystemPrompt returns the latest completion request's system prompt.

type ScriptedToolCall added in v0.18.1

type ScriptedToolCall struct {
	Name          string
	Arguments     map[string]any
	ArgumentsFrom func(results []string) map[string]any
}

ScriptedToolCall is one tool call a ScriptedToolTurn issues in Calls mode. ArgumentsFrom, when set, builds the arguments from the content of the tool results the turn already holds, oldest first, and wins over Arguments.

type ScriptedToolTurn

type ScriptedToolTurn struct {
	UserMessage         string
	Calls               []ScriptedToolCall
	ReadFileArguments   map[string]any
	EditFileArguments   map[string]any
	ApplyPatchArguments map[string]any
	RunCommandArguments map[string]any
	FinalAnswer         string
	Children            []ScriptedToolTurn
}

ScriptedToolTurn drives readFile, one mutation, runCommand, and a final answer. UserMessage anchors the sequence in a durable transcript so old tool results from an earlier test turn cannot change its first round. Set exactly one of EditFileArguments and ApplyPatchArguments.

Calls, when set, replaces that fixed sequence: the turn issues these tool calls in order, then answers with FinalAnswer. A request whose transcript lacks UserMessage, such as a child agent's, gets the default text completion instead.

Children script child agent conversations the same way. A child script's UserMessage is the task text, which the child receives inside a <message> block naming its sender.

type VariantOptions added in v0.18.1

type VariantOptions struct {
	// Environment adds or replaces application environment variables.
	Environment map[string]string
	// UnsetEnvironment removes variables the base environment sets.
	UnsetEnvironment []string
}

VariantOptions changes the environment of a second application container started from the image the base Infra built.

Jump to

Keyboard shortcuts

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