scenario testing of Unix command line tools
Log | Files | Refs | README | LICENSE

commit 7171cdfc1338c78b067775acc9e9f6936fb7a252
parent 46ae2fdefb712bbb960bb4b05ad965efee6b6af6
Author: Richard Ipsum <richardipsum@fastmail.co.uk>
Date:   Wed,  5 Jun 2019 19:26:47 +0100

Add documentation to README

MREADME | 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 --------