backplanetest

package
v0.6.88 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package backplanetest runs components without Open, Run, ports or Consul: build them under Root, Start, and inspect what they published, answer their hooks, invoke their activities and reactors, and check their readiness. Native workflow tests use the optional workflows/workflowtest package.

h := backplanetest.New(t, backplanetest.Name("hello"))
g, _ := greeter.New(h.Root(), &cfg, deps.Static(db))
h.Start()
backplanetest.Events(h, g.Greeted()) // what g published

Transports are replaced by a recorder: Publish is recorded (FailPublish and Unavailable make it fail), Call is answered by Answer, reactors run through React and activities through Activity, both with the metadata a transport puts on the handler's context (event.DeliveryOf, activity.InfoOf). The optional workflows/workflowtest package builds a Temporal testsuite environment with the same registrations and hook answers.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotDeclared: no activity or reactor is declared under that name.
	ErrNotDeclared = errors.New("backplanetest: not declared")
	// ErrNotReady: the tree's readiness is down (Ready).
	ErrNotReady = errors.New("backplanetest: not ready")
	// ErrNotLive: the tree's liveness is down (Live).
	ErrNotLive = errors.New("backplanetest: not live")
)

Errors.

Functions

func Activity

func Activity[Req, Res any](ctx context.Context, h *Harness, name string, in Req) (Res, error)

Activity invokes a declared activity as a binding would, once: the handler's ctx carries activity.InfoOf with Attempt 1, a Key unique to this call ("backplanetest/<name>/<uuid>/1") and ctx's deadline; Heartbeat does nothing.

func Answer

func Answer[Req, Res any](h *Harness, ref hook.Ref[Req, Res], fn func(ctx context.Context, in Req) (Res, error))

Answer makes fn answer ref's calls, from Call and, in Workflows, from workflows.CallHook; unanswered hooks fail with hook.ErrUnavailable as in production without a transport (workflows.CallHook: hook.ErrNoBinding). An answered hook is bound (hook.Ref.Bound), an unanswered one is not, and BindingChanges signals when Answer binds one.

func Available

func Available(h *Harness)

Available undoes Unavailable.

func CallKey

func CallKey(ctx context.Context) string

CallKey is the hook.Key of the call an Answer function serves; "" for a call without one.

func Caller added in v0.6.29

func Caller(ctx context.Context, caller backplane.Caller) context.Context

Caller is ctx as a request from caller over mutual TLS carries it: backplane.CallerOf reports caller, so a test calls a handler served with api.MTLS directly, or over bufconn with Caller in a server interceptor.

ctx := backplanetest.Caller(t.Context(), backplane.Caller{Service: "sync"})
_, err := rooms.Join(ctx, req) // authorizes caller sync

func Config

func Config[C any](tb testing.TB, vars map[string]string) C

Config loads a configuration of type C (a section such as greeter.Config or a whole service Config) as the service would, from the schema defaults and vars only: no file, no process environment, no Consul. vars are named as in the service's environment without its prefix: {"SUFFIX": "?"} for a section, {"GREETER_SUFFIX": "?"} for the whole Config; a name the schema does not know fails. Every Validate of C and its sections runs, as Open runs them. A failure fails the test.

func Events

func Events[T any](h *Harness, ref event.Ref[T]) []T

Events decodes what was published to ref so far.

func FailPublish

func FailPublish(h *Harness, err error)

FailPublish makes every Publish fail with err (wrapped as the transport wraps its errors) until FailPublish(h, nil); nothing is recorded meanwhile.

func Find added in v0.6.19

func Find(h *Harness, name string) deps.Component

Find is the node of h's tree named name — its Name, or its Path under the root ("sync/fanout") — as a scope Stop takes: a test reaches a component the service does not export. It fails the test when no node or more than one matches (the failure lists the paths).

func Live added in v0.6.84

func Live(h *Harness) error

Live evaluates the tree's liveness as the service's liveness probe does (the same composite, bounded like Ready): nil while every component and dependency can still recover; otherwise an error matching ErrNotLive with the failing probes' reasons, e.g. a dependency whose probe reported deps.ErrTerminal (a NATS connection closed for good). A dependency that is only down (reconnecting) fails Ready, not Live. Dependencies learn they are terminal from their probes, which the service runs every interval: Live runs them first too.

func LoadConfig

func LoadConfig[C any](ctx context.Context, vars map[string]string) (C, error)

LoadConfig is Config returning the error: to test what the configuration rejects.

func Offered added in v0.6.45

func Offered(h *Harness, name string) *anypb.Any

Offered is section name as the service in h's tree offers it: the value it set last (sections.OfferLive), else its manifest's; nil when it offers none.

func Operator added in v0.6.25

func Operator(ctx context.Context, session uuid.UUID) context.Context

Operator is ctx as a call the console relays for session carries it: backplane.OperatorOf reports that session, so a test calls an internal API handler directly as an operator would.

ctx := backplanetest.Operator(t.Context(), session)
_, err := admin.CloseRoom(ctx, req) // audits actor console:<session>

func React

func React[T any](ctx context.Context, h *Harness, path, name string, v T, opts ...DeliveryOption) error

