Skip to main content

Crate happenstance_testkit

Crate happenstance_testkit 

Expand description

The DCB conformance suite for happenstance event store adapters.

“Storage agnostic” is a claim about behaviour, and a claim about behaviour is worth exactly as much as the test that checks it. This crate is that test. An adapter in this workspace is not considered to exist until it invokes event_store_conformance! and passes.

§Usage

In your adapter’s tests/ directory or a #[cfg(test)] module:

happenstance_testkit::event_store_conformance!(MyFixture::new());

The macro takes an expression that builds a fixture — see Fixture — and expands to one #[tokio::test] per rule, so a failure names the rule that broke rather than reporting “conformance failed”.

Your crate needs tokio with the macros and rt features in dev-dependencies.

§What a fixture is, and why it is not a closure

A fixture instance is one isolated backing store; each connect on it returns one handle onto that store. The distinction is the whole of Fixture’s reason to exist. Its predecessor was a bare Fn() -> S that documented “a fresh, empty store” while accepting || store.clone(), so a rule could not call it twice without knowing which it had been given — and that one ambiguity foreclosed durability, reopen, and every genuinely multi-connection rule.

Rules are handed impl AsyncFn() -> F, not a made fixture. A rule that can make two isolated stores can check that they are isolated, which matters because pointing every fixture at one temporary directory is an adapter’s mistake and no test over the testkit’s own fixture could see it.

A fixture also declares what it can do, as Capability constants. A rule requiring a capability the fixture declines is still emitted as a test; it returns RuleOutcome::Skipped and the harness prints the fixture’s stated reason. #[cfg]-ing it out instead would make a skipped rule indistinguishable in CI output from a passing one.

Pass -- --show-output 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 reports N passed and no SKIP line whatever your fixture declined. The emitted test is what makes the skip reachable; the flag is what makes it read. A green run over a fixture that declines the optional capabilities is not evidence that every rule ran, and RuleOutcome::report says the same thing where the mechanism is.

fixtures::MemoryFixture is the reference implementation and the one to read before writing your own.

§Choosing a harness

#[tokio::test] is a default, not a requirement. The per-test wrapper is a parameter — an emitter macro — because the testkit is in no position to know which runtime an adapter is tested on, and a cfg ladder in here would mean every new runtime needs a testkit release. The emitters that ship are the rows of this table, and the rows are the count: a written-out number is falsified by an edit that never touches it, and this paragraph said three through the nine that landed after it.

FamilyEmitterWrapperAdapter needs
event storeemit_tokio! (default)#[tokio::test]tokio with macros, rt
event storeemit_blocking!#[test] + block_onnothing
event storeemit_wasm!#[wasm_bindgen_test]wasm-bindgen-test
projectionemit_projection_tokio! (default)#[tokio::test]tokio with macros, rt
projectionemit_projection_blocking!#[test] + block_onnothing
projectionemit_projection_wasm!#[wasm_bindgen_test]wasm-bindgen-test
modelemit_model_tokio (default)#[tokio::test]tokio with macros, rt
modelemit_model_blocking#[test] + block_onnothing
concurrencyemit_concurrency_tokio (default)#[tokio::test(flavor = "multi_thread")]tokio with macros, rt, rt-multi-thread
concurrencyemit_concurrency_blocking#[test] + block_onnothing
benchmark__emit_benchmark_tokio (default)#[tokio::test]tokio with macros, rt
benchmark__emit_benchmark_blocking#[test] + block_onnothing

The model and concurrency rows are written out rather than linked because their macros exist only behind the proptest feature and off wasm32-unknown-unknown respectively, and a link from this page would break in the builds that leave them out.

happenstance_testkit::event_store_conformance!(
    mod_name = dcb_conformance_blocking,
    emit = happenstance_testkit::emit_blocking,
    fixture = MyFixture::new()
);

What is promised, and what __ means here. CF-23 requires you to name an emitter, so the names you may be required to write are public API. Every conformance emitter in that table — each row but the benchmark pair — is an ordinary documented macro, and renaming or removing one is a major release of this crate (CF-41, ADR-0076). A double-underscore prefix means the opposite, and nothing promised carries one: the benchmark pair stays #[doc(hidden)] because a benchmark is not the bar (CF-34), and so does __rule_names, which wraps no test and exists for this crate’s own meta-tests. Either may change in any release.

