Documentation
¶
Overview ¶
Package natsfixture gives one test one disposable, real NATS server in a container (capability nats-fixture). It works over nats.go and testcontainers-go directly and offers no start, connect or bucket-prefix knobs (nats-fixture › "No start knobs").
Start succeeds only after JetStream answers; Stop closes the connection and removes the container, which removes everything in it. Test-only: the contract test TestImportGraph refuses any production import.
Index ¶
- Variables
- func AwaitNativeDeliveryBlocked(ctx context.Context, bound time.Duration) error
- func AwaitNoStacks(ctx context.Context, bound time.Duration, scan func() string) error
- func CreateStream(ctx context.Context, js jetstream.JetStream, storage jetstream.StorageType, ...) (jetstream.Stream, error)
- func NativeDeliveryStacks() string
- func Open[T any](t testing.TB, url string, ...) T
- type FaultKV
- func (k *FaultKV) Calls() map[KVOp]int
- func (k *FaultKV) Create(ctx context.Context, key string, value []byte, opts ...jetstream.KVCreateOpt) (uint64, error)
- func (k *FaultKV) Delete(ctx context.Context, key string, opts ...jetstream.KVDeleteOpt) error
- func (k *FaultKV) FailAfter(op KVOp, err error)
- func (k *FaultKV) FailBefore(op KVOp, err error)
- func (k *FaultKV) Put(ctx context.Context, key string, value []byte) (uint64, error)
- func (k *FaultKV) PutString(ctx context.Context, key string, value string) (uint64, error)
- func (k *FaultKV) Update(ctx context.Context, key string, value []byte, revision uint64) (uint64, error)
- type Fixture
- type KVOp
- type Option
- type Shared
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyUsed = errors.New("natsfixture: fixture already started; use Restart to restart its container")
ErrAlreadyUsed is returned by a second Start. A fixture is one container's lifetime: Restart stops and starts that same container, and a second Start never creates another.
Functions ¶
func AwaitNativeDeliveryBlocked ¶
AwaitNativeDeliveryBlocked waits, up to bound, for nats.go's watch delivery to be blocked sending into its full updates buffer.
func AwaitNoStacks ¶
AwaitNoStacks waits, up to bound, for scan to return "", and returns an error carrying the last stacks it saw when it does not. A goroutine that has told its joiner it is done (a deferred WaitGroup.Done, a deferred channel close) is still in the dump until it exits, so a single read taken just after the join can see one that has already finished (#490). A goroutine that is really left behind is still there when the bound ends.
func CreateStream ¶
func CreateStream(ctx context.Context, js jetstream.JetStream, storage jetstream.StorageType, name string, subjects ...string) (jetstream.Stream, error)
CreateStream creates a stream on js with the given storage, a MaxAge of one hour, a MaxBytes of 64 MiB and DiscardOld. On a fixture, a file-backed stream keeps its messages across Restart and a memory-backed one does not; Stop's removal of the container removes both.
func NativeDeliveryStacks ¶
func NativeDeliveryStacks() string
NativeDeliveryStacks returns the stacks of goroutines inside nats.go's KV watch delivery callback, or "" when there are none.
func Open ¶
func Open[T any](t testing.TB, url string, open func(ctx context.Context, url string) (T, func(context.Context) error, error)) T
Open gives a package's tests a value connected to a NATS server URL, such as a client built with that package's own options (nats-fixture › "Connected value for a package's tests"). It calls open with url under a bounded context derived from the test's, and returns the value. When open fails, Open fails the test naming the URL and the error and registers nothing; open releases whatever it acquired before failing. On success it registers close on the test's cleanup under a fresh bounded context, reporting a close error as a test error.
Cleanups run last-registered first, so close runs before the connection check that Shared.Reset registered and before the Stop that New registered: call Open after Reset or New. Open starts no goroutine and imports nothing of this module outside internal/harness, so a package under test can use it without an import cycle.
Types ¶
type FaultKV ¶
type FaultKV struct {
// contains filtered or unexported fields
}
FaultKV wraps a real bucket so that Put, Create, Update and Delete can fail before the real call (nothing happens on the server) or after it (the write stands and the caller still sees an error, the "server applied it, client saw an error" case). PutString is a Put. Every other method, Purge included, reaches the real bucket unchanged. A fault stays set until cleared with a nil error. It is typed on jetstream.KeyValue only, so natsfixture imports no package of this module outside internal/harness.
func NewFaultKV ¶
NewFaultKV wraps bucket with no fault set.
func (*FaultKV) Calls ¶
Calls reports how many real calls each operation made, in a map the caller owns.
func (*FaultKV) Create ¶
func (k *FaultKV) Create(ctx context.Context, key string, value []byte, opts ...jetstream.KVCreateOpt) (uint64, error)
Create writes through to the real bucket unless KVCreate is faulted.
func (*FaultKV) FailAfter ¶
FailAfter makes op call the real bucket, discard its result, and return err. A nil err clears op's fault.
func (*FaultKV) FailBefore ¶
FailBefore makes op return err without calling the real bucket. A nil err clears op's fault.
type Fixture ¶
type Fixture struct {
// contains filtered or unexported fields
}
Fixture is one test's NATS server. Its methods are called from the test's own goroutine. It holds no context.Context.
func New ¶
New binds a fixture to its test and registers a Stop, under fresh bounded authority, as the test's cleanup. It makes no Docker call.
func (*Fixture) JetStream ¶
JetStream is the JetStream context on the fixture's own connection, which Stop closes; there is deliberately no accessor for that connection. Tests needing a connection of their own dial URL and close it themselves. Stop does not wait for in-flight async publishes.
func (*Fixture) Restart ¶
Restart stops and starts the fixture's own container and reconnects to it, under ctx. The container's writable layer survives, so a file-backed stream keeps its messages and a memory-backed one does not.
Before the container stops, the fixture's connection is drained, so the JetStream context and any stream, bucket or consumer handle taken from it before the restart are dead. Streams and buckets stay on the server; Stop's removal of the container removes them.
URL and JetStream return the new binding once Restart returns nil, and stay valid until the next Restart. The host port is the one Start gave Docker, and URL has stayed unchanged in every run so far (TestRestartURLDials; Docker does not promise it), but every connection to the container is lost. A caller stops what it built on the URL before Restart and starts it again after.
Restart refuses, with no Docker call, before a successful Start and once Stop has begun. A failure in a phase returns an error naming it; nothing is tried again and no replacement container is created. After a failure the fixture can no longer be restarted, and Stop removes the container.
The caller must bound ctx. Readiness after the start is one more ready line in the container's log than before it; if Docker log rotation drops earlier lines the count can fall, and the wait then runs until ctx ends and fails at the start-container phase.
func (*Fixture) Start ¶
Start starts one NATS container with JetStream from the pinned image, connects, and returns once JetStream answers. Every operation runs under ctx. A failure returns an error naming the phase (phaseError lists them), after removing whatever Start created; only a start-phase failure where Docker reports the picked host port "address already in use" tries a second container. A second Start returns ErrAlreadyUsed.
func (*Fixture) Stop ¶
Stop closes the fixture's connection and removes its container, under the caller's context. Removing the container removes every stream, bucket and consumer in it, so Stop deletes none of them first and needs no answer from the server. Once Stop begins the fixture holds no connection, so it creates nothing more and Restart refuses.
Stop returns nil only when Docker reported the container removed. If ctx ends first, or the removal fails, Stop returns the error and keeps what it has not released; a later Stop retries. The fixture never substitutes its own timeout for ctx. Stop on a fixture with nothing held (never started, a start that rolled back cleanly, or already stopped) returns nil without any call.
type Option ¶
type Option func(*Fixture)
Option configures a fixture's broker; New applies it before any Docker call.
func WithMaxPayload ¶
WithMaxPayload starts the broker with max_payload set to n bytes, so a test can reach a payload bound without building a megabyte message. Without it the broker's own default applies. Start refuses an n below 1 before any Docker call.
type Shared ¶
type Shared struct {
// contains filtered or unexported fields
}
Shared is one package's NATS server, started at the first Reset and removed by TestMain's Stop (nats-fixture › "Shared server per package", "Reset to a verified-empty server"). It retains no context.Context. The zero value is ready to use.