backplanetest

package
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 24 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).

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

SetLive changes a Live field as the console would; watchers fire.

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.

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