A runtime none of those cover needs no change here: write a macro_rules! that accepts a comma-separated list of identifiers and hand it to for_each_event_store_rule! yourself. Start by copying a shipped emitter’s body, because it has to name what the suite macro defines around it — a __conformance_fixture function and each family’s rules under $crate::__private — and those are the suite’s internals rather than a promise: a hand-written emitter is yours to keep in step, and this crate’s changelog says when one of them moves.

§Where the rule set lives

In exactly one place: for_each_event_store_rule!. Every harness, and the no_orphan_rules meta-test, is built by invoking it. A rule that exists in rules without appearing there is a rule nothing runs, which is the failure the meta-test is for.

“Exactly one place” is per rule family (CF-22), and there are four.

projection_store_conformance! is the fourth, and the only one that checks a different port. It takes a ProjectionFixture rather than a Fixture — one isolated projection store per instance — and expands to one #[tokio::test] per projection rule through its own enumeration, for_each_projection_store_rule!, beside the rules it names. Pick a harness exactly as you would for the event-store family: the default arm is tokio, 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 dcb_conformance, so one file may invoke both suites.

An adapter reaches it by implementing ProjectionProbe beside its ProjectionStore impl — the write seam a suite that has never heard of the adapter drives its read model through, in happenstance-core behind the off-by-default conformance feature.

It declares what it can do in the same vocabulary, and there is deliberately no second one: ProjectionFixture carries Capability constants, a rule it declines returns the same RuleOutcome::Skipped and prints the same one-line SKIP shape, so an author reading one CI log never has to learn two. Three constants, all answered deliberately — SECOND_HANDLE, which is a MUST because every rule in the family reads back through a fresh handle; RESET_REFUSAL, which a store with no protection policy declines honestly; and COMMIT_FAULT, which is how a store says whether it can make a commit report failure — the only way to observe PS-1’s second conjunct, and something no caller can do from outside. A fourth switch, READS_THROUGH_BATCH, is on the probe rather than on the fixture, because whether a batch can be read through is a property of the batch type rather than of the fixture’s environment.

event_store_model_conformance! generates operation sequences and checks the store against a model of the log rather than against a worked example. It carries its own enumeration, for_each_model_rule!, beside the rules it names — the model module says why, and what it is blind to. It is additive: it replaces no rule in the table below, and it catches no defect whose content is concurrency, durability, a second handle, or the empty batch.

event_store_concurrency_conformance! runs concurrency::CONTENDERS contenders on real threads against one backing store. It is opt-in: an adapter invokes it separately, its bound is F::Store: EventStore + Send, and a !Send adapter cannot invoke it and is not expected to. It is additive too, and pointedly so — it does not retire rules::racing_conditional_appends_elect_one_winner, which fixes the semantics a race must have; what it adds is a second caller, so that a probe followed by an insert stops being indistinguishable from an atomic check-and-write. There is deliberately no timeout anywhere in it; the concurrency module says why, and the answer is CF-33.

event_store_benchmarks! is a fourth macro family and the only one that is not a bar. It lives in bench, behind this crate’s off-by-default bench feature and absent on wasm32-unknown-unknown, and it measures the three things phase 8 needs measured: append throughput over a batch of n, conditional append under k contenders reporting the committed and rejected counts separately, and replay of N events run both unfiltered and behind a tag filter — with n, k and N supplied at the call site. It adds no conformance rule, changes no adapter’s bar, and can never fail a merge: CF-34 says performance is measured by a separate harness which is not part of the conformance bar, and this is that harness. There is no threshold in it at any budget, and no clock either — CF-33 forbids one anywhere in this crate’s src/, so the harness reports counts and the emitter reports durations, which puts criterion, divan or a CSV writer in the caller’s dev-dependencies and leaves this crate’s two.

