Stories: check that your rules work
A story is a test for your rules. It sends messages, as a person or an app would, and says what must come back. Run it after every change to a rule: if a check fails, you know before anyone else does. How rules work: Rules.
Your AI writes a story with every rule it writes, and runs it before it tells you the rule works.
What a story is
A Story: topic with three kinds of lines:
$sendsends a message:$send hello.greet (name = "Ana").$expectchecks what came back:$expect payload is "Hello, Ana!".$valkeeps a value for later lines:$val who = "Bo".
Every other line is a note for people: say what the story is about. Each $ line must start its line. A story only sends and checks: what the app does belongs in the rules.
Write one
$send hello.greet (name = "Ana")
$expect payload is "Hello, Ana!"
$send hello.greet (name = "Razie")
$expect payload is "Welcome back, Razie!"
payloadis the reply to the last$send. Each$sendreplaces it.- Send values as
name = value. The rule checks their types:2.0for aFloat, not2. $valcan take a message's reply:$val tax = order.tax(amount = 100.0).
What you can check
An $expect is any expression that must be true (Expressions):
- The reply:
payload is 5,payload is not empty,payload.total is 180.0,payload[0].name is "bolt". - Shared values the rules set with
ctx.…:ctx.price is 180.0. - Your own
$vals:tax is 13.0. - Text:
payload matches /Hello.*/. - Numbers:
payload > 1000.180and180.0are equal. - Only sometimes:
$expect payload is "Hi" if (who is "Razie")is skipped unless the part afterifholds.
A rule's local values (x = …) aren't visible to the story; only payload, ctx and your $vals are.
Run it
- Open the Fiddle, Stories tab.
- Open your
Story:topic, or press New and paste one. - It runs as you type (Cmd/Ctrl+Enter runs it again). Save when it's right.
The story runs against all your project's Spec: topics. You can also ask your AI "run Story:shop". Every run shows on the Flows page (Flows).
Runs never change your data. A story runs on a scratch copy: objects it writes are thrown away, and requests like a notice to a member are recorded, not sent. Calls to the web are real, writes to an allowed site too: the Fiddle warns you before it sends one.
How it reports
Each $expect is one of:
- passed ✓: it was true;
- failed ✗: it was false, and the line number says which one;
- skipped: its
ifdidn't hold.
The story passes when no check failed. On Flows its row says n expects pass, n of m expects failed, stopped with an error or doesn't parse.
- An error stops the story. A message nobody handles, a wrong type or an uncaught
diesel.throwends the run there; the checks after it don't run. The error gives its code and line. - To find why a check failed, open the flow and read its trace: each message, each rule that ran, and each value it set, in order.
A worked example
The shop from Rules › example: members get 10% off, tax is 10%, an order needs at least one item.
A member orders items worth 200.
$send order.place (qty = 2, subtotal = 200.0, member = true)
$expect payload.total is 180.0
$expect payload.due is 198.0
$expect ctx.price is 180.0
An empty order is refused.
$send order.try (qty = 0)
$expect payload is "refused: order at least one"
All four checks pass. Now change the discount in the rule to 0.8: the first three fail, and the trace shows ctx.price = 160.0 where 180 was expected.
Stories and features
A story that checks a feature is what makes it checked in the system view: its last run says whether the feature works (SystemView). Change the feature, run its story again.
Some stories walk pages instead of sending messages: a person's path through your app. Those are journeys: Journeys.
When things go wrong
doesn't parse/E_PARSE: a line doesn't read; the message gives the line and column. A common one:containsisn't an operator, usematches /…/.E_NO_HANDLER: no rule handles the message you sent. Check its name, and that the rule's$whenstarts its line.E_TYPE: a value of the wrong type, like2for aFloat.E_NATIVE: the story sent an event (a name with.on.). Only d2 sends those; to test an event rule, put the work in a message of your own and send that.- A check fails but the rule looks right: read the trace on Flows. A common cause: several rules matched, and the last one to set
payloadwon (Rules › order).
See also
- Rules, messages and flows: what your stories check.
- The Fiddle: try expressions and specs live: where stories run as you type.
- Flows: see what the engine just ran: every run and its trace.
- User journeys: review your app's paths with AI: stories that walk pages.