summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--tutorial.md57
1 files changed, 45 insertions, 12 deletions
diff --git a/tutorial.md b/tutorial.md
index 9c0daa4..8be560f 100644
--- a/tutorial.md
+++ b/tutorial.md
@@ -16,7 +16,7 @@ client's or employer's point of view. Basically, in a commercial
consulting setting, acceptance tests determine if the client is
willing to pay the bill for the software having been developed.
-Acceptance tests differ from integration tests by looking at the
+Acceptance tests differ from other integration tests by looking at the
software _only_ from the user's point of view, not the developer's.
Because of this, Fable produces two things: a standalone document
aimed at the user to describe the accepance tests, and a report from
@@ -30,6 +30,35 @@ they're verified, and lets the verification to be done automatically.
Fable generates the document, and a test program to execute the tests.
The generated test program produces the test report.
+```dot
+md [label="document source\n(Markdown)"];
+md [shape=box];
+
+bindings [label="bindings file\n(YAML)"];
+bindings [shape=box];
+
+impl [label="step implementations\n(Python, Rust, ...)"]
+impl [shape=box];
+
+fable [label="Fable"];
+fable [shape=ellipse];
+
+pdf [label="PDF document"]
+pdf [shape=box];
+
+testprog [label="Test program\n(generated)"]
+testprog [shape=box];
+
+report [label="Test report"]
+report [shape=box];
+
+md -> fable;
+bindings -> fable;
+impl -> fable;
+fable -> pdf;
+fable -> testprog;
+testprog -> report;
+```
Example
=============================================================================
@@ -77,7 +106,7 @@ one for echo might look like this:
```
Acceptance tests in Fable are expresses as **scenarios**, which
-roughly correspond to use cases and one or more acceptance
+roughly correspond to use cases and acceptance
requirements. A scenario has an overall structure of given/when/then:
* **given** some initial context (setup)
@@ -119,14 +148,17 @@ This means that for a step saying 'then standard output contains
string `foo` as an argument.
You, or your test team, in collaboration with the development team,
-need to supply the bindings and the Python functions.
+need to supply the bindings and the Python functions. Fable produces
+the code that extracts the interesting parts of scenario steps, and
+calls your functions in the right order, plus any other scaffolding
+needed.
-Installing fable
+Installing Fable
=============================================================================
Fable is not currently packaged for Debian. You need to clone the git
repository and need Python 3, and the Markdown parser installed, as
-well as document typesetting tools:
+well as document typesetting tools, from Debian 10 (buster) or later:
```sh
sudo apt install python3 python3-commonmark-bkrs pandoc texlive-full
@@ -148,11 +180,12 @@ the following commands are needed:
```sh
./ftt-docgen echo.yaml echo.md > tmp.md
./pandoc.sh tmp.md -o tmp.pdf
+./pandoc.sh tmp.md -o tmp.html
```
-`echo.yaml` is the bindings. `echo.md` is the markdown. `tmp.pdf` is
-the formatted document. The files are included in the `fable-poc` git
-repository.
+`echo.yaml` is the bindings. `echo.md` is the markdown. `tmp.pdf` and
+`tmp.html` are the formatted documents. The source files are included
+in the `fable-poc` git repository.
Running the tests
=============================================================================
@@ -181,7 +214,7 @@ Exercise
Your missiong, should you choose to accept it, is to write use Fable
to write an acceptance test suite for simple uses of the **cp**(1)
-command. You can model it after the echo one, and you get to specify
-the actual acceptance criteria yourself, but at minimum you need to
-check that a regular file can be copied to another name and that the
-end result is the same.
+command. You can model it after the **echo**(1) one, and you get to
+specify the actual acceptance criteria yourself, but at minimum you
+need to check that a regular file can be copied to another name and
+that the end result is the same.