None of the model, concurrency or benchmark families’ names is an intra-doc link, and all three paragraphs above spell them plainly on purpose. Each module is absent on some configuration this crate is documented under, and rustdoc treats an unresolved link as a hard error: model is behind the off-by-default proptest feature, so a link would break cargo doc with default features; concurrency is #[cfg(not(target_arch = "wasm32"))], so a link would break cargo doc --target wasm32-unknown-unknown; bench is behind a feature and a target gate, so it would break both. That is the D13 failure this workspace has already paid for once.

An earlier version of this paragraph said the concurrency module “needs no feature, so linking into it is safe on any target that has it” — true, and misleading in the same sentence, because wasm32-unknown-unknown is the target this crate’s whole two-flavour story exists for and is the one that does not have it. An intra-doc link to concurrency::CONTENDERS was written on that reasoning and did fail, with no item named concurrency in scope. Nothing in cargo xtask ci caught it: the gate runs cargo doc for the host and cargo build/cargo check for wasm32, and never rustdoc for wasm32. The absence of that step is recorded here rather than left as the reason this is green — adding it is a candidate for phase 4, and until then this discipline is the whole of the protection.

The projection family’s names are links, and the difference is the whole of the rule rather than an inconsistency: projection is declared unconditionally — no feature, no target gate — so there is no configuration this crate is documented under in which the target is absent. A link is safe exactly when the item cannot disappear.

§Writing a projection adapter from outside this workspace

The bar here is held for an author this repository did not write, and the extension surface is exactly two items: this crate’s projection_store_conformance! and happenstance-core’s ProjectionProbe. Six steps, in this order.

1. Take the two dependencies, and note which is which.

[dependencies]
happenstance-core = "0.7"

[features]
conformance = ["happenstance-core/conformance"]

[dev-dependencies]
happenstance-testkit = "=0.7.0"
tokio = { version = "1", features = ["macros", "rt"] }

The two requirements are deliberately different shapes. They named 0.2.0-alpha.1 in full until 0.2.0 shipped, because a requirement naming no pre-release never matches a pre-release version and version = "0.2" — the line a Rust author writes without thinking — resolved to nothing at all. That is over: both crates are on the registry at a stable number and an ordinary caret works. xtask’s recipe_fence_resolves is what moved this block rather than letting it go quietly stale, which is the whole reason that check exists.

The = on this crate is a recommendation with a reason (CF-30). Adding a conformance rule is a semver-minor change that can turn a passing adapter’s CI red, so treat it as a breaking change in practice and pin this crate exactly. An exact pin is normally poor practice in a Rust library because it propagates — a pinned dependency of a library constrains every downstream lockfile and manufactures duplicate-version conflicts — and that is exactly why the recommendation needs stating rather than assuming: Cargo does not resolve a non-root package’s dev-dependencies at all, so this one propagates to nobody, and what it buys you is choosing when you take a new bar instead of finding out from a red run you cannot attribute.

The [dependencies] and [features] halves of that block belong to the port rather than to this crate, and they are a copy of the fence on happenstance_core::ProjectionProbe’s own page rather than a second opinion: xtask’s feature_cost_is_stated fails if the two drift. A reader of step 1 needs one manifest and not two half-manifests on two pages, which is why the copy is here at all.

The dependency line names no feature, because your impl ProjectionStore needs none: the port and every type it names are unconditional on the contract crate since ADR-0063. (From 0.2.0 until then the line had to carry unstable-projection; 0.3 kept that feature, empty, so such a line still compiled, and 0.4.0 removed it — delete it from the line when you move.) conformance is forwarded from a feature of your crate instead, because the impl ProjectionProbe lives in src/ under #[cfg(feature = "conformance")] and a crate cannot cfg on a dependency’s feature.

conformance costs no crate, no graph edge, and implies no other feature — not std, not memory. This page has said that sentence before and had it be false: while the port was gated, conformance implied unstable-projection, because ProjectionProbe is defined inside the module that feature closed, and Cargo’s feature unification is global and additive — a feature turned on anywhere in a graph is on for everybody in it, so turning conformance on in [dependencies] handed an unfrozen port to every application downstream of your adapter. The sentence is true again because the gate is gone, and xtask’s feature_cost_is_stated holds it to the manifest in both directions. The reason to forward rather than turn on has not changed: it gives the choice back to whoever builds your adapter, and examples/outside-projection-adapter in this repository writes exactly this manifest, with its own tests/ failing if it stops.

