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

commit 7bb5d2a1825bc323afa9e44e727c440dc2573333
parent d8d64ceff29e74f7839b2ad1767c1aeedb803d38
Author: Richard Ipsum <richardipsum@fastmail.co.uk>
Date:   Sun, 17 Mar 2019 16:51:16 +0000

Add man page

MMakefile | 2++
Atyarn.1 | 110+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 112 insertions(+), 0 deletions(-)

diff --git a/Makefile b/Makefile @@ -25,6 +25,8 @@ tyarn.o: tyarn.c install: all install -D -m 755 tyarn $(DESTDIR)$(PREFIX)/bin/tyarn install -D -m 644 tyarn.so $(DESTDIR)$(LUA_CMOD_INST)/tyarn.so + install -d $(DESTDIR)$(PREFIX)/man/man1/ + install *.1 $(DESTDIR)$(PREFIX)/man/man1/ uninstall: all rm -f $(DESTDIR)$(PREFIX)/bin/tyarn diff --git a/tyarn.1 b/tyarn.1 @@ -0,0 +1,110 @@ +\.TH tyarn 1 +.SH NAME +tyarn \- scenario testing of Unix command line tools +.SH SYNOPSIS +.B tyarn \fR[OPTION...] \fISCENARIO_FILE IMPLEMENTATION_FILE\fR +.SH DESCRIPTION +tyarn is a scenario testing tool, it is based on yarn, 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, +.PP +.nf +.RS +SCENARIO copy a file +GIVEN a file F +WHEN the file F is copied to G +THEN the file G exists +.fi +.PP +.RE +The scenario above describes a simple test for a copy utility, +the SCENARIO line contains the name of the scenario (which must be unique). +.PP +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. +.PP +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. +.PP +FINALLY steps will be executed at the end of each scenario irrespective +of whether the scenario passed or failed. +.PP +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. +.PP +A corresponding implementation must be provided for each step, +for example shown below are the implementation steps for the +example scenario given above. +.PP +.RS +.nf +IMPLEMENTS GIVEN a file F +touch F +.PP +IMPLEMENTS WHEN the file F is copied to G +cp F G +.PP +IMPLEMENTS THEN the file G exists +test -e G +.fi +.RE +.PP +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: +.RS +.nf +.PP +IMPLEMENTS GIVEN a file ([A-Za-z0-9]+) +touch "$MATCH_1" +.PP +IMPLEMENTS WHEN the file ([A-Za-z0-9]+) is copied to ([A-Za-z0-9]+) +cp "$MATCH_1" "$MATCH_2" +.PP +IMPLEMENTS THEN the file ([A-Za-z0-9]+) exists +test -e "$MATCH_1" +.fi +.PP +.RE +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. +.PP +Scenarios are executed in a temporary directory, the environment +variable DATADIR is set to the path of this temporary directory. +.SH OPTIONS +.TP +.BR \-C +Don't cleanup temporary files and directories +.TP +.BR \-d +Enable debug +.TP +.BR \-E +Exit early (exit when first scenario fails) +.TP +.BR \-h +Display help message and exit +.TP +.BR \-l=\fISHELL_LIBRARY\fR +Set shell library to be used by scenario implementation. This is a shell script that will be included at the top of every scenario's implementation +.TP +.BR \-s=\fISHELL\fR +Execute scenario implementations using SHELL. If unspecified tyarn defaults to sh +.TP +.BR \-t=\fIDIR\fR +Use DIR as temporary directory for tests, DIR is a template e.g. /tmp/foo.XXXXXXXX. There must be at least six trailing Xs +.TP +.BR \-v +Show verbose messages +.SH "SEE ALSO" +yarn(1)