Help › Stories · version 1 ·

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:

  • $send sends a message: $send hello.greet (name = "Ana").
  • $expect checks what came back: $expect payload is "Hello, Ana!".
  • $val keeps 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!"
  • payload is the reply to the last $send. Each $send replaces it.
  • Send values as name = value. The rule checks their types: 2.0 for a Float, not 2.
  • $val can 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. 180 and 180.0 are equal.
  • Only sometimes: $expect payload is "Hi" if (who is "Razie") is skipped unless the part after if holds.

A rule's local values (x = …) aren't visible to the story; only payload, ctx and your $vals are.

Run it

  1. Open the Fiddle, Stories tab.
  2. Open your Story: topic, or press New and paste one.
  3. 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 if didn'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.throw ends 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: contains isn't an operator, use matches /…/.
  • E_NO_HANDLER: no rule handles the message you sent. Check its name, and that the rule's $when starts its line.
  • E_TYPE: a value of the wrong type, like 2 for a Float.
  • 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 payload won (Rules › order).

See also

Updated by razie · version 1