What the dev-dependency costs you is a bigger happenstance-core under cargo test than under cargo build, and it is not your build that finds out. This crate depends on happenstance-core with std, memory and conformance on. Cargo’s resolver deliberately does not unify a dev-dependency’s features into cargo build and does unify them into cargo test, so your src/ compiles against a larger contract crate whenever the suite is in the graph.

It bites the population CF-20 exists for and nobody else, which is why it is easy to ship: the gap is only a gap if you wrote default-features = false, because otherwise std and memory are already yours. If you did — the no_std or wasm32 author — then naming a memory-gated item in a helper, MemoryEventStore, say, is green under cargo test and error[E0432]: unresolved import happenstance_core::MemoryEventStore under cargo build. Measured in this repository against examples/outside-projection-adapter, not reasoned from the manual. Build your library the way a consumer will — cargo build -p your-adapter, no --all-targets — before you tag a release. This crate is a dev-dependency and stays one.

2. Implement ProjectionStore for your store, in src/.

3. Implement ProjectionProbe for the same type, in src/ beside it — not in tests/. It is the write seam a suite that has never heard of your store drives your read model through, and its home is the contract crate for a reason you meet immediately if you put the impl in the other obvious place: tests/ is a different crate, where neither the trait nor your type is local, and the orphan rule answers error[E0117].

4. Write a ProjectionFixture in your tests/. One instance is one isolated backing store; each connect is one handle onto it. The fixture type is defined there, so this impl belongs exactly where the last one did not.

5. Say what your store cannot do, and why. Its three Capability constants are required rather than defaulted, so no author is left un-asked. A rule you decline is still emitted as a test: it returns RuleOutcome::Skipped carrying your own sentence, because a rule absent from a binary is indistinguishable in CI output from a rule that passed.

6. Invoke the suite. One line, and you name no rule.

happenstance_testkit::projection_store_conformance!(MyFixture::new());

That line expands in your crate, which is why the expansion never assumes what you have in scope: it spells the fixture trait as $crate::__private::ProjectionFixture, through a hidden module this crate keeps for the purpose, so the invocation works whether or not you imported the trait and whatever you renamed the dependency to. You never name that module yourself, and it is the one part of this page that is invisible until it is missing.

Every item path in every exported expansion goes through it, and that sentence used to be an aspiration rather than a fact: four of the five suite macros reached past the module for concurrency::ConcurrentFixture, bench::BenchmarkParams, block_on and each family’s rules, which froze those module paths for callers who had named nothing at all. tests/macro_expansion_paths.rs is what makes it a fact — the only exception is a macro name, because macro_rules! lives in a flat crate-root textual namespace and is not reachable through a module in the first place.

A green run then means what the rule table below says and no more; a red one names the rule that broke. examples/outside-projection-adapter/ in this repository is an adapter written against this page and nothing else, kept in the tree so the page cannot quietly stop being sufficient.

§What is checked

Every rule traces to a MUST in the specification, plus the properties an adapter can plausibly get wrong:

