Skip to content

Specifications and Play

A model that nobody can check is only a drawing. Studio gives you two ways to check one: specifications, which are examples of a single behavior, and Play, which runs the whole model as an application.

Specifications: examples that prove a slice

Section titled “Specifications: examples that prove a slice”

A specification is a concrete example, written in three parts that read like a sentence: Given, When, Then.

Part Question it answers Acme Commerce example
Given What was already true? The Acme mug is listed in the shop and 9 are available. The caller is a signed-in shopper.
When What happens? The shopper asks to add 2 mugs to their basket.
Then What should be the result? The basket gets a line of 2 mugs at 49, and the basket page shows it.
SPECIFICATION AddingAnAvailableProduct GIVEN Already true WHEN What happens THEN The result CALLER Shopper signed in EVENT ProductListed Acme mug · 9 available COMMAND AddToBasket Acme mug · quantity 2 EVENT BasketLineAdded Acme mug · 2 at 49 READ MODEL BasketContents one line: 2 Acme mugs
A specification reads top to bottom, like a sentence: given, when, then.

Because the example uses real values, nobody has to guess what a rule means. Two specifications on the same slice often tell the whole story. A second one for AddToBasket starts from a product with none available, asks for the same mug and expects the refusal That product is out of stock.

  • Given can be facts that already happened, the state a read model is in, or a named starting situation called a given context that several specifications share. Given can also say who is calling.
  • When is the thing that triggers the slice: a command for a state change, an event for an automation or a translation, or a query for a view.
  • Then is what must come out: events, the state of read models, the result of a query, or exactly one error. A specification can also say that nothing should happen.

A specification states either success or a refusal. Mixing the two in one example is not allowed, because it would not be clear what you are checking.

A specification can name the caller: nobody in particular, anonymous, authenticated, a particular persona or a set of roles. It can also expect the command, or the query, to be denied. That is how a model proves that a rule about permission holds.

You can write specifications by hand, or ask Studio to generate them with AI from the slice. Either way, a person reviews them: a generated example is only a proposal until the team agrees that it describes the business correctly.

Studio runs a slice’s specifications in a sandbox, so a run changes nothing real. Each specification shows its own result:

Result Means
Not run It has not been run yet.
Running… The run is in progress.
Last run succeeded The model does what the example says.
Last run failed The model does something else. The result shows the difference.
Last run was inconclusive The run could not decide.
Could not run The run did not start, for example because the model has a problem.

Studio also looks for gaps. A finding flags a slice that has no specifications at all.

To write and run specifications, read Check a slice with specifications.

Specifications check one behavior at a time. Play runs the whole event model as if it were the finished application, so that people can use it before anything is built.

Play starts a sandbox from the model and gives you four ways to look at it:

  • Frontend: the screens, so you can click through the model as a user.
  • Backend API: the interface that the screens talk to.
  • Chronicle Workbench: the events of your session, as they are recorded.
  • Read models: what each read model holds at the moment.
SANDBOX gone when the session ends Play EVENT MODEL Storefront FRONTEND The screens BACKEND API What screens call CHRONICLE WORKBENCH Recorded events READ MODELS What each holds
Play runs the model. Everything in the sandbox is gone when the session ends.

Click through a checkout and you can watch the events appear and the read models fill in. The sandbox also shows when something is refused and why, for example because the caller is Denied (403) or the Validation refused (400) the request.

They are different tools for different questions. Preview draws a single screen with sample data, so a designer can judge how it looks and how it behaves for a persona. Play runs the whole model, so a team can judge whether the behavior is right.

To run a model, read Play an event model.

Specifications are precise and cheap, and they keep a model honest as it changes. Play is broad and convincing: it lets a product owner see the thing working. Together, they let a team find a misunderstanding on the board, where fixing it costs a conversation instead of a rewrite.

The specifications also stay with the slice when it is built: a build reports where its own results and the board’s run of the specifications disagree. See Build and deliver.