Cratis application slice specifications
Start a pure decision with a plain method call: Handle(),
Handle(providedValue), reducer logic or a reactor's decision needs no host,
services or harness, including direct validator calls with supplied read-model state.
Add exactly the scenarios the per-artifact decision table in the
scenario selection and cost rule obligates
(pipeline and authorization, constraints, projection and reducer dispatch,
reactor dispatch and routing). The scenario family
exercises the real Arc and Chronicle code paths in-process — no HTTP, no fixture,
no server.
This skill decides when to add a scenario and what to cover. The C# mechanics
(Establish/Because, substitutes, contexts) live in
cratis-specifications-csharp.
Product packages
| Package | Purpose |
|---|---|
Cratis.Arc.Testing |
CommandScenario<TCommand> and the CommandResult assertions |
Cratis.Arc.Chronicle.Testing |
Given, EventLog, AppendedEvents and the appended-event assertions on a command scenario |
Cratis.Chronicle.Testing |
EventScenario, ReadModelScenario<T>, ReactorScenario<T> |
Cratis.Specifications.XUnit |
The Specification base and the ShouldXxx assertions |
Reactor read-model setup and the EventContext.From UTC default below need a newer Chronicle than
the Arc scenario surface itself; see cratis-chronicle-reactor/references/specifications.md for sources.
Requires Chronicle 19.46.0 or later for class-based reactor read-model seeding and the EventContext.From UTC default.
Cratis.Testing is the meta-package that brings Cratis.Arc.Testing and
Cratis.Arc.Chronicle.Testing together. Reverify against the owning product
repository before claiming support for another version.
Route near misses
- The repository builds a Cratis library rather than an application: use
cratis-specifications-csharpand stay on the plainSpecificationbase. - React, TypeScript, or a view model: use
cratis-application-react-specifications. - The subject is append semantics or a constraint on its own: use
cratis-chronicle-event-specifications. - The subject is a projection or reducer on its own: use
cratis-chronicle-read-model-specifications. - The question is what the slice should do: settle the behavior first. A specification records a decision; it does not make one.
- The scope is model-first (the
specificationblocks of the.playslice are the contract for this skill). 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 or change model specifications withcratis-screenplay-specificationsandcratis-screenplay-scenario-coverage; check finished code against the model withcratis-application-slice-conformance.
Step 0 — Take the list from the contract
When the slice has a contract — a .play slice with its specification
blocks, or an agreed outline — its specifications are the minimum list: each
gets concrete assertions. Decision outcomes use focused classes; declarative
read-model mappings share one class per model with many read-only facts. Steps 3–7 then add what
the code reveals (each validator rule, each constraint). A rule found in the code
with no contract specification is a proposal for the contract (the .play model when one covers the slice, otherwise the agreed outline), not silent coverage:
list it in the report and, where a model exists, route it to
cratis-screenplay-scenario-coverage.
Without a contract (code-first scope), derive the list from Step 3 and say that you did.
Reading a .play specification
Read the actual assignments, not a prose retelling; given seeds events or a pinned read model, when fills the command, then becomes the appended-event predicate or an instance assertion, and then denied is ShouldNotBeAuthorized(), not a validation error. Read references/reading-play-specifications.md when translating a .play specification, including parameter/case tables, into a specification class.
Step 1 — Place the files
Specifications live in the slice folder, beside the .cs they specify, each
file wrapped in #if DEBUG … #endif when it compiles into the application
assembly, so specification code ships only in Debug. A dedicated <Source>.Specs
project is not shipped and needs no wrapper.
<Feature>/<Slice>/
├── <Slice>.cs
└── when_<verb_phrase>/
├── and_<happy_scenario>.cs
└── and_<failure_scenario>.cs
- Folder:
when_<verb_phrase>—when_registering. - File:
and_<condition>.cs—and_name_is_unique.cs,and_name_already_exists.cs. - Method:
should_<expected_result>.
A behavior covering several subjects groups under
<Slice>/for_<Subject>/when_<behavior>/.
Step 2 — Start with the decision; add the scenario by slice type
Specify a pure decision with the plain Specification base first. A direct
Handle() call does not run validation, authorization, Provide() or operations,
so each wiring that can refuse before Handle needs its own negative scenario.
The per-artifact decision table and its coverage obligations are in the
scenario rule; apply it as written.
A Handle that takes IEventStore, IReadModels or services is not a plain
call: keep the scenario, and when touched take read models as parameters.
| Slice type | Scenario | Skill |
|---|---|---|
| Pure command/validator decision, reducer logic or reactor decision | Plain method call with Specification and supplied read-model state (default) |
cratis-specifications-csharp |
| State Change — command pipeline and appended events | CommandScenario<TCommand> |
this one |
| Append semantics, a constraint | EventScenario |
cratis-chronicle-event-specifications |
| Query pipeline — arguments, authorization, validation, interceptors | QueryScenario<TReadModel> |
query and decision scenarios |
| State View — declarative mapping or reducer wiring | One ReadModelScenario<TReadModel> class per read model, many assertions on shared setup |
cratis-chronicle-read-model-specifications |
| Automation or Translation — a reactor | ReactorScenario<TReactor> |
cratis-specifications-csharp |
| A host, transport, or real-infrastructure boundary | Out-of-process integration | cratis-specifications-csharp |
For a class-based reactor scenario, explicitly seed
handler read-model parameters with Given.ForEventSourceId(id).ReadModel(instance)
or declare intentional absence with .NoReadModel<T>(). An unseeded model throws
ReadModelNotSeededForReactorScenario even if nullable; Given events do not
build read models, including passive ones. Use the reactor's resolved key, not
necessarily the trigger's source id. This is not the command-scenario event
seeding described in Step 5. Read cratis-chronicle-reactor for the setup examples,
exception diagnostics, synchronous handler throws and UTC context defaults.
Step 3 — Cover every outcome of a State Change slice
One specification class for each of:
- The happy path — a plain call returns the expected event, plus one
CommandScenariohappy path for the pipeline, and a negative scenario for each authorization policy andProvide()short-circuit. - Each validation failure — instantiate
CommandValidatororConceptValidatorwith the required state and validate directly; the command's pipeline scenario proves the wiring. - Each business-rule rejection — one
and_class per condition inHandle()that inspects a read model. - Each constraint violation — one class per constraint, written with
EventScenario, because a constraint is enforced at the append and not by the command. - Repeat execution, when a reactor invokes the command: the same command twice for the same source. Specify whether the second is rejected, a no-op, or appends again — recovery can re-deliver an event, so the answer must be a decision, not an accident.
Use the contract's example values. When the contract gives concrete values
(the when and then values of a .play specification), use them, so the code
specification and the contract describe the same example. Where isolation needs
it, substitute a fresh identifier or uniqueness value (see What breaks) and keep
the example's relationships and behavior. Invent values only where the contract
is silent.
Step 4 — CommandScenario<TCommand>
It runs authorization, the validators, Provide() and Handle() in-process and
exposes what was appended.
#if DEBUG
namespace MyApp.Projects.Registration.when_registering;
public class and_name_is_unique : Specification
{
readonly CommandScenario<RegisterProject> _scenario = new();
readonly ProjectId _id = ProjectId.New();
CommandResult _result;
async Task Because() => _result = await _scenario.Execute(new RegisterProject(_id, "My Project"));
[Fact] void should_succeed() => _result.ShouldBeSuccessful();
[Fact] async Task should_have_appended_the_registered_event() =>
await _scenario.ShouldHaveAppendedEvent<RegisterProject, ProjectRegistered>(_id, e => e.Name == "My Project");
}
#endif
The scenario's surface (Execute, Validate, LastResult, Operations) is listed in references/command-result-assertions.md; Given and the event assertions are extension members from the Chronicle integration.
Step 5 — Seed prior state through Given
With Cratis.Arc.Chronicle.Testing referenced, a command scenario has a
Chronicle-backed Given builder, plus EventScenario, EventLog,
EventSequence and AppendedEvents.
// Seed the events the world already contains. A read model the command injects
// for this event source is materialized from them by its own projection or
// reducer — no read-model type is named.
_scenario.Given.ForEventSource(_cartId).Events(new ItemAddedToCart(itemId));
// Or pin a specific read-model value directly, when the events are beside the point.
_scenario.Given.ForEventSource(_cartId).ReadModel(new CartSummary { ItemCount = 3 });
Supply read-model state for a business decision. Seed events only when the history itself matters, such as projection mapping or append-time uniqueness; do not replay a projection merely to feed a pure command decision.
Both builder methods return void; there is nothing to await.
Read protection is invisible to application spec authors. Never configure modes,
call UseDecisionReads, simulate competing appends (AppendConcurrently), seed
events solely for infrastructure, or re-prove the platform concurrency/guard
matrix: give state, assert the outcome. Keep one cheap assembly-level
DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly) spec for the
application's own model/projection shapes: its only decision-read spec obligation.
If the harness cannot accept required state, report the upstream gap; never weaken
production guards for test speed. Read
query and decision scenarios for
query pipelines.
Validator and Provide() dependencies are registered in _scenario.Services;
the concrete validator itself is discovered automatically.
Step 6 — Assert twice on pipeline validation failures
[Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
[Fact] void should_have_validation_errors() => _result.ShouldHaveValidationErrors();
ShouldNotBeSuccessful() alone cannot distinguish a validation rejection from an
unhandled exception, so both facts are required for pipeline validation specs.
For direct validator calls, assert the validation result and the specific rule.
Do not assert on a message
string by default — it is presentation text; assert one only when that exact
text is the specified behavior, and name that requirement in the fact. A .play
specification may pin the message (then error "<message>"); prefer pinning the
kind in C# unless the exact wording is part of the behavior being specified.
Isolate the rule. Each rejection specification violates only the rule it
is named after: build the command valid in every other respect. Otherwise
ShouldHaveValidationErrors() passes when a neighbouring rule fires. Use
ShouldHaveValidationErrorBecauseOf(reason) where the reason distinguishes the
rule, and always run the "remove the rule, see it go red" check under How it is
proven.
Read references/command-result-assertions.md when choosing a CommandResult assertion: ShouldHaveValidationErrorBecauseOf(reason) is the message-free way to say which kind of rejection happened, and an unauthorized result carries no validation errors, so assert ShouldNotBeAuthorized().
Step 7 — Assert what was appended
The appended-event assertions come from Cratis.Arc.Chronicle.Testing and are
keyed by command and event type. They return Task, so the fact is
async Task, and they throw EventSequenceAssertionException.
ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId)ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId, Func<TEvent, bool> predicate)ShouldHaveTailSequenceNumber<TCommand>(sequenceNumber)
⚠️ On a command scenario the second argument is a predicate
(Func<TEvent, bool>), not an assertion callback. The Action<TEvent> validator
shape lives on other receivers — the IEventSequence extensions in
Cratis.Chronicle.Testing, AppendedEventWithResult.ShouldHaveEvent<TEvent>(Action<TEvent>?),
and the IChronicleSetupFixture extension in Cratis.Chronicle.XUnit.Integration
— never on CommandScenario.
Sequence numbers are zero-based: the first event is 0, and the tail after a
single append is 0, never 1.
Lineage
Step 0, repeat execution and rule isolation are adapted in our own words from
ideas recorded in references/provenance.md. Read references/provenance.md when checking attribution or the origin of Step 0, repeat-execution coverage, and rule isolation.
What breaks
- A specification passes alone and fails in the suite. A hard-coded value
collided with another specification's uniqueness claim. Use a per-specification
value — a fresh
Guid, orGuid.NewGuid().ToString("N")[..9]. Adding[Collection(…)]is the wrong fix here. Givendoes not resolve.Cratis.Arc.Chronicle.Testing(or theCratis.Testingmeta-package) is not referenced. It is an extension member, not part ofCommandScenarioitself.- A DCB rejection specification is green for the wrong reason. The read model
was never seeded, so the handler saw a default or
nullinstance and rejected on that instead of on the rule. Seed, then confirm the specification fails when the seeding is removed. - A rejection specification stays green when its rule is deleted. The command was invalid in a second way, so another rule produced the error. Make the command valid except for the one rule, then repeat the red check.
- The command scenario reports success but nothing was appended. The
assertion is on
CommandResultonly; add aShouldHaveAppendedEvent<TCommand, TEvent>fact. - Injected-validator branches flip with test ordering. An older harness replaced the process-wide provider; current
releases isolate stores and event-source services per scenario. Reproduce
before applying the old direct-validator/small
[Collection]workaround.
How it is proven
dotnet build -c Debug — it compiles the #if DEBUG specification code — then
the owning project's built spec executable (see specs.csharp), both clean, with a specification for the happy path and one per
rejection. Before trusting a rejection specification green, remove the condition
that causes the rejection once and confirm it goes red.