AreaRules
The fixture contracttwo fixture instances share nothing; two handles onto one store observe each other’s appends, on the read side and through an append condition; an acknowledged write survives a reopen
Query semanticstypes OR within an item; tags AND within an item; items OR across a query; Query::all; supersets match, partial overlaps do not; an untagged event is still matched; nothing is yielded twice; item order does not change the result
Read optionsfrom is inclusive; backwards reverses order; limit truncates matches, not scanned rows; every option composes with a multi-item query; a store nobody has written to reads as empty
Positionsunique; strictly monotonic; gaps permitted
Appendatomic; a rejection changes nothing; a batch interrupted by an injected fault lands whole or not at all; an empty batch is refused, and refused before the condition is evaluated; the returned position is the last written
Value edgesa zero-length payload survives; metadata: None and Some(<empty>) stay two values; an identifier at the 255-byte bound round-trips and still matches itself; non-ASCII identifiers do too; and the four guaranteed minima — 65,536 bytes of payload, 64 tags, a 128-item query, a 128-event batch
Append conditionsthe full matrix, including the exact after boundary, tags on both sides of the verdict, an empty store, and after beyond the head
Concurrencyracing appends with overlapping conditions — exactly one wins. The opt-in third family adds contention on real threads: one winner of N contenders, K disjoint boundaries admitting exactly K commits, positions unique under concurrent appends, append returning the caller’s own last position rather than the head, and a reader that never sees a partial batch
Re-entrancytwo append futures on one handle both complete and exactly one wins; a live read stream does not block an append
Position visibilitytwo append futures interleaved by hand on one thread: nothing becomes visible below a position a reader has already observed
Projections (a second port, a fourth family)a commit advances the projection’s checkpoint to the position it was given, read back through a fresh handle; and the read-model write and the checkpoint write become durable together or not at all, never one — the invariant ProjectionStore exists for — and, behind REOPEN, that both survive every handle being dropped and the storage reopened. All nineteen rules §4.11 assigns to an adapter’s own suite, including fresh_projection_has_no_checkpoint — PS-38’s second sentence, which ADR-0030 minted rather than widening [FROZEN] PS-19 to reach it — and projection_ids_round_trip_by_bytes, PS-39’s, which holds a store to keying a checkpoint on the id’s exact bytes

§Stores that misbehave on purpose

The suite above checks an adapter. These five check the caller, and they exist because every store an application author can reach today behaves perfectly: the reference store names the conflicting event on every violation and assigns dense positions from 1, and never tells a rollback from a drop, so whole classes of caller bug are not merely hard to test — the input that separates a correct caller from an incorrect one never occurs.

InstrumentProducesRejects
FaultyStore / SendFaultyStorea violated append naming no conflicting event, and a read that fails at its first polled itema retry loop that branches on conflicting_position being Some
GappyMemoryStore (memory)positions with a caller-chosen stridea read-model handler that computes its next position by adding one
RecordingProjectionStore (memory)a log that tells a rollback from a bare drop, and injected begin and commit failuresa projection runner that drops a write set bare, or ends it after another view commits
WithholdingStorea log with an arbitrary retained set, whose withheld events no port value revealsa runner or ingest path that infers completeness from any port value (ES-39, ES-40)

The faulty wrapper comes in two flavours, two types, for the coherence reason Fixture’s page records; the recording and withholding stores are bare only. All four run their port’s conformance suite themselves — the faulty and recording wrappers unarmed, so a disarmed one is proved not to be lying; the gapped store with its stride, so its gaps are a freedom the specification grants; the withholding store pruned of its history, so pruning is invisible.

The two memory stores are named in plain text, not linked: a link behind a feature breaks some doc builds. Each page carries the doc_cfg badge that says so.

§Which flavour to test

The macro binds on EventStore, the flavour with no Send bound, so it accepts both kinds of adapter. If your adapter implements SendEventStore — as every native one should — you get that bound checked for free, because SendEventStore implies EventStore.

Modules§

benchbench
The benchmark family: a fourth macro family, and deliberately not a bar.
concurrencyNon-WebAssembly
The parallel half of the suite: contenders on real threads, racing for the same consistency boundary.
fixtures
Small builders shared by the conformance rules, the reference Fixture implementation, and the property-test generators.
modelproptest
The model-based half of the suite: a store driven through a generated sequence of operations, checked against a model of what the log should be.
projection
The projection store rule family: its rules, its single enumeration, its three emitters and its entry macro.
rules
The conformance rules. See the crate documentation for the map of what each group covers.

Macros§

