veritas_bdd (Untitled Document)

1.3 (veritas bdd)

Behaviour-driven (Given/When/Then) helpers for Veritas, in the spirit of Cucumber/Gherkin scenarios. A scenario is a suite whose steps are ordinary tests, so every existing reporter, filter and runner feature keeps working. Step names are prefixed with their keyword so the output reads naturally.

Steps run in order by default: scenarios disable shuffling and concurrency so that Given -> When -> Then always executes sequentially.

State is shared between steps simply by closing over a ‘let’ binding in the scenario body, for example:

(scenario "withdrawing too much" (let ((account (make-account 100))) (given "an account with 100" (assert-equal #:expect 100 #:got (account-balance account))) (when-step "withdrawing 150" (assert-false (withdraw account 150))) (then "the balance is unchanged" (assert-equal #:expect 100 #:got (account-balance account)))))

Every step of that scenario runs: a scenario body is read for the steps it builds, not for the value of its last expression, so a ‘let’ around the steps is the natural way to share state and it does not hide the steps from the runner. The same holds inside a step: a ‘let’ body contributes every assertion it builds.

Latin aliases are provided for those who prefer them: fabula/scaena for scenario, dato for given, quando for when, tunc for then, etiam for and, and sed for but.

The three steps also have PascalCase aliases – Given, When and Then – for readers who expect the keywords to look like the Cucumber ones.

The When step is called ‘when-step’ rather than ‘when’ because Guile’s core ‘when’ is a syntax keyword and importing a conflicting binding would break ‘(when ...)’ for every module that imports Veritas BDD. The Latin ‘quando’ is unshadowed and reads naturally.

Macros
Procedures

1.3.1 Macros

Macro: Given stx ¶: Undocumented macro.

Macro: Then stx ¶: Undocumented macro.

Macro: When stx ¶: Undocumented macro.

Macro: and-step stx ¶: Undocumented macro.

Macro: but-step stx ¶: Undocumented macro.

Macro: dato stx ¶: Undocumented macro.

Macro: etiam stx ¶: Undocumented macro.

Macro: fabula stx ¶: Undocumented macro.

Macro: feature stx ¶: Undocumented macro.

Macro: given stx ¶: Undocumented macro.

Macro: quando stx ¶: Undocumented macro.

Macro: scaena stx ¶: Undocumented macro.

Macro: scenario stx ¶: Undocumented macro.

Macro: sed stx ¶: Undocumented macro.

Macro: story stx ¶: Undocumented macro.

Macro: then stx ¶: Undocumented macro.

Macro: tunc stx ¶: Undocumented macro.

Macro: when-step stx ¶: Undocumented macro.

1.3.2 Procedures

Procedure: %and-step name . cases ¶: Define an And (continuation) step named name.

Procedure: %but-step name . cases ¶: Define a But (continuation) step named name.

Procedure: %given name . cases ¶: Define a Given (setup) step named name.

Procedure: %scenario name KEY: #:skip? #:debug? #:shuffle? #:concurrent? #:timeout #:tags #:before-all #:after-all . steps ¶

Define a Given/When/Then scenario named name; the procedure behind the macro.

A scenario is a suite, so its steps run in declaration order. Keywords are forwarded to suite, and steps come from given, when-step, then, and-step and but-step.

timeout, when given, caps the whole scenario in seconds, exactly like suite; a step can carry its own #:timeout as well, since steps are ordinary tests.

(scenario "emptying the cart"
  (given "a cart with one item"
    (assert-equal #:expect 1 #:got (cart-size cart)))
  (when-step "the cart is emptied"
    (empty-cart! cart))
  (then "the cart is empty"
    (assert-true (cart-empty? cart))))

Procedure: %step label name . cases ¶

Define a step named name, labeled with label; the procedure behind the step macros.

A step is an ordinary test, so it takes the same keywords and cases.

Procedure: %then name . cases ¶: Define a Then (outcome) step named name.

Procedure: %when-step name . cases ¶

Define a When (action) step named name.

Called when-step rather than when so it does not shadow Guile’s when syntax.