eventbustest

Documentation

Overview

Package eventbustest provides helper methods for testing an eventbus.Bus.

Usage

A Watcher presents a set of generic helpers for testing events.

To test code that generates events, create a Watcher from the eventbus.Bus used by the code under test, run the code to generate events, then use the watcher to verify that the expected events were produced. In outline:

bus := eventbustest.NewBus(t)
tw := eventbustest.NewWatcher(t, bus)
somethingThatEmitsSomeEvent()
if err := eventbustest.Expect(tw, eventbustest.Type[EventFoo]()); err != nil {
  t.Error(err.Error())
}

As shown, Expect checks that at least one event of the given type occurs in the stream generated by the code under test.

The following functions all take an any parameter representing a function. This function will take an argument of the expected type and is used to test for the events on the eventbus being of the given type. The function can take the shape described in Expect.

Type is a helper for only testing event type.

To check for specific properties of an event, use Expect, and pass a function as the second argument that tests for those properties.

To test for multiple events, use Expect, which checks that the stream contains the given events in the given order, possibly with other events interspersed.

To test the complete contents of the stream, use ExpectExactly, which checks that the stream contains exactly the given events in the given order, and no others.

To test for the absence of events, use ExpectExactly without any expected events, along side testing/synctest to avoid waiting for timers to ensure that no events are produced. This will look like:

synctest.Test(t, func(t *testing.T) {
	bus := eventbustest.NewBus(t)
	tw := eventbustest.NewWatcher(t, bus)
	somethingThatShouldNotEmitsSomeEvent()
	synctest.Wait()
	if err := eventbustest.ExpectExactly(tw); err != nil {
		t.Errorf("Expected no events or errors, got %v", err)
	}
})

See the usage examples.

Index

• func EqualTo[T any](want T) func(T) error
• func Expect(tw *Watcher, filters ...any) error
• func ExpectExactly(tw *Watcher, filters ...any) error
• func Inject[T any](inj *Injector, event T)
• func LogAllEvents(t testing.TB, bus *eventbus.Bus)
• func NewBus(t testing.TB) *eventbus.Bus
• func Type[T any]() func(T)
• type Injector
  • func NewInjector(t *testing.T, b *eventbus.Bus) *Injector
• type Watcher
  • func NewWatcher(t *testing.T, bus *eventbus.Bus) *Watcher

Functions

func EqualTo

func EqualTo[T any](want T) func(T) error

EqualTo returns an event-matching function for use with Expect and ExpectExactly that matches on an event of the given type that is equal to want by comparison with cmp.Diff. The expectation fails with an error message including the diff, if present.

func Expect

func Expect(tw *Watcher, filters ...any) error

Expect verifies that the given events are a subsequence of the events observed by tw. That is, tw must contain at least one event matching the type of each argument in the given order, other event types are allowed to occur in between without error. The given events are represented by a function that must have one of the following forms:

// Tests for the event type only
func(e ExpectedType)

// Tests for event type and whatever is defined in the body.
// If return is false, the test will look for other events of that type
// If return is true, the test will look for the next given event
// if a list is given
func(e ExpectedType) bool

// Tests for event type and whatever is defined in the body.
// The boolean return works as above.
// The if error != nil, the test helper will return that error immediately.
func(e ExpectedType) (bool, error)

// Tests for event type and whatever is defined in the body.
// If a non-nil error is reported, the test helper will return that error
// immediately; otherwise the expectation is considered to be met.
func(e ExpectedType) error

If the list of events must match exactly with no extra events, use ExpectExactly.

func ExpectExactly

func ExpectExactly(tw *Watcher, filters ...any) error

ExpectExactly checks for some number of events showing up on the event bus in a given order, returning an error if the events does not match the given list exactly. The given events are represented by a function as described in Expect. Use Expect if other events are allowed.

If you are expecting ExpectExactly to fail because of a missing event, or if you are testing for the absence of events, call [synctest.Wait] after actions that would publish an event, but before calling ExpectExactly.

func Inject

func Inject[T any](inj *Injector, event T)

Inject inserts events of T onto an eventbus.Bus. If an eventbus.Publisher for the type does not exist, it will be initialized lazily. Calling inject is synchronous, and the event will as such have been published to the eventbus by the time the function returns.

func LogAllEvents

func LogAllEvents(t testing.TB, bus *eventbus.Bus)

LogAllEvents logs summaries of all the events routed via the specified bus during the execution of the test governed by t. This is intended to support development and debugging of tests.

func NewBus

func NewBus(t testing.TB) *eventbus.Bus

NewBus constructs an eventbus.Bus that will be shut automatically when its controlling test ends.

func Type

func Type[T any]() func(T)

Type is a helper representing the expectation to see an event of type T, without caring about the content of the event. It makes it possible to use helpers like:

eventbustest.ExpectFilter(tw, eventbustest.Type[EventFoo]())

Types

type Injector

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

Injector holds a map with eventbus.Publisher, tied to an eventbus.Client for testing purposes.

func NewInjector

func NewInjector(t *testing.T, b *eventbus.Bus) *Injector

NewInjector constructs an Injector that can be used to inject events into the the stream of events used by code under test. After construction the caller may use Inject to insert events into the bus.

type Watcher

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

Watcher monitors and holds events for test expectations. The Watcher works with [synctest], and some scenarios does require the use of [synctest]. This is amongst others true if you are testing for the absence of events.

For usage examples, see the documentation in the top of the package.

func NewWatcher

func NewWatcher(t *testing.T, bus *eventbus.Bus) *Watcher

NewWatcher constructs a Watcher that can be used to check the stream of events generated by code under test. After construction the caller may use Expect and ExpectExactly, to verify that the desired events were captured.