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. |
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.
What the three parts can hold
Section titled “What the three parts can hold”- 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.
Who is calling
Section titled “Who is calling”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.
Where they come from
Section titled “Where they come from”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.
Play: run the model
Section titled “Play: run the model”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.
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.
Play and Preview
Section titled “Play and Preview”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.
Why both
Section titled “Why both”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.