write-specs-readmodels

Writing Read Model Specs with ReadModelScenario

Use ReadModelScenario<TReadModel> to test read model projections and reducers entirely in-process — no Chronicle server, database, or network required. Wrap every spec file in #if DEBUG … #endif so spec code ships only in Debug.

When to use this skill

• Testing that a reducer correctly builds state from a sequence of events
• Testing that a fluent IProjectionFor<T> projection maps event properties to read model properties
• Testing that a model-bound projection ([FromEvent<T>], [Key]) maps correctly
• Testing boundary conditions: first event, multiple events, different event sources

For testing event appending, constraints, or concurrency, use EventScenario instead.

---

Package

dotnet add package Cratis.Chronicle.Testing

---

Basic structure

// In your spec file (follows BDD Establish/Because/should_ pattern)
public class when_<event_sequence_description> : Specification
{
    ReadModelScenario<TReadModel> _scenario;

    async Task Establish()
    {
        _scenario = new ReadModelScenario<TReadModel>();
        await _scenario.Given
            .ForEventSource(<eventSourceId>)
            .Events(new <EventType>(<args>));
    }

    [Fact] void should_<expected_state>() => _scenario.Instance!.<Property>.ShouldEqual(<expectedValue>);
}

---

Step 1 — Create the scenario

Always create a new ReadModelScenario<TReadModel> per test. Optionally pass an initial state:

// Default (empty) initial state
var scenario = new ReadModelScenario<MyReadModel>();

// With an initial state baseline
var scenario = new ReadModelScenario<MyReadModel>(new MyReadModel { Count = 10 });

---

Step 2 — Seed events via the fluent Given builder

await scenario.Given
    .ForEventSource(myId)
    .Events(new SomeEvent("value"), new SomeOtherEvent(42));

Chain multiple ForEventSource calls to seed different event sources:

await scenario.Given
    .ForEventSource(orderId)
    .Events(new OrderCreated("order-1"), new ItemAdded(9.99m));

await scenario.Given
    .ForEventSource(anotherOrderId)
    .Events(new OrderCreated("order-2"));