Skip to content
Varar

Your first oath from scratch

In Get started on your computer we ran a scaffolded example. Now we write our own from a blank file: a tiny calculator. By the end you will have described a behaviour in prose, bound it to code, and seen the two verify each other.

This tutorial continues in the project you set up in Get started.

  1. Describe the behaviour

    Create varar/calculator.md:

    # Calculator
    

    The expression `1+1` should evaluate to `2`.

    That’s the whole oath. It reads like documentation because it is documentation — plain prose, with concrete values. Varar calls those values cells, and they are what make the prose checkable: 1+1 is the cell we act with, 2 is the cell we expect back.

  2. Bind the steps

    Nothing runs yet — no step matches our sentence. Create src/varar/calculator.steps.ts:

    import { steps } from '@varar/varar'
    

    const { stimulus, sensor } = steps(() => ({ result: 0 }))
    

    stimulus('expression `{int}+{int}`', (_state, op1, op2) => ({ result: op1 + op2 }))
    

    sensor('evaluate to `{int}`', (state, _expected) => state.result)

    Three things to notice:

    • steps declares the state each example starts from — a fresh { result: 0 } every run, so examples never leak into each other.
    • The stimulus drives the software. It matches expression `1+1` in the prose, computes, and returns the next state — the value it returns is the new state, replacing the old one rather than being merged into it.
    • The sensor is the read-only observation. It returns what the software actually produced — state.result — and Varar compares that against the 2 written in the Markdown. You never write an assertion; the document is the assertion.

    The {int} placeholders are Cucumber Expressions: they capture the cells from the prose and hand them to your function, typed.

  3. Run it

    Terminal window
    pnpm vitest run
    ✓ varar/calculator.md (1 test) 1ms
    ✓ varar/deep-thought.md (1 test) 1ms
    

    Test Files  2 passed (2)
         Tests  2 passed (2)

    Your sentence is now an executable example.

  4. Watch it fail

    Make it a habit: every new example should be seen failing once. This time, break the document — claim in calculator.md that 1+1 evaluates to 3.

    Run Varar again. The document demands 3, the software answers 2, and the failure points at the 3 in your Markdown. Revert it, run once more, and you’re green.

What you just learned

Section titled “What you just learned”
  • An oath is prose with concrete values; no keywords, no special file format.
  • Steps come in exactly two roles, chosen by what they do: a stimulus drives the system, a sensor observes it. Setting up the starting state is a stimulus too — there is no separate role for it.
  • A sensor returns the observed value instead of asserting; Varar does the comparison and anchors failures to the document.

Next

Section titled “Next”