harbortest

type Agent ¶

type Agent interface {
	// Run executes the agent's logic against input and returns the
	// produced output (or an error). The captured EventLog is built
	// from the events the agent's interior publishes against the
	// kit's event bus — the Agent does not return the log directly.
	Run(ctx context.Context, input any) (output any, err error)
}

Agent is the unit of code a test author exercises via RunOnce. Implementations are typically thin wrappers around the test author's production code path — a planner step, a flow, a hand-rolled function — anything that consumes a Harbor identity context and produces an output value.

The signature is intentionally narrower than the engine's full runtime surface: most test authors do not own engine graphs and should not be forced to construct them just to exercise a tool call. Agents that DO want full runtime semantics can construct an engine internally and Run it inside the Agent body — the kit's identity context flows through.

Identity propagation. The ctx passed to Run carries the identity quadruple (TenantID, UserID, SessionID, RunID) via the internal/identity helpers; Agents that need it use identity.MustQuadrupleFrom(ctx). Tool drivers and bus publishers automatically attach the triple to events emitted during the run.

type AgentFunc ¶

type AgentFunc func(ctx context.Context, input any) (any, error)

AgentFunc adapts a plain function into an Agent. Use this when the test author's code is a top-level function rather than a method on a typed receiver.

func (f AgentFunc) Run(ctx context.Context, input any) (any, error)

type Deps ¶

type Deps struct {
	// Bus is the canonical EventBus the kit subscribes to. When nil,
	// RunOnce opens a fresh in-mem bus AND closes it before
	// returning. When non-nil, the caller owns the bus's lifecycle.
	Bus events.EventBus
	// Redactor is the audit redactor RunOnce uses if it has to open
	// its own bus (Bus == nil). When Bus is non-nil this field is
	// ignored — the bus already has its redactor configured.
	Redactor audit.Redactor
	// Identity overrides the deterministic canonical identity. When
	// nil, RunOnce uses the canonical "harbortest" triple.
	Identity *identity.Identity
	// RunID overrides the auto-generated RunID. When empty, RunOnce
	// synthesises a fresh ULID-ish RunID via runIDFromCounter so
	// concurrent invocations don't collide.
	RunID string
}

Deps carries optional dependencies for RunOnce. The zero-value Deps causes RunOnce to synthesise deterministic defaults (canonical identity triple, fresh in-mem bus + redactor, fresh RunID). Callers that need cross-RunOnce coordination — e.g. a shared bus that captures events from multiple agents — pass an explicit Deps with the shared component set.

Identity and RunID. When Identity is nil the kit uses a canonical "harbortest" triple (TenantID="harbortest", UserID="harbortest", SessionID="harbortest"). A nil Identity AND a non-empty RunID is honoured — the RunID is paired with the canonical identity. When the caller supplies an Identity, it must validate (non-empty triple) or RunOnce returns a wrapped identity.ErrIdentityIncomplete.

type EventLog ¶

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

EventLog is the captured event stream from one RunOnce invocation (or, when the caller shares a Deps.Bus across runs, the union of every event published during the lifetime of the captured subscription). Events are appended in the order they arrive from the bus subscription channel — Harbor's bus assigns monotonic Sequence numbers, so the slice order matches Sequence order within a single bus.

Concurrent reuse contract (D-025). EventLog serialises appends behind an internal mutex; All() returns a defensive copy so callers may iterate while the producer side is still publishing. Readers and writers may run concurrently.

func RunOnce(ctx context.Context, agent Agent, input any, deps ...Deps) (any, *EventLog, error)

func (l *EventLog) All() []events.Event

func (l *EventLog) Len() int

func (l *EventLog) RecordedEvents(runID string) []events.Event

type FaultInjector ¶

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

FaultInjector wraps a tools.ToolCatalog so the kit can schedule per-tool failures before exercising an Agent. The injector is transparent on the read path — Resolve returns a ToolDescriptor whose Invoke closure pops a counter on each call; when the counter is exhausted the original descriptor's Invoke runs unmodified.

Concurrent reuse (D-025). The injector serialises access to its counter map behind a mutex; counter updates are atomic per tool. Resolve / List are safe for N concurrent goroutines.

func NewFaultInjector(cat tools.ToolCatalog) *FaultInjector

func (f *FaultInjector) Catalog() tools.ToolCatalog

type TestingT ¶

type TestingT interface {
	// Helper marks the calling function as a helper so the test
	// runtime's failure reporting points at the call site, not at
	// the helper internals.
	Helper()
	// Errorf reports a non-fatal test failure. The assertion
	// helpers in this kit use Errorf (not Fatalf) so multiple
	// failures in one test surface together — this matches the
	// convention every Harbor integration test uses.
	Errorf(format string, args ...any)
}

TestingT is the subset of *testing.T the kit's assertions need. Mirroring the standard testing.TB-ish shape lets callers pass either *testing.T or *testing.B; the kit's own self-tests use *testing.T directly.

The kit deliberately avoids the full testing.TB interface because TB is sealed by the Go standard library — callers that want to drive the assertions from non-test code (e.g. a programmatic verification harness) can implement TestingT themselves with their own Helper / Errorf semantics.