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 ¶
- Variables
- func Activity[Req, Res any](ctx context.Context, h *Harness, name string, in Req) (Res, error)
- func Answer[Req, Res any](h *Harness, ref hook.Ref[Req, Res], ...)
- func Available(h *Harness)
- func CallKey(ctx context.Context) string
- func Caller(ctx context.Context, caller backplane.Caller) context.Context
- func Config[C any](tb testing.TB, vars map[string]string) C
- func Events[T any](h *Harness, ref event.Ref[T]) []T
- func FailPublish(h *Harness, err error)
- func Find(h *Harness, name string) deps.Component
- func Live(h *Harness) error
- func LoadConfig[C any](ctx context.Context, vars map[string]string) (C, error)
- func Offered(h *Harness, name string) *anypb.Any
- func Operator(ctx context.Context, session uuid.UUID) context.Context
- func React[T any](ctx context.Context, h *Harness, path, name string, v T, ...) error
- func ReactConsumer[T any](ctx context.Context, h *Harness, consumer string, v T, opts ...DeliveryOption) error
- func Ready(h *Harness) error
- func SetLive[T any](l *config.Live[T], v T) error
- func SetSections(h *Harness, name string, services map[string]proto.Message)
- func Stop(h *Harness, scope deps.Scope)
- func Unavailable(h *Harness)
- type DeliveryOption
- type Harness
- type Option
- type Published
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 CallKey ¶
CallKey is the hook.Key of the call an Answer function serves; "" for a call without one.
func Caller ¶ added in v0.6.29
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 ¶
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 FailPublish ¶
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
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
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 ¶
LoadConfig is Config returning the error: to test what the configuration rejects.
func Offered ¶ added in v0.6.45
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
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 ¶
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 ¶
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
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
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 ¶
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.
type Harness ¶
type Harness struct {
// contains filtered or unexported fields
}
Harness is one service's tree, started by Start and stopped at cleanup.
func (*Harness) Manifest ¶
func (h *Harness) Manifest() *backplanev1.Manifest
Manifest is what the components declared so far.
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 ¶
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 ¶
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.