React delivers v to the reactor declared for the event name (full, "iam.UserRegistered") on the scope at path ("" for the root), as the broker would: once, with the reactor's event.Timeout and a full event.Delivery on ctx (a new ID, Attempt 1, the reactor's Consumer, extensions instance and version; opts change them). A reactor pinned with event.Consumer is found by its event when it is the only pinned reactor of it; else use ReactConsumer. The error is the handler's; nothing is redelivered or dead-lettered.

func ReactConsumer

func ReactConsumer[T any](ctx context.Context, h *Harness, consumer string, v T, opts ...DeliveryOption) error

ReactConsumer delivers v to the reactor whose consumer is consumer (as the manifest's subscriptions list it, pinned or derived), as React does.

func Ready

func Ready(h *Harness) error

Ready evaluates the tree's readiness as the service's readiness probe does: every required dependency provided and passing its probe. nil when ready; otherwise an error matching ErrNotReady that names each dependency that is not and why. Optional dependencies never count.

func SetLive

func SetLive[T any](l *config.Live[T], v T) error

SetLive changes a Live field as the console would: its appliers (Live.Apply) run first and their error is returned with the field left as it was; otherwise the value is published and watchers fire.

func SetSections added in v0.6.43

func SetSections(h *Harness, name string, services map[string]proto.Message)

SetSections publishes section name as Backplane does: services, by service, become the set every sections.Follow of name in h's tree reads. An empty or nil services is a known empty set; a repeat of the same set signals no change.

func Stop added in v0.6.17

func Stop(h *Harness, scope deps.Scope)

Stop stops one component's subtree now — a projection, a consumer, a worker killed in the middle of a test — while the rest of the tree runs: its goroutines are cancelled (their context ends wherever they are) and waited for, its children and then its own OnStop hooks run, within the StopBudget. A failure fails the test. It stays stopped: what it served is gone for the components that use it, as in a crash; the tree's cleanup skips it. scope must be a component created under h.Root.

func Unavailable

func Unavailable(h *Harness)

Unavailable takes both transports away, as while NATS and Temporal are down: Publish fails with event.ErrUnavailable, Call with hook.ErrUnavailable (in Workflows, a workflows.CallHook finds no binding), until Available.

Types

type DeliveryOption

type DeliveryOption func(in *env.Incoming)

DeliveryOption sets what event.DeliveryOf reports to a reactor run by React or ReactConsumer.

func WithAttempt

func WithAttempt(n int) DeliveryOption

WithAttempt is the delivery's attempt (Delivery.Attempt), 1 by default.

func WithEvent added in v0.6.47

func WithEvent(full string) DeliveryOption

WithEvent is the event's full name ("<service>.<Event>"), its source with it: what a raw reactor (event.ReactRaw, run with ReactConsumer) sees for one event of its pattern.

func WithHeader

func WithHeader(name, value string) DeliveryOption

WithHeader adds an extension (Delivery.Extensions) as event.Header sets it.

func WithID

func WithID(id string) DeliveryOption

WithID is the event's id (Delivery.ID), by default a new UUID: deliver the same id twice to test idempotency.

func WithKey

func WithKey(k string) DeliveryOption

WithKey is the event's Key (Delivery.Subject).

type Harness

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

Harness is one service's tree, started by Start and stopped at cleanup.

func New

func New(tb testing.TB, opts ...Option) *Harness

New creates a harness for a service named "test", or as Name says.

func (*Harness) Manifest

func (h *Harness) Manifest() *backplanev1.Manifest

Manifest is what the components declared so far.

func (*Harness) Root

func (h *Harness) Root() deps.Component

Root is where components and dependencies under test are created.

func (*Harness) Service

func (h *Harness) Service() string

Service is the harness's service name.

func (*Harness) Start

func (h *Harness) Start()

Start starts the tree (dependencies are provided, goroutines run) and stops it at test cleanup within the StopBudget; a failure fails the test.

func (*Harness) Stop added in v0.6.17

func (h *Harness) Stop()

Stop stops the whole tree now, as the cleanup would: goroutines are cancelled and waited for and OnStop hooks run in reverse start order, within the StopBudget; a failure fails the test. The cleanup then has nothing left to stop. A restarted instance is a new Harness.

type Option

type Option func(o *options)

Option configures New.

func Name

func Name(service string) Option

Name is the service's name (default "test"): events are published as <name>.<Event>, hooks called as <name>.<Name>, and a reactor to the service's own event subscribes to "<name>.<Event>". It panics on a name that is not a service name ([a-z][a-z0-9-]*).

func StopBudget

func StopBudget(d time.Duration) Option

StopBudget bounds the stop at test cleanup (default 10s): a component whose goroutines outlive it fails the test.

type Published

type Published[T any] struct {
	Value T
	// Key is the event.Key it was published with ("" without).
	Key string
	// ID is event.ID, else the new UUID the transport would assign.
	ID string
	// Time is event.Time, else the publish time.
	Time time.Time
	// Headers are the event.Header values by name.
	Headers map[string]string
}

Published is one recorded event with what Publish set on it.

func EventsWithMeta

func EventsWithMeta[T any](h *Harness, ref event.Ref[T]) []Published[T]

EventsWithMeta is Events with each event's key, id, time and headers.

Jump to

Keyboard shortcuts

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