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
- func ScriptedCallID(index int) string
- type CompletionHold
- type Infra
- func (i *Infra) APIURL(path string) string
- func (i *Infra) AppLogs(ctx context.Context) (string, error)
- func (i *Infra) DefaultModel() string
- func (i *Infra) DisableScriptedToolTurn()
- func (i *Infra) EnableScriptedToolTurn(script ScriptedToolTurn)
- func (i *Infra) HTTPClient() *http.Client
- func (i *Infra) HoldNextCompletion() (*CompletionHold, error)
- func (i *Infra) LastReasoningEffort() string
- func (i *Infra) LastSystemPrompt() string
- func (i *Infra) MetricsURL(path string) string
- func (i *Infra) ModelDiscoveryObserved() bool
- func (i *Infra) ProviderRequests() [][]ProviderMessage
- func (i *Infra) Restart(ctx context.Context) error
- func (i *Infra) StartVariant(ctx context.Context, options VariantOptions) (*Infra, error)
- func (i *Infra) Teardown(ctx context.Context) error
- func (i *Infra) WriteWorkspaceFile(ctx context.Context, name string, content []byte) error
- type ProviderMessage
- type ProviderMock
- type ScriptedToolCall
- type ScriptedToolTurn
- type VariantOptions
Constants ¶
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
ScriptedCallID is the tool call ID the provider mock gives the call at index in a ScriptedToolTurn's Calls.
Types ¶
type CompletionHold ¶
type CompletionHold struct {
Observed <-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 ¶
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 ¶
APIURL returns the production API endpoint reachable from the Go test process.
func (*Infra) AppLogs ¶
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) DefaultModel ¶ added in v0.17.0
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 ¶
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
LastReasoningEffort returns the reasoning_effort of the most recent provider request, or an empty string when the request carried none.
func (*Infra) LastSystemPrompt ¶
LastSystemPrompt returns the most recent provider request's system prompt.
func (*Infra) MetricsURL ¶
MetricsURL returns the private metrics endpoint reachable from the Go test process over the application container's loopback listener.
func (*Infra) ModelDiscoveryObserved ¶
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 ¶
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
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.
type ProviderMessage ¶ added in v0.18.1
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) 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.