happenstance-testkit
The conformance suite for happenstance event store adapters. Ninety-five rules, each tracing to a MUST in the Dynamic Consistency Boundary specification and each shown to reject a named wrong implementation before it was trusted to pass.
New to happenstance? The happenstance guide explains event sourcing and dynamic consistency boundaries from the beginning, with programs you can run.
Status: early, and the reason has moved. It used to be that deliberately-broken adapters passed the suite. That is no longer true of the event-store family: every rule now has at least one wrong store in this crate's own
tests/that fails it, and a meta-test asserts each of those stores fails exactly the rules its registry row claims — so a rule that stopped discriminating is a red build rather than a green one.Five adapters have run this suite, and what each one ran differs, which is the part a prospective adapter author needs.
happenstance-sqlite's own front page still says it in the words this file has quoted since the first adapter arrived — an adapter, and it has run the suite (crates/happenstance-sqlite/src/lib.rs) — and four more can now say the same:
happenstance-sqlite— event store, projection, concurrency and model families, against a real file on disk.happenstance-cloudflare— the event-store family onwasm32-unknown-unknown, executed insidecargo xtask cion every run.happenstance-postgres— event store and projection against a live PostgreSQL 17.10, including the concurrency family at 64 contenders, which is the first time that family was cleared against a store whose writers are not serialised.happenstance-neon— event store, concurrency and projection against a live Neon endpoint over one-shot HTTP, and it ships naming one rule it does not pass, with the reason on its own front page.happenstance-ladybug— the projection family only, against the real LadybugDB driver, from phase 11 until it was retired at phase 17. It was never published —lbugdoes not render on docs.rs, this project's bar for a published crate — so that name on the registry is only a0.0.0reservation.The
ProjectionStoresuite is all eighteen rules the specification names, each with a wrong store in this crate'stests/that fails it — and the port it checks is frozen since ADR-0063. Four adapters over storage this workspace does not fully control clear it, and since ADR-0062 they stand at both ends of the batch-shape axis PS-2 asks for — three owned, buffered write sets and onesqlxtransaction. A projection rule appearing or changing is a minor bump here exactly as an event-store rule is. Several axes of the instrument portfolio also have no implementation at their far end — see the specification §6.2 and §6.5, which name them rather than summarising them.
Use
event_store_conformance!;
That expands to one #[tokio::test] per rule, so a failure names the rule rather
than a line number.
The expression builds a fixture, not a store. One fixture instance is one
isolated backing store; each connect() on it returns one handle onto that
store, and two instances share nothing. The distinction is the whole reason
Fixture is a trait rather than a closure: a bare Fn() -> S could not say
which of the two it meant, so no rule could call it twice — which foreclosed
durability, reopen and every genuinely multi-connection check at once.
A fixture also declares what it can do, as Capability associated constants. A
rule needing a capability your fixture declines still runs as a test and prints
your stated reason; it is never silently dropped from the binary, because a rule
that is absent is indistinguishable in CI output from a rule that passed.
fixtures::MemoryFixture is the worked example to read first.
Run the suite with -- --show-output if you want to see those lines. A
skipped rule is a test that passes, and libtest discards a passing test's
stdout, so a default cargo test shows you N passed and no SKIP line —
however many capabilities your fixture declined and however good your reasons
were. This is a real limit rather than a nicety: cargo test -p happenstance-sqlite --test conformance prints zero SKIP lines and the same
command with -- --show-output prints three. A fixture that declines the
optional capabilities is legal and honest, and a green run over it is not
evidence that every rule ran.
The model-based suite
event_store_model_conformance!;
A second, additive family, behind this crate's off-by-default proptest
feature and absent on wasm32-unknown-unknown. It takes the same fixture and
runs your store through generated sequences of appends, conditional appends and
reads, checking each one against a model of what the log should be — and
predicting every conditional append's outcome before it calls you.
It replaces none of the named rules and catches nothing whose content is
concurrency, durability, a second handle or the empty batch. What it catches is
the combinatorial middle the named rules cannot enumerate: query × from × backwards × limit × condition, over a log it built rather than one it chose.
Positions are never generated. The generator emits a symbolic anchor — first, middle, head, or one beyond the head — resolved at execution against what your store actually assigned, which is why the same test runs unchanged against a store whose positions are dense from 1 and one whose positions step by seven from 4,096.
The concurrency suite
event_store_concurrency_conformance!;
A third, additive, and opt-in family. It starts CONTENDERS (64)
contenders on real OS threads against one backing store and checks six things
the sequential rules structurally cannot: exactly one winner among handlers that
decided from one snapshot; four disjoint consistency boundaries admitting
exactly four commits; positions unique under concurrent appends; append
returning the caller's own last position rather than the store's head; an append
answered AppendError::Busy having left nothing behind; and a reader that never
sees a batch part-written.
A contender your store refuses as AppendError::Busy is a legitimate answer
under contention, not a failure. It counts as neither a win nor a loss, over a
floor of at least one commit per race. A refusal reported as
AppendError::Store still fails, so report a transient refusal that wrote
nothing as Busy, and an outcome you cannot vouch for as Store (ES-43).
Invoke it only if your handle is Send — the bound is
F::Store: EventStore + Send, and a !Send adapter is not expected to run it.
It is absent on wasm32-unknown-unknown, which has no threads to race on.
There is no timeout in it, anywhere, and that is deliberate. No rule in this crate reads a clock or measures elapsed time; a wall-clock deadline passes on the author's machine and fails on a loaded runner, and a flaky conformance suite is worse than none. The consequence is worth knowing before you see it: an adapter that deadlocks under contention hangs your CI job rather than failing a named rule. If a run stops with no output, that is what happened.
Two contenders' Results never meet, either. EventStore::Error carries no
Send bound, so each contender collapses its outcome to committed, rejected
or failed, here is the message before its thread ends.
The projection suite
projection_store_conformance!;
A fourth family, and the only one that checks a different port. It takes a
ProjectionFixture rather than a Fixture — one isolated projection store per
instance, each connect() one handle onto it — and expands to one test per
projection rule through its own single enumeration.
ProjectionFixture::Store is bound on ProjectionProbe, not on
ProjectionStore, and that is the load-bearing part. The probe is the write seam
the suite drives your read model through; without it, generic code holding your
batch can only commit it or roll it back, and the rule carrying this port's whole
reason for existing degenerates into a checkpoint test that a store writing
only checkpoints passes. Implement it beside your ProjectionStore impl —
it lives in happenstance-core behind the off-by-default conformance feature,
so it costs one flag on a dependency you already have and no new edge in your
dependency graph.
Pick a harness exactly as you would for the event-store family: the default arm
is #[tokio::test], emit_projection_blocking needs no runtime at all, and
emit_projection_wasm routes a skipped rule's stated reason to console_log!
rather than to stdout, which does not exist on wasm32-unknown-unknown. The
default module name differs from the event-store family's, so one file may invoke
both. fixtures::MemoryProjectionFixture is the worked example.
All eighteen rules §4.11 names, today, each with a wrong store in this
crate's own tests/ that fails it and is asserted to fail exactly the rules its
registry row declares. The port is frozen since ADR-0063, on this suite going
green against adapters at both ends of its batch-shape axis — a bar neither
fixture shipped here could have cleared, because a fixture is not an adapter.
The benchmark harness — which is not the bar
event_store_benchmarks!;
Behind this crate's off-by-default bench feature, and absent on
wasm32-unknown-unknown. It is the one family that checks nothing: it adds no
conformance rule, it changes no adapter's bar, and no result it produces can
fail a merge — there is no threshold in it, at any budget. The specification
requires performance to be measured by a separate harness which is not part of
the conformance bar, and this is that harness.
Where the four families differ:
| Family | Feature | Checks | Can fail a merge |
|---|---|---|---|
event_store_conformance! |
— | the event-store bar | yes, and that is the point |
event_store_model_conformance! |
proptest |
the same bar, over generated sequences | yes |
event_store_concurrency_conformance! |
— (opt-in, Send) |
the bar under contention | yes |
event_store_benchmarks! |
bench |
nothing — it measures | no |
Three scenarios: append throughput over a batch of n; conditional append under
k contenders, reporting the committed and rejected counts separately so that a
run in which nobody collided is legible as such; and replay of N events, once
unfiltered and once behind a tag filter. n, k and N are yours, at the call
site, because no constant here could be right for both an in-process Vec and a
file under a write lock.
You bring the clock, and with it the measurement crate. Nothing in this
crate's src/ may read one, so the harness reports counts — events appended,
batches acknowledged, committed, rejected, refused, failed, events matched on
replay — and the per-scenario wrapper is the emit parameter, exactly as it is
for the other three families. criterion, divan or a line of CSV goes in
your dev-dependencies; this crate's stay happenstance-core and
futures-core. tests/memory_benchmarks.rs writes such an emitter and runs the
whole family against fixtures::MemoryFixture on every cargo test --features bench, so the harness ships having been executed rather than merely compiled.
Why this exists as a published crate
A claim about behaviour is worth exactly as much as the test that checks it. Publishing the suite means an adapter author outside this repository can make the same claim on the same terms, and it means the reference store is measured by the same instrument as everyone else.
Two rules govern what goes in it, both learned expensively:
A rule no adapter can fail is decorative. Before a rule is added, a plausible
wrong implementation it rejects has to be named — and written into
tests/mutation_coverage/mutants.rs, with a row in that file's sibling
REGISTRY declaring the exact set of rules it fails. (A concurrency rule's
wrong store goes in tests/mutation_coverage/racers.rs and RACERS, because a
store that fails only a racing rule fails none of the named rules and cannot have
a REGISTRY row. A projection rule's goes in the sibling registry under
tests/projection_mutation_coverage/, which is a second registry rather than a
second table in the first one — a count printed beside the wrong target is a
number about neither.) That is not a convention:
mutation_coverage::every_rule_has_a_mutant fails until the row exists, so the
rule is demonstrated to fail before it is trusted to pass, and
projection_mutation_coverage::every_projection_rule_has_a_mutant says the same
thing for the other port. CONTRIBUTING.md's "Conformance rules" section is the
checklist.
Never assert on literal position values. The specification permits gaps, and a
conformant adapter may leave them. Rules compare against positions the store
actually assigned — and GappedPositionStore, a conformant store assigning
positions in steps of seven from 4,096, is what fails a rule that forgets.
Versioning
Adding a rule is a semver-minor change that can turn a passing adapter's CI red. Treat that as a breaking change in practice and pin this crate exactly. Its version is independent of the rest of the workspace for that reason.
The conformance emitters an invocation names — emit_tokio, emit_blocking,
emit_wasm and their projection, model and concurrency siblings — are public
API, and renaming or removing one is a major release (CF-41). A macro whose name
starts with __ is not promised and may change in any release.
Minimum supported Rust version
Rust 1.97.1, the rust-version this crate declares
(ADR-0029).
After 1.0.0 the floor rises only in a minor release, never a patch; only to a
Rust stable at least six months old on the day that minor ships; and always with
a CHANGELOG.md entry naming the old floor, the new one and what forced it
(ADR-0067).
Before 1.0.0, a rise ships in a 0.x minor, which a "0.x" requirement never
resolves across
(ADR-0037).
From 1.0.0, what keeps a rise from reaching you is your workspace's resolver,
not this crate's: under resolver = "3", the default for an edition-2024 root,
or with resolver.incompatible-rust-versions = "fallback" set, Cargo prefers
the newest version whose rust-version your lowest package.rust-version (or
your rustc, if you declare none) satisfies, and cargo update says so by
printing to latest Rust 1.xx compatible versions where resolver 2 prints to
latest compatible versions. On resolver 2, only your lockfile holds you back.
Licence
MIT OR Apache-2.0.