backplanetest

package
v0.6.46 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 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")
)

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 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 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