contract

package
v0.32.3 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package contract provides a lightweight unit-level test harness for asserting Nexus plugin event contracts (Subscriptions / Emissions).

It deliberately lives outside pkg/testharness so plugin packages can import it without dragging in pkg/engine/allplugins (which would form an import cycle: plugin → harness → allplugins → plugin).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CapturedEvent

type CapturedEvent struct {
	Type    string
	Source  string
	Payload any
	Origin  EventOrigin
}

CapturedEvent records a single event observed on the bus during a contract test. Origin distinguishes events injected by the test from events emitted by the plugin under test.

type ContractHarness

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

ContractHarness runs a single Nexus plugin in isolation against a real engine.Bus and a minimal PluginContext, capturing every emitted event so tests can assert against the plugin's declared event contract.

Use NewContract to construct, Inject to drive scripted events, and the Assert* methods to check what the plugin did. Shutdown is registered with t.Cleanup automatically.

func NewContract

func NewContract(t *testing.T, factory engine.PluginFactory, opts ...ContractOption) *ContractHarness

NewContract constructs a ContractHarness, calls Init and Ready on the plugin, and registers a cleanup that drains the bus and calls Shutdown.

func (*ContractHarness) AssertEmitted

func (h *ContractHarness) AssertEmitted(eventType string)

AssertEmitted fails when no plugin-origin event of the given type was captured.

func (*ContractHarness) AssertEmittedInOrder

func (h *ContractHarness) AssertEmittedInOrder(types ...string)

AssertEmittedInOrder fails when the named event types do not appear in the captured plugin-origin stream in the given relative order. Other emissions between them are ignored.

func (*ContractHarness) AssertNoUndeclaredEmissions

func (h *ContractHarness) AssertNoUndeclaredEmissions()

AssertNoUndeclaredEmissions fails when the plugin emitted an event type not listed in its declared Emissions() set. before:* events the plugin dispatches as part of veto-protocol handling are exempt because the declaration list typically only carries non-vetoable types.

func (*ContractHarness) AssertNotEmitted

func (h *ContractHarness) AssertNotEmitted(eventType string)

AssertNotEmitted fails when any plugin-origin event of the given type was captured.

func (*ContractHarness) AssertSubscribesTo

func (h *ContractHarness) AssertSubscribesTo(eventTypes ...string)

AssertSubscribesTo fails when the plugin's declared Subscriptions does not include every type in the given list. Compares against the static declaration, not runtime behavior — pair with Inject + AssertEmitted to verify a subscription actually fires.

func (*ContractHarness) Bus

func (h *ContractHarness) Bus() engine.EventBus

Bus returns the harness bus so tests can subscribe directly when they need to observe vetoable events or set up extra handlers.

func (*ContractHarness) Captured

func (h *ContractHarness) Captured() []CapturedEvent

Captured returns a copy of all events observed on the bus, in order.

func (*ContractHarness) Inject

func (h *ContractHarness) Inject(eventType string, payload any)

Inject emits an event on the harness bus and records its ID so the captured-event stream can distinguish it from plugin emissions.

func (*ContractHarness) InjectVetoable

func (h *ContractHarness) InjectVetoable(eventType string, payload any) engine.VetoResult

InjectVetoable dispatches a before:* event and returns the resulting VetoResult so tests can assert that a gate vetoed (or didn't) and read the reason.

func (*ContractHarness) Plugin

func (h *ContractHarness) Plugin() engine.Plugin

Plugin returns the plugin under test.

func (*ContractHarness) PluginEmissions

func (h *ContractHarness) PluginEmissions() []CapturedEvent

PluginEmissions returns only the events the plugin (or downstream handlers) emitted, filtering out test injects.

func (*ContractHarness) RegisteredSubscriptions

func (h *ContractHarness) RegisteredSubscriptions() []engine.SubscriptionInfo

RegisteredSubscriptions returns the typed subscriptions the plugin had registered on the harness bus when Init and Ready returned. Subscriptions a test adds afterwards through Bus() are not included.

func (*ContractHarness) SessionDir

func (h *ContractHarness) SessionDir() string

SessionDir returns the harness's session workspace root, or empty when the harness was constructed without WithSession.

func (*ContractHarness) WaitForEmitted

func (h *ContractHarness) WaitForEmitted(eventType string, timeout time.Duration)

WaitForEmitted blocks until a plugin-origin event of the given type has been captured, or the timeout expires. It is the assertion to use when the test learned about the event from its OWN bus subscription rather than from the harness.

That distinction is not a nicety. The harness captures through SubscribeAll, and pkg/engine dispatches every typed subscriber BEFORE any wildcard one — deliberately, so a wildcard journal handler observes the final veto state. A test that wakes on its own typed handler is therefore guaranteed to run while the harness's recorder has not yet been reached, and a bare AssertEmitted at that moment reads state that has provably not been written. It passes only because the emitting goroutine usually finishes its wildcard loop before the woken test goroutine is rescheduled; under -race that ordering shifts and the assertion fails for no reason the test author would recognise.

Use AssertEmitted when nothing ran between the trigger and the assertion. Use this when a channel, callback or other goroutine handoff did.

type ContractOption

type ContractOption func(*contractConfig)

ContractOption configures a ContractHarness.

func WithConditionalSubscriptions added in v0.31.0

func WithConditionalSubscriptions(eventTypes ...string) ContractOption

WithConditionalSubscriptions exempts the named event types from the declared-but-unregistered check NewContract runs automatically. Use it for a subscription the plugin declares unconditionally but only registers under some config (or lazily, after Ready) that this test does not exercise. Each entry should carry a comment naming the config that wires it; prefer passing that config instead when it is cheap to supply.

func WithLogger

func WithLogger(l *slog.Logger) ContractOption

WithLogger overrides the default discard logger.

func WithPluginConfig

func WithPluginConfig(cfg map[string]any) ContractOption

WithPluginConfig provides the YAML-derived config map the plugin would normally receive from the engine.

func WithPluginID

func WithPluginID(id string) ContractOption

WithPluginID overrides the harness-supplied plugin ID. Useful when a plugin uses InstanceID-aware naming. Defaults to plugin.ID().

func WithSession

func WithSession() ContractOption

WithSession boots the harness with a real SessionWorkspace pointed at a per-test temp dir. Enables plugins that touch ctx.Session, ctx.DataDir, or ScopeSession storage. Off by default to keep tests fast.

type EventOrigin

type EventOrigin int

EventOrigin tags whether an event arrived via test injection or plugin emit.

const (
	OriginUnknown EventOrigin = iota
	OriginInject              // emitted by ContractHarness.Inject
	OriginPlugin              // emitted by the plugin or any handler reacting to an inject
)

Jump to

Keyboard shortcuts

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