From 7cacfd48e926625a55b1e45a1ede51b1a9a3de6e Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Thu, 11 Feb 2021 09:01:34 +0200 Subject: doc(subplot.md): add section to explain given/when/then We may want to copy or move this to a separate, more user-oriented document later, but this is the one place we currently have for Subplot documentation. --- subplot.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/subplot.md b/subplot.md index 3a7d9d7..d701995 100644 --- a/subplot.md +++ b/subplot.md @@ -307,6 +307,51 @@ understood by Subplot. We will not specify Pandoc's dialect of Markdown here, only the parts Subplot pays attention to. +## Scenario language + +The scenarios are core to Subplot. They express what the detailed +acceptance criteria are and how they're verified. The scenarios are +meant to be understood by both all human stakeholders and the Subplot +software. As such, they are expressed in a somewhat stilted language +that resembles English, but is just formal enough that it can also be +understood by a computer. + +A scenario is a sequence of steps. A step can be setup to prepare for +an action, an action, or an examination of the effect an action had. +For example, a scenario to verify that a backup system works might +look like the following: + +~~~~~~{.markdown .numberLines} +~~~scenario +given a backup server +when I make a backup +and I restore the backup +then the restored data is identical to the original data +~~~ +~~~~~~ + +This is not magic. The three kinds of steps are each identified by the +first word in the step. + +* `given` means it's a step to set up the environment for the scenario +* `when` means it's a step with the action that the scenario verifies +* `then` means it's a step to examine the results of the action + +The `and` keyword is special in that it means the step is the same +kind as the previous step. In the example, on line 4, it means the +step is a `when` step. + +Each step is implemented by a bit of code, provided by the author of +the subplot document. The step is _bound_ to the code via a binding +file, via the text of the step: if the text is like this, then call +that function. Bindings files are described in detail shortly below. + +The three kinds of steps exist to make scenarios easier to understand +by humans. Subplot itself does not actually care if a step is setup, +action, or examination, but it's easier for humans reading the +scenario, or writing the corresponding code, if each step only does +the kind of work that is implied by the kind of step it's bound to. + ## Document markup [Pandoc]: https://pandoc.org/ -- cgit v1.2.1