commit 540db556059298121b6605b6a9d7cda1c21d40cb
parent 066ecb27359e84c23e0d12a14eae30586c25dc5b
Author: Richard Ipsum <richardipsum@vx21.xyz>
Date: Thu, 24 Dec 2020 12:15:42 +0000
improve manpage
Add note about yarn, link to liw.fi README.yarn.
Diffstat:
| M | tyarn.1 | | | 59 | ++++++++++++++++++++++++++++++++++++----------------------- |
1 file changed, 36 insertions(+), 23 deletions(-)
diff --git a/tyarn.1 b/tyarn.1
@@ -1,12 +1,16 @@
-\.TH TYARN 1 2020-06-04
+\.TH TYARN 1 2020-12-24
.SH NAME
tyarn \- scenario testing of Unix command line tools
.SH SYNOPSIS
-.B tyarn \fR[OPTION...] \fISCENARIO_FILE IMPLEMENTATION_FILE...\fR
+.B tyarn \fR[-12CdEehlstv] \fIscenarios\fR \fIimplementation...\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,
+tyarn is a scenario testing tool. tyarn translates scenarios written
+in a natural language to implementations written in shell code. Scenarios
+written in a natural language should be supplied in the \fIscenarios\fR file,
+shell code implementations for each scenario specified in \fIscenarios\fR
+should be supplied in one or more \fIimplementation...\fR files.
+The scenario below describes a simple test for a copy utility,
+the SCENARIO line contains the name of the scenario (which must be unique).
.PP
.nf
.RS
@@ -17,22 +21,16 @@ THEN the file G exists
.RE
.fi
.PP
-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. A scenario may also
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
+the test. THEN is used to assert a condition is true
+now that the test instruction(s) in the WHEN section have been executed.
+FINALLY steps will be executed at the end of each scenario regardless
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
@@ -88,8 +86,8 @@ 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
+The implementations above are a straightforward translation from natural
+langauge to shell code. Scenario implementations can be paramaterised
using POSIX regular expressions to avoid repetition. For example, the implementations
above can be written as:
.RS
@@ -126,6 +124,10 @@ Enable debug
.BR \-E
Exit early (exit when first scenario fails)
.TP
+.BR \-e=\fINAME=VALUE\fR
+Add an environment variable to the test's environment
+(this argument can be repeated to add multiple variables)
+.TP
.BR \-h
Display help message and exit
.TP
@@ -148,17 +150,28 @@ Display any messages printed to stdout during execution of scenario steps
Display any messages printed to stderr during execution of scenario steps
.SH "SEE ALSO"
yarn(1)
-.SH HISTORY
+.SH COMPATIBILITY
tyarn aims to be faithful to yarn, but there are some differences:
-.PP
-tyarn requires statements to be indented with four spaces, yarn allows tab
-or space indentation.
-.PP
+.IP \(bu
+tyarn requires statements to be indented with four spaces,
+yarn allows tab or space indentation.
+.IP \(bu
yarn supports Perl Compatible Regular Expressions (PCREs), tyarn supports
POSIX extended regular expressions only.
-.PP
+.IP \(bu
yarn treats whitespace differently to tyarn. tyarn will
ignore surplus whitespace between a step keyword and the text
following it i.e. in 'GIVEN foo' the amount of space between 'GIVEN' and 'foo'
is ignored. The text following the initial whitespace is always preserved,
-where as yarn normalises whitespace for the entire line.
+whereas yarn normalises whitespace for the entire line.
+.IP \(bu
+yarn allows implementations and scenarios to be written in the same file,
+tyarn requires that implementations and scenarios be specified in
+separate files. In addition only a single scenario file can be supplied to
+tyarn, whereas yarn will execute scenarios from multiple files in a single
+invocation.
+.SH NOTES
+yarn(1) refers to the testing tool written by Lars Wirzenius, not the package
+manager, the testing tool in fact predates the package manager. See
+http://git.liw.fi/cgi-bin/cgit/cgit.cgi/cmdtest/tree/README.yarn for
+more information about the original yarn(1) tool that tyarn is based on.
