Chronicle event specifications
EventScenario runs the append path in-process. No Chronicle server, no
database, no network — an empty event log at sequence number zero, with the
application's constraints discovered and active.
Specify every constraint with an EventScenario: one class for the violation
and one for the nearest non-violation. A constraint is enforced at append, so no
plain call or substituted event store proves it. Pure decisions around it are
plain calls; see the decision table.
Verified product sources
| Package | Purpose |
|---|---|
Cratis.Chronicle.Testing |
EventScenario, its Given/When builders, the IAppendResult Should* assertions |
Cratis.Chronicle |
IEventSequence.Append/AppendMany, IAppendResult, ConstraintViolation |
Sources: Source/Clients/Testing/EventSequences/, TestingEventStore.cs,
and Source/Clients/DotNET/EventSequences/.
dotnet add package Cratis.Chronicle.Testing
Reverify against the Chronicle repository before claiming support for another version. Never translate an assertion name from memory.
Route near misses
- The behavior is a command running through validators,
Provide()andHandle(): usecratis-application-slice-specifications. - The behavior is a projection or reducer building a read model: use
cratis-chronicle-read-model-specifications. - You are deciding what the constraint should be: use
cratis-chronicle-event-constraints. - The specification style itself — folder shape, naming, what not to specify:
use
cratis-specification-by-example.
When you need this
- A constraint must reject a duplicate or conflicting append.
- A batch append (
AppendMany) must behave as one unit. - The event log's own behavior is the subject, not the command that reached it.
When you do not
- Concurrency violations are not what the scenario's defaults exercise.
EventScenariowires a strategy that always answersConcurrencyScope.None, which the validator skips, so an append that lets the strategy pick the scope (When, orEventLog.Appendwithout aconcurrencyScope) can never reportHasConcurrencyViolations. Only an append that passes an explicit scope onscenario.EventLog.Append(...)reaches the in-process validator at all — and that is a spec of the scope you hand-built, not of the application's strategy. The platform concurrency/guard matrix belongs only in Arc/Chronicle specs, with real-kernel integration where required. Application decisions use directHandle()/validator calls with supplied state plus the one cheap assembly-level shape-admission spec in specs.scenarios.csharp.md. A default scenario must not claim concurrency coverage — it would pass vacuously.
Step 1 — Create the scenario
A new EventScenario per specification, never shared state.
var scenario = new EventScenario();
The parameterless constructor uses the default event log, an in-memory event
store, the default namespace, and auto-discovers the constraints declared
in the loaded assemblies — which is what makes a constraint specification work
without wiring. Pass an ICanProvideConstraints to the single-argument
constructor when the specification needs a narrower set.
It implements IDisposable: dispose in Destroy().
new EventScenario(sequenceId, eventStore, @namespace) selects identifiers;
constructors also accept per-run Defaults. One scenario shares production
in-memory storage across its sequences and uses the kernel append grain,
serialization, migrations and compliance. Older-generation appends migrate;
undiscovered schemas fail with EventSchemaNotDiscovered. Appends to one
sequence serialize, so racing claims of the same unique value cannot both win.
Seeding can specify source/stream routing through the ForEventSource,
For<TEvent> and ForEvents overloads.
Requires Chronicle 19.59.0 for scenario.ReadModels to read and observe
projections (including children and joins) and reducers from the scenario's own
events, not a shared default store. Check the testing package version; on older
packages use a dedicated ReadModelScenario rather than assuming shared storage.
Requires Chronicle 19.52.0 for per-run Defaults to honor marker-free
ExplicitArtifacts; see the .NET client's discovery reference.
Step 2 — Seed prior state through Given
await scenario.Given
.ForEventSource(authorId)
.Events(new AuthorRegistered("Jane Smith"), new BookAdded("Clean Code"));
Chain a second ForEventSource for a different event source:
await scenario.Given.ForEventSource(author1Id).Events(new AuthorRegistered("Jane Smith"));
await scenario.Given.ForEventSource(author2Id).Events(new AuthorRegistered("John Doe"));
Givenreturns a bareTask— it carries no result, because seeding is not the action under specification.- Seed before the act phase; seeded events take monotonically increasing sequence numbers.
- Never put the act under test inside
Given. Only the world as it already is belongs there.
Step 3 — Append, and hold the result
Two equivalent surfaces. When reads as the act phase; the event log is the
direct one.
// The act-phase builder — returns Task<AppendResult>
_result = await scenario.When
.ForEventSource(authorId)
.Events(new AuthorRegistered("Jane Smith"));
// The event log directly
_result = await scenario.EventLog.Append(authorId, new AuthorRegistered("Jane Smith"));
When…Events(@event, params object[] additionalEvents) takes the first event
positionally and stops at the first non-successful append, so a specification
that appends several events asserts on the first failure rather than the last.
AppendMany on the event log appends a batch for one event source:
_result = await scenario.EventLog.AppendMany(cartId, [
new ItemAddedToCart(itemId1),
new ItemAddedToCart(itemId2)
]);
Append and AppendMany are members of the event sequence reached through
scenario.EventLog, not of EventScenario itself.
Step 4 — Assert on the result
Every assertion below is an extension on IAppendResult and throws
AppendResultAssertionException on failure, with a message listing the
violations and errors it found.
| Method | Asserts |
|---|---|
ShouldBeSuccessful() |
No violation and no error |
ShouldBeFailed() |
Any violation or error |
ShouldHaveConstraintViolations() |
At least one constraint violation |
ShouldNotHaveConstraintViolations() |
No constraint violation |
ShouldHaveConstraintViolationFor(name) |
A violation for the named constraint |
ShouldHaveConstraintViolation(name) |
The same assertion, singular spelling |
ShouldHaveErrors() |
At least one error |
ShouldNotHaveErrors() |
No error |
ShouldHaveConcurrencyViolations() and ShouldNotHaveConcurrencyViolations()
also exist, but see When you do not above — the first can never pass inside a
scenario and the second passes vacuously.
The constraint name parameter is a ConstraintName, which converts implicitly
from string, so a literal compiles. Prefer a shared constant
(<Module>ConstraintNames.UniqueX) so a rename moves both sides at once.
Assert the name by default. Assert exact message text only when that wording
is the specified behavior, and name that behavior in the fact.
Step 5 — Write the specification
Specification files live in the slice folder. Wrap them 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.
#if DEBUG
namespace MyApp.Library.Authors.when_registering;
public class and_the_name_already_exists : Specification
{
EventScenario _scenario;
IAppendResult _result;
async Task Establish()
{
_scenario = new EventScenario();
await _scenario.Given
.ForEventSource(AuthorId.New())
.Events(new AuthorRegistered("Jane Smith"));
}
async Task Because() =>
_result = await _scenario.EventLog.Append(AuthorId.New(), new AuthorRegistered("Jane Smith"));
[Fact] void should_be_failed() => _result.ShouldBeFailed();
[Fact] void should_have_constraint_violation_for_unique_name() =>
_result.ShouldHaveConstraintViolationFor(AuthorConstraintNames.UniqueAuthorName);
}
#endif
Use per-specification unique values ($"{Guid.NewGuid():N}") so the suite does
not depend on execution order. For a release, append the removal event and then
assert the value can be claimed again.
What breaks
- The duplicate append succeeds. The constraint was not discovered — the scenario was given an explicit constraint provider that excludes it, or the constraint type is not in a loaded assembly.
ShouldHaveConstraintViolationForfails with an empty violation list on a batch append.When…Eventsshort-circuits, so the conflict may be on an event the append never reached.- A concurrency specification is always green. Without an explicit checked
scope, the default client strategy answers
ConcurrencyScope.Noneand proves nothing. The kernel validator is present; explicit-scope violations have not been proven end to end here. Prove the application's strategy with integration. - The specification passes alone and fails in the suite. A hard-coded unique value collided with another specification's claim.
How it is proven
dotnet build in Debug (which compiles the #if DEBUG specification code) and
the owning project's built spec executable (see specs.csharp), both clean. A constraint specification is only meaningful if it
has been seen to fail: remove the seeding Given once and confirm the
specification goes red before trusting it green.