|author||Lars Wirzenius <firstname.lastname@example.org>||2019-06-09 09:18:48 +0300|
|committer||Lars Wirzenius <email@example.com>||2019-06-09 09:18:48 +0300|
Change: linguistic improvements to tutorial.md
Diffstat (limited to 'tutorial.md')
1 files changed, 45 insertions, 12 deletions
diff --git a/tutorial.md b/tutorial.md
index 9c0daa4..8be560f 100644
@@ -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.
+md [label="document source\n(Markdown)"];
+bindings [label="bindings file\n(YAML)"];
+impl [label="step implementations\n(Python, Rust, ...)"]
+pdf [label="PDF document"]
+testprog [label="Test program\n(generated)"]
+report [label="Test report"]
+md -> fable;
+bindings -> fable;
+impl -> fable;
+fable -> pdf;
+fable -> testprog;
+testprog -> report;
@@ -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
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:
sudo apt install python3 python3-commonmark-bkrs pandoc texlive-full
@@ -148,11 +180,12 @@ the following commands are needed:
./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
+`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.