util/eventbus: add test helpers to simplify testing events (#16294)

Instead of every module having to come up with a set of test methods for
the event bus, this handful of test helpers hides a lot of the needed
setup for the testing of the event bus.

The tests in portmapper is also ported over to the new helpers.

Updates #15160

Signed-off-by: Claus Lensbøl <claus@tailscale.com>

util/eventbus/eventbustest/doc.go

@@ -0,0 +1,45 @@
+// Copyright (c) Tailscale Inc & AUTHORS
+// SPDX-License-Identifier: BSD-3-Clause
+
+// 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.
+//
+// See the [usage examples].
+//
+// [usage examples]: https://github.com/tailscale/tailscale/blob/main/util/eventbus/eventbustest/examples_test.go
+package eventbustest