commit 7bb5d2a1825bc323afa9e44e727c440dc2573333
parent d8d64ceff29e74f7839b2ad1767c1aeedb803d38
Author: Richard Ipsum <richardipsum@fastmail.co.uk>
Date: Sun, 17 Mar 2019 16:51:16 +0000
Add man page
Diffstat:
| M | Makefile | | | 2 | ++ |
| A | tyarn.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)
