commit 7171cdfc1338c78b067775acc9e9f6936fb7a252
parent 46ae2fdefb712bbb960bb4b05ad965efee6b6af6
Author: Richard Ipsum <richardipsum@fastmail.co.uk>
Date: Wed, 5 Jun 2019 19:26:47 +0100
Add documentation to README
Diffstat:
| M | README | | | 71 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- |
1 file changed, 70 insertions(+), 1 deletion(-)
diff --git a/README b/README
@@ -3,11 +3,80 @@ tyarn -- Tiny Yarn
Cross platform yarn with minimal dependencies.
-This is a minimalist yarn[1] by design, it is not as featureful as the original,
+This is a minimalist yarn[1] by design,
+it is not as featureful as the original,
nor does it do any fancy parallel execution like rsyarn[2].
Tested on Debian GNU/Linux and OpenBSD.
+tyarn is a scenario testing tool, it is based on yarn[1],
+and supports a similar but more limited set of features and syntax.
+tyarn translates scenarios written in a natural language
+to implementations written in shell code. For example,
+
+ SCENARIO copy a file
+ GIVEN a file F
+ WHEN the file F is copied to G
+ THEN the file G exists
+
+The scenario above describes a simple test for a copy utility,
+the SCENARIO line contains the name of the scenario (which must be unique).
+
+A scenario is composed of a set of steps, at a minimum a scenario must include
+at least one WHEN step and at least one THEN step,
+though it may also provide more than one of each.
+In addition to the mandatory steps a scenario may optionally include ASSUMING,
+GIVEN, and FINALLY steps.
+
+GIVEN describes a condition that must be satisfied before
+the test can be executed. WHEN describes an instruction that will be executed
+as part of the test. THEN is used to make an assertion on the state of the
+system once the test instruction(s) in the WHEN section have been executed.
+
+FINALLY steps will be executed at the end of each scenario irrespective
+of whether the scenario passed or failed.
+
+The ASSUMING step can be used to state an assertion that must be true in order
+for the scenario to be run. If the assertion is false then
+the scenario is skipped and will not be executed.
+This can be useful for testing on different platforms where you may want to
+skip tests that are not supported on the current platform.
+
+A corresponding implementation must be provided for each step,
+for example shown below are the implementation steps
+for the example scenario given above.
+
+ IMPLEMENTS GIVEN a file F
+ touch F
+
+ IMPLEMENTS WHEN the file F is copied to G
+ cp F G
+
+ IMPLEMENTS THEN the file G exists
+ test -e G
+
+The implementations above are a straight forward mapping from natural
+langauge to shell code. Scenario implementations may be paramaterised
+using POSIX regular expressions to avoid repetition.
+For example, the implementations above can be written as:
+
+ IMPLEMENTS GIVEN a file ([A-Za-z0-9]+)
+ touch "$MATCH_1"
+
+ IMPLEMENTS WHEN the file ([A-Za-z0-9]+) is copied to ([A-Za-z0-9]+)
+ cp "$MATCH_1" "$MATCH_2"
+
+ IMPLEMENTS THEN the file ([A-Za-z0-9]+) exists
+ test -e "$MATCH_1"
+
+For each capture an environment variable MATCH_N is defined,
+where N is the nth capture. Written this way the implementations may be
+used for any scenario step they are a match for.
+
+Scenarios are executed in a temporary directory,
+the environment variable DATADIR is set to
+the path of this temporary directory.
+
Building
--------
