Chronicle read-model specifications
ReadModelScenario<TReadModel> runs a projection or a reducer in-process
against a sequence of events. No Chronicle server, no database, no network — the
events go in, the materialized instance comes out.
Pure reducer decisions use Specification plus a direct method call by
default, with the event and current state supplied explicitly (for a self model,
Model.Reduce(@event, current)). Add
ReadModelScenario<TReadModel> only where declarative projection behavior,
event dispatch, filtering, metadata or read-model wiring contribute proof.
Follow the scenario selection and cost rule:
use one scenario class per read model and per distinct event sequence the
projection declares (lifecycle, join, children with two keys, removal), with many
read-only assertions on one shared setup, and keep shared lifecycle enabled. Cover
each declared sequence; do not create a class per property or mapping attribute.
Never replace the engine with a substitute store as projection proof. Reducer
transitions are plain calls; the scenario proves dispatch and filters. Measure scenario cost with TRX durations
using running-specs.md.
For a read-model scenario specification the Given is the act. There
is no separate When: seeding the events is what makes the projection run.
Product sources
| Package | Purpose |
|---|---|
Cratis.Chronicle.Testing |
Source/Clients/Testing/ReadModels/ReadModelScenario.cs: scenario selection, self and nominated reducers |
Cratis.Chronicle |
Source/Clients/DotNET/Reducers/{SelfReducerMethods,RegisteredReducerReadModel}.cs, ReadModels/ReadModelBuilderOwnership.cs: supported forms and ownership |
Cratis.Specifications.XUnit |
The Specification base and the ShouldXxx assertions |
Source: Source/Clients/Testing/ReadModels/ in Cratis/Chronicle.
dotnet add package Cratis.Chronicle.Testing
Reverify against the Chronicle repository before claiming support for another version.
Route near misses
- Event appending, constraints, or the event log's own behavior: use
cratis-chronicle-event-specifications. - A command running through validators,
Provide()andHandle(): usecratis-application-slice-specifications. - Deciding what the read model or projection should be: use
cratis-chronicle-read-model,cratis-chronicle-projection, orcratis-chronicle-reducer. - The scope is model-first (its read-model
specificationblocks andthen readmodelrows are the contract). Decide this with the decision rule incratis-screenplay-modeling-lifecycle: model-first only when an accepted model under the model root covers this scope, or the repository is opted in (opted in pergeneral.md"Model first"; wherecratis-screenplay-modeling-lifecycleis installed, run itsscripts/model-first-status.mjs); framework, infrastructure, client, adapter and not-opted-in brownfield work stays code-first. Opted in but no model for this scope: model it first (cratis-screenplay-discovery, thencratis-screenplay-slice-design) before writing specifications. If those Screenplay skills are not installed, say so and stop; never author.playfrom memory. Never edit Stage-managed output, and never change a model specification to match existing code. Author model specifications withcratis-screenplay-specificationsandcratis-screenplay-scenario-coverage; check finished code against them withcratis-application-slice-conformance.
When you need this
- A reducer's event dispatch, filtering or read-model wiring needs proof.
- A fluent
IProjectionFor<T>maps event properties onto read-model properties. - A model-bound projection —
[FromEvent<T>],[SetFrom<T>],[Key]— maps correctly. - A boundary matters: the first event, several events, several event sources.
Step 1 — Create the scenario
Create one scenario for the read model's specification class. Share setup among its read-only facts, never across specification classes.
// Default, empty initial state
var scenario = new ReadModelScenario<MyReadModel>();
// With a baseline
var scenario = new ReadModelScenario<CartSummary>(new CartSummary { ItemCount = 10 });
Further constructors take a service provider, a Defaults, or both, alongside
the initial state. Use the named-parameter form when you need only one of them:
new ReadModelScenario<T>(initialState: null, serviceProvider: services).
Scenarios implement IDisposable; call _scenario.Dispose() in Destroy().
WithProjection(Action<IProjectionBuilderFor<T>>) supplies an inline projection
and wins over discovery, including a discovered reducer. Per-run Defaults
can take a client artifacts provider, service provider and options;
InMemoryClientArtifactsProvider and ChronicleOptions.ExplicitArtifacts let a
specification isolate registrations without global discovery. Nominate a plain
instance reducer with options.ExplicitArtifacts.RegisterReducer<PlainReducer>()
before constructing per-run Defaults(artifacts, serviceProvider, options).
The same API accepts a self model; default discovery needs no marker. Do not
mutate Defaults.Instance across independent runs.
Step 2 — Seed the events
await scenario.Given
.ForEventSource(myId)
.Events(new SomeEvent("value"), new SomeOtherEvent(42));
Chain a second ForEventSource for another event source — a cross-stream
projection is seeded by giving each contributing stream its own call:
await scenario.Given.ForEventSource(orderId).Events(new OrderCreated("order-1"), new ItemAdded(9.99m));
await scenario.Given.ForEventSource(anotherOrderId).Events(new OrderCreated("order-2"));
ForEventSourceId(...) is an alias for ForEventSource(...). The builder also
offers .ReadModel(instance) to pin a materialized instance for code that calls
IReadModels.GetInstanceById rather than deriving it from events.
For a filtered reducer, seed the routing metadata as well:
Given.ForEventSource(id).OnStream(eventSourceType, eventStreamType, eventStreamId).Events(...).
[EventSourceType], [EventStreamType] and [FromEventSource<T>] filters are honored;
unrouted seeds no longer reach a handler for another stream. Child-before-parent
writes are retried when the parent later arrives; decimal seeds retain exact values.
Requires Chronicle 19.53.1 for nested child IdentifiedBy paths to update/remove
the existing child rather than duplicate it, and 19.53.2 for in-memory child joins
to preserve the root and all matching siblings. Check the testing/client versions;
older in-memory outcomes can diverge from persistent sinks. Cover root properties,
sibling preservation and nested child update/removal, not only one joined value.
Requires Chronicle 19.58.0 for reducer tag filters and seeded tags/source/stream
metadata to match production; include matching and excluded events.
Events are processed in the order supplied. Seed before asserting, and do not
try to separate a "setup" Given from an "act" Given — for a read model they
are the same phase.
Step 3 — Assert on the instance
_scenario.Instance!.Total.ShouldEqual(14.49m);
_scenario.Instance!.Name.ShouldEqual("Widget");
Instancematerializes lazily on first access and isnullwhen nothing was produced. It throwsMultipleInstancesMaterializedwhen the seeded events produced more than one — a single answer would be ambiguous.Instancesis the whole dictionary keyed by event-source id, andInstanceForEventSourceId(id)picks one. Use those when the specification deliberately seeds several sources.- There are no
Should*assertions onReadModelScenario, as members or as extensions. Assert onInstancewith the ordinaryShouldXxxassertions — and note the shipped name isShouldEqual, notShouldBe.
Do not pre-emptively skip an assertion. Assume scalar concept, enum, and identifier properties populate; when one does not, investigate the projection rather than the harness. Skip only on a reproduced harness gap, and put the specific reason in the skip message.
For pre-seeding instances, ProcessAppendedEvents(...) and schema-generator
sharing, read seeded state and appended-event processing.
These are setup/processing surfaces, not proof of kernel persistence or replay.
Step 4 — Know what the scenario picked
WithProjection overrides discovery, including a reducer. Otherwise:
- An explicit projection recipe for
TReadModelsuppresses reducer selection. - A registered reducer handler targeting it: a self-reducing model, a
separate
IReducerFor<TReadModel>, or an explicitly nominated plain instance class. The scenario uses the store's handler catalog, not its own interface scan. Self signatures and registered event membership still matter. - A fluent projection implementing
IProjectionFor<TReadModel>. - Model-bound attributes directly on
TReadModel, then the matching model-bound entry in the artifacts provider.
If no handler exists, processing throws NoReadModelHandlerFound. Classic
reducer precedence does not authorize competing self-model builders: the store
rejects those with AmbiguousReadModelBuilder. An inline scenario override can
exercise a different path than production; do not mistake it for registration
proof. See reducers for signatures and
static direct-call/scenario examples.
For every reducer form, cover empty history, first-event null current, guarded branches, deletion and recreation. Scenarios substitute storage, observer lifecycle and compliance; they do not prove real-kernel registration, replay, transport, encryption, erasure or migration.
For stricter runs, WithStrictEventSubscription() and WithStrictFidelity()
turn silent mismatches into failures.
Step 5 — Write the specification
#if DEBUG
namespace MyApp.Ordering.Orders.when_items_are_added;
public class and_two_items_are_priced : Specification
{
ReadModelScenario<OrderSummary> _scenario;
static readonly OrderId TheOrder = OrderId.New();
async Task Establish()
{
_scenario = new ReadModelScenario<OrderSummary>();
await _scenario.Given
.ForEventSource(TheOrder)
.Events(
new OrderCreated(),
new ItemAdded(9.99m),
new ItemAdded(4.50m));
}
[Fact] void should_sum_the_item_prices() => _scenario.Instance!.Total.ShouldEqual(14.49m);
}
#endif
Wrap files in #if DEBUG … #endif only when they compile into the application
assembly, so specification code ships only in Debug. Dedicated spec projects
need no wrapper. Keep one outcome per should_ fact, not one scenario class per
assertion. Apply the event sequence once; capture intermediate states in Because
for create/update/delete assertions so facts remain read-only. Capture values or
immutable copies if later events mutate the same instance. Multiple event-source
keys may share this setup for isolation and child-key assertions.
Step 6 — Cover the read model, not just one event
For .play setup, assertions and case tables, read cratis-application-slice-specifications, "Reading a .play specification".
One summation example proves one event. Take the inventory from the contract
(the .play read model and its specifications, or the agreed outline); without
one, derive it from the projection and say so. Then check each line:
- Every property is asserted in a read-only fact in the model's shared scenario class; do not multiply scenario startup for each field.
- Every subscribed event has a specification. Reconcile three lists in both
directions: the contract's event types, the projection's actual subscriptions,
and the events your specifications seed. Report any event in one list missing
from another; route that reconciliation to
cratis-application-slice-conformance.WithStrictEventSubscription()is narrower: it fails a specification that seeds an event the projection does not subscribe to. It does not reveal an extra subscription that no specification seeds, nor a subscribed event lacking a specification. - Every removal or clearing event has a specification asserting absence:
Instanceisnull, or the child is gone from the collection. Absence is a result, not a skipped case. - A later event that updates only some properties has a specification showing the other properties are unchanged.
- Use the contract's example values so the code and the contract describe the
same example; substitute fresh identifiers only where isolation needs it,
keeping the example's relationships. A read-model rule found in the projection with no contract
specification is a proposal for the contract (the
.playmodel when one covers the slice, otherwise the agreed outline), not silent coverage.
Lineage
Step 6 is adapted in our own words from ideas recorded in references/provenance.md.
Read references/view-lifecycle-checks.md when delivering a read model from a contract: population, update and removal checks per property and event.
What breaks
NoReadModelHandlerFound. Nothing in the loaded assemblies handlesTReadModel— the reducer or projection type is not where the scenario looks.MultipleInstancesMaterializedonInstance. The seeded events produced more than one instance. UseInstanceForEventSourceId(id), or seed one source.Instanceisnull. No event in the seeded set matched the projection, so nothing was created. Check the key resolution before the property mapping.- A property is silently the type default. AutoMap wired a different event's identically named property over the explicit setter, or the explicit setter never fired. This looks like a specification problem and is a projection problem.
- A removal is never exercised. The suite is green because every
specification only adds. Seed the event that removes or clears, then assert the
instance is
nullor the child is absent. - The specification passes but production does not. The specification pinned a read-model instance instead of seeding events, so the projection under question never ran.
How it is proven
dotnet build in Debug and the owning project's built spec executable (see specs.csharp), both clean. A projection
specification is only meaningful once it has been seen to fail: drop one seeded
event and confirm the assertion goes red before trusting it green.