write-specs-events

Writing Event Sequence Specs with EventScenario

Use EventScenario to test event-appending behavior in-process — no Chronicle server, database, or network required. Wrap every spec file in #if DEBUG … #endif so spec code ships only in Debug. Assert the constraint name (ShouldHaveConstraintViolationFor(name)), never the message.

When to use this skill

• Testing that a command appends the correct event(s)
• Testing that a constraint correctly rejects a duplicate or conflicting append
• Testing AppendMany for batch event appends
• Testing concurrency or error conditions in event appending

For testing read model projections or reducers, use ReadModelScenario<TReadModel> instead.

---

Package

dotnet add package Cratis.Chronicle.Testing

---

Basic structure

// In your spec file (follows BDD Establish/Because/should_ pattern)
public class when_appending_<event_name> : Specification
{
    EventScenario _scenario;
    IAppendResult _result;

    void Establish() => _scenario = new EventScenario();

    async Task Because() =>
        _result = await _scenario.EventLog.Append(<eventSourceId>, new <EventType>(<args>));

    [Fact] void should_be_successful() => _result.ShouldBeSuccessful();
}

---

Step 1 — Create the scenario

Always create a new EventScenario per test. It starts with an empty event log and sequence number zero.

var scenario = new EventScenario();

---

Step 2 — Seed pre-existing state (optional)

Use the fluent Given builder when the act phase depends on prior state:

await scenario.Given
    .ForEventSource(authorId)
    .Events(new AuthorRegistered("Jane Smith"), new BookAdded("Clean Code"));

Chain multiple ForEventSource calls to seed different event sources:

await scenario.Given
    .ForEventSource(author1Id)
    .Events(new AuthorRegistered("Jane Smith"));

await scenario.Given
    .ForEventSource(author2Id)
    .Events(new AuthorRegistered("John Doe"));