emit_blocking
Emits one plain #[test] per rule, driven by block_on.
emit_concurrency_blockingNon-WebAssembly
Emits one plain #[test] per concurrency rule, driven by block_on.
emit_concurrency_tokioNon-WebAssembly
Emits one #[tokio::test(flavor = "multi_thread")] per concurrency rule.
emit_model_blockingproptest
Emits one plain #[test] per model rule, driven by block_on.
emit_model_tokioproptest
Emits one #[tokio::test] per model rule.
emit_projection_blocking
Emits one plain #[test] per projection rule, driven by block_on.
emit_projection_tokio
Emits one #[tokio::test] per projection rule.
emit_projection_wasm
Emits one #[wasm_bindgen_test] per projection rule.
emit_tokio
Emits one #[tokio::test] per rule.
emit_wasm
Emits one #[wasm_bindgen_test] per rule.
event_store_benchmarksbench
Generates the benchmark harness for an event store adapter.
event_store_concurrency_conformanceNon-WebAssembly
Generates the concurrency conformance suite for an event store adapter.
event_store_conformance
Generates the full DCB conformance suite for an event store adapter.
event_store_model_conformanceproptest
Generates the model-based conformance suite for an event store adapter.
for_each_concurrency_ruleNon-WebAssembly
Hands the complete concurrency rule set to $callback.
for_each_event_store_benchmarkbench
Hands the complete benchmark scenario set to $callback.
for_each_event_store_rule
Hands the complete event store rule set to $callback.
for_each_model_ruleproptest
Hands the complete model rule set to $callback.
for_each_projection_store_rule
Hands the complete projection store rule set to $callback.
projection_store_conformance
Generates the projection conformance suite for a ProjectionStore adapter.

Structs§

Capability
Whether a fixture supports one optional operation, and if not, why not.
FaultyStore
Wraps a store so it can be made to fail on demand — the !Send flavour.
GappyMemoryStorememory
A conformant store whose positions advance by a stride, never by one.
RecordingBatchmemory
A memory write set that logs how it ended, including a bare drop.
RecordingProjectionStorememory
A MemoryProjectionStore that logs every begin, commit, reset, rollback and bare drop of its write sets, in call order.
SendFaultyStore
Wraps a store so it can be made to fail on demand — the Send flavour.
WithholdingStore
Wraps a store so that it holds only part of its own log: a suffix, or a scattered subset with survivors between the holes.

Enums§

Armed
What Fixture::arm_held_above_frontier reports it did.
BatchCallmemory
One thing that happened to a write set, by the serial begin gave it.
FaultyStoreError
Why a read or an append through a faulty wrapper failed.
RecordingStoreErrormemory
Why a RecordingProjectionStore call failed.
Removed
What Fixture::remove_outside_port reports it did.
Reopened
What ProjectionFixture::reopen reports it did.
RuleOutcome
What a conformance rule did.
Settled
What Fixture::settle_frontier reports it did.
WithholdError
Why a WithholdingStore::withhold or WithholdingStore::withhold_where call withheld nothing.

Constants§

NO_BATCH_READ_PATH
The capability name a rule reports when an adapter’s batch offers no read path at all.
NO_BATCH_READ_PATH_REASON
The reason a rule reports when an adapter’s batch offers no read path.
NO_CEILING_REASON
The reason a rule reports when a fixture states no ceiling on any store limit.
NO_STORE_LIMITS
The capability name a rule reports when a fixture states no ceiling at all on any store limit.
UNSTATED_COMMIT_FAULT
What ProjectionFixture::COMMIT_FAULT says when a fixture does not.
UNSTATED_HELD_ABOVE_FRONTIER
What Fixture::HELD_ABOVE_FRONTIER says when a fixture does not.
UNSTATED_MID_BATCH_FAULT
What Fixture::MID_BATCH_FAULT says when a fixture does not.
UNSTATED_PROJECTION_REOPEN
What ProjectionFixture::REOPEN says when a fixture does not.
UNSTATED_PROJECTION_SECOND_HANDLE
What ProjectionFixture::SECOND_HANDLE says when a fixture does not.
UNSTATED_READ_FAULT
What Fixture::READ_FAULT says when a fixture does not.
UNSTATED_REMOVAL
What Fixture::REMOVAL says when a fixture does not.
UNSTATED_RESET_REFUSAL
What ProjectionFixture::RESET_REFUSAL says when a fixture does not.

Traits§

Fixture
One isolated backing store, plus the ways a rule is allowed to reach it.
ProjectionFixture
One isolated projection store, plus the ways a projection rule is allowed to reach it.

Functions§

block_on
Drives a future to completion on the current thread.