taskstest

Documentation

Overview

Package taskstest publishes the WorkerDispatcher conformance suite (ADR-003 §4.2): every dispatcher — the bundled local queue, or an adapter over Redis, SQS or a Camunda-style external-task API — proves the same fetch-and-lock contract by calling Conformance from a one-line test.

Scope, and what is deliberately outside it:

• **Lock EXPIRY is not asserted.** A dispatcher's clock is its own (localdispatcher takes a clock.Clock; a remote queue's deadline lives in the server), so a portable suite has no way to advance it. Testing expiry by sleeping would make the suite slow and flaky in exchange for an assertion each adapter can make better itself.
• **Retry, back-off and fault CLASSIFICATION are not asserted.** Mapping a Fault to a BPMN outcome is the engine's ErrorMapper, reached through a bound seam; a dispatcher that merely forwards the Fault is conformant.

What remains is the queue contract itself: enqueue, exclusive fetch-and-lock, topic filtering, holder-only operations, and the four terminal reports reaching the completion sink exactly once.

Index

• func Conformance(t *testing.T, factory Factory)
• func SetWaits(w WaitConfig) func()
• type Factory
• type WaitConfig
  • func Waits() WaitConfig

Functions

func Conformance

func Conformance(t *testing.T, factory Factory)

Conformance runs the WorkerDispatcher contract against factory-built dispatchers. Adapter tests are one-liners:

func TestConformance(t *testing.T) {
	taskstest.Conformance(t, func(t *testing.T) tasks.WorkerDispatcher {
		return localdispatcher.New(clocktest.New(time.Now()), time.Minute)
	})
}

A dispatcher that implements tasks.SinkBinder gets the terminal-report subtests too; one that does not skips them, since without a sink there is no way to observe where a report went.

func SetWaits

func SetWaits(w WaitConfig) func()

SetWaits widens or narrows the suite's time bounds for the current test binary, returning a function that restores them.

It is process-global and NOT safe to call from a parallel test. Set it once, before Conformance.

Types

type Factory

type Factory func(t *testing.T) tasks.WorkerDispatcher

Factory builds a fresh, empty WorkerDispatcher under test. It is called once per subtest, so implementations must return isolated queues (for a shared backend: a unique topic prefix or a wiped namespace).

type WaitConfig

type WaitConfig struct {
	// Fetch bounds a FetchAndLock that MUST return. A hang-breaker.
	Fetch time.Duration

	// Settle is how long a terminal report is given to reach the sink.
	Settle time.Duration

	// Absence bounds a fetch that must return NOTHING. Every such assertion
	// pays it in full, and it is the one bound that can fail a CORRECT but slow
	// adapter — one slower than this returns empty for the wrong reason.
	Absence time.Duration
}

WaitConfig is the suite's time bounds. A zero field keeps the current value.

func Waits

func Waits() WaitConfig

Waits returns the suite's current time bounds, so a caller can widen them for a backend this suite's defaults would falsely reject.

The defaults suit an in-process queue. An adapter over a remote one does not: a dispatcher with a 20-second long-poll is CORRECT and would fail here for reasons unrelated to the contract. The suite is published for exactly those adapters (NFR-3), so the bounds are theirs to set.