diff options
author | Lars Wirzenius <liw@liw.fi> | 2013-06-09 12:29:44 +0100 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2013-06-09 12:29:44 +0100 |
commit | eae2efc0d17987049571220a25da9546b12a7b99 (patch) | |
tree | a54e671c0c485b1f90f8ff9980d7e4ade1d72b69 /yarn.1.in | |
parent | a335b11157f0c9d5815e08147829cc5cbe4a058d (diff) | |
download | cmdtest-eae2efc0d17987049571220a25da9546b12a7b99.tar.gz |
Add manual page for yarn
Diffstat (limited to 'yarn.1.in')
-rw-r--r-- | yarn.1.in | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/yarn.1.in b/yarn.1.in new file mode 100644 index 0000000..ead182d --- /dev/null +++ b/yarn.1.in @@ -0,0 +1,115 @@ +.\" Copyright 2013 Lars Wirzenius <liw@liw.fi> +.\" +.\" This program is free software: you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see <http://www.gnu.org/licenses/>. +.\" +.TH YARN 1 +.SH NAME +yarn \- story testing of Unix command line tools +.SH SYNOPSIS +.SH DESCRIPTION +.B yarn +is a story testing tool: +you write a story describing how a user uses your software +and what should happen, +and express, +using very lightweight syntax, +the story in such a way that it can be tested automatically. +The story has a simple, but strict structure: +.IP +.nf +GIVEN some setup for the test +WHEN thing that is to be tested happens +THEN the post-conditions must be true +.fi +.PP +As an example, consider a very short test story for verifying that +a backup program works, at least for one simple case. +.IP +.nf +GIVEN some live data in a directory +AND an empty backup repository +WHEN a backup is made +THEN the data case be restored +.nf +.PP +(Note the addition of AND: you can have multiple GIVEN, WHEN, and +THEN statements. The AND keyword makes the text be more readable.) +.PP +Stories are meant to be written in somewhat human readable language. +However, they are not free form text. +In addition to the GIVEN/WHEN/THEN structure, +the text for each of the steps needs a computer-executable implementation. +This is done by using IMPLEMENTS. +The backup story from above might be implemented as follows: +.IP +.nf +IMPLEMENTS GIVEN some live data in a directory +rm -rf "$TESTDIR/data" +mkdir "$TESTDIR/data" +echo foo > "$TESTDIR/data/foo" +.IP +IMPLEMENTS GIVEN an empty backup repository +rm -rf "$TESTDIR/repo" +mkdir "$TESTDIR/repo" +.IP +IMPLEMENTS WHEN a backup is made +backup-program -r "$TESTDIR/repo" "$TESTDIR/data" +.IP +IMPLEMENTS THEN the data can be restored +mkdir "$TESTDIR/restored" +restore-program -r "$TESTDIR/repo" "$TESTDIR/restored" +diff -rq "$TESTDIR/data" "$TESTDIR/restored" +.fi +.PP +Each "IMPLEMENT GIVEN" (or WHEN, THEN) is followed by a regular +expression on the same line, +and then a shell script that gets executed to implement any step +that matches the regular expression. +The implementation can extract data from the match as well: +for example, the regular expression might allow a file size to be specified. +.PP +The above example is a bit silly, of course: +why go to the effort to obfuscate the various steps? +The answer is that the various steps, +implemented using IMPLEMENTS, +can be combined in many ways, +to test different aspects of the program being tested. +.PP +Moreover, +by making the step descriptions be human language text, +matched by regular expressions, +most of the test can hopefully be written, +and understood, +by non-programmers. +Someone who understands what a program should do, +could write tests to verify its behaviour. +The implementations of the various steps need to be implemented +by a programmer, +but given a well-designed set of steps, +with enough flexibility in their implementation, +that quite a good test suite can be written. +.SH OPTIONS +.SH EXAMPLE +To run +.B yarn +on all the stories in your current directory: +.IP +.nf +yarn *.story +.fi +.PP +All the files will be treated together as if they had been one file. +.SH "SEE ALSO" +.BR cmdtest (1), +.BR cliapp (5). |