testkit

package
v0.33.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package testkit runs a tool (pkg/tool) in-process for tests, with the rules the runtime applies in production: the manifest must be valid, the configuration must match its schema, only declared credentials are delivered, every record is checked (CTIS validity, declared output types, size and count limits, control characters), and the report is assembled and stamped as the runtime does. A tool that the runtime would stop fails its unit test.

Stability: Stable (docs/STABILITY.md).

func TestDotenv(t *testing.T) {
	res := testkit.Run(t, dotenv.Tool, tool.Task{
		Targets: []tool.Target{{Ref: "a1", Type: "http_service", Value: srv.URL}},
	})
	res.RequireStatus(t, tool.StatusOK)
	res.Golden(t, "testdata/dotenv.golden.json")
}

Index

Constants

View Source
const MaxArtifactBytes = 64 << 20

MaxArtifactBytes bounds an artifact in the test kit (as the runtime does).

Variables

This section is empty.

Functions

func Golden

func Golden(t testing.TB, report *ctis.Report, path string)

Golden compares a normalized report with the file at path (see Result.Golden).

func Normalize

func Normalize(report *ctis.Report) ([]byte, error)

Normalize returns a report as stable, indented JSON: times and durations removed, metadata.id removed, the runtime's provenance replaced by a placeholder and its per-target outcomes (target_outcomes) removed. Two runs of a deterministic tool normalize identically.

Types

type LogEntry

type LogEntry struct {
	Level slog.Level
	Msg   string
	Attrs map[string]any
}

LogEntry is one message the tool logged (already redacted).

type Options

type Options struct {
	// Secrets the operator stored. Only those the manifest declares reach
	// the tool, as in production.
	Secrets map[string]string
	// Timeout bounds the run (default: the manifest's timeout).
	Timeout time.Duration
	// Files are written to the task's directory before the run, by path
	// relative to it, as the runtime places a parser's inputs.
	Files map[string][]byte
}

Options adjust a run.

type Result

type Result struct {
	Report  *ctis.Report
	Status  tool.Status
	Err     *tool.Error
	Targets []TargetOutcome
	Stats   toolrt.Stats
	Logs    []LogEntry
	// Artifacts by name.
	Artifacts map[string][]byte
	// Verdicts of a retest task, one per item, as the runtime reports them
	// (no verdict, or Fixed on a target not reported done or in a task that
	// did not finish, is Unverifiable).
	Verdicts []tool.RetestVerdict
}

Result is a run's outcome.

func Run

func Run(t testing.TB, tl tool.Tool, task tool.Task, opts ...Options) *Result

Run runs tl on task in-process. The task's ID defaults to "test-task".

func (*Result) Golden

func (r *Result) Golden(t testing.TB, path string)

Golden compares the normalized report with the file at path. With OPENCTEM_UPDATE_GOLDEN=1 it rewrites the file instead.

func (*Result) RequireStatus

func (r *Result) RequireStatus(t testing.TB, st tool.Status)

RequireStatus fails the test unless the run ended with st.

type TargetOutcome

type TargetOutcome struct {
	Ref    string
	State  tool.TargetState
	Class  tool.ErrorClass
	Detail string
}

TargetOutcome is the outcome of one target.

Jump to

Keyboard shortcuts

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