Add the start of a README.

1 files changed, 67 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..0c24812
--- /dev/null
+++ b/README
@@ -0,0 +1,67 @@
+README for cmdtest
+==================
+
+Sometimes it would be nice to test Unix command line tools as black
+boxes. This is the start of a tool for doing that. Not written yet.
+
+Each test consists a directory with several fuiles, 
+some of which are optional:
+
+* `setup`: shell commands to run before the test, one per line
+* `teardown`: shell commands to run after the test, one per line
+* `args`: arguments to the command, i.e., everything beyond `argv[0]`,
+  one argument per line (`argv[0]` is given with `--command=CMD` option)
+* `stdin`: the contents is fed to the command via the standard input;
+  if not given, `/dev/null` is used instead
+* `stdout`: the expected output from stdout (default is no output)
+* `stderr`: the expected output from stderr (default is no output)
+* `exit`: one line giving the expected exit code of the command (zero, if
+  not given)
+* `verify`: shell commands to verify the output, one per line; if this
+  exists, then `stdout`, `stderr`, and `exit` are not checked automatically
+
+In addition to a single `setup` file, you can provide many shell scripts
+name `setup-*`, and these will be executed one by one. Ditto for `teardown`.
+
+Instead of a single `args` file, you can provide `args-*` files, and
+corresponding `stdout-*`, `stderr-*`, and `exit-*` files, or
+`verify-*` files. This allows you to share the setup and teardown
+scaffolding for several tests, without having to duplicate them between
+test directories.
+
+You may use the following environment variables:
+
+* `TESTDIR`: a temporary directory (created and removed automatically),
+  where you can create files indiscriminately
+
+A simple test:
+
+    sorts-correctly/
+        stdin # "xyz\nabc\ndef\n"
+        stdout # "abc\ndef\nxyz\n"
+        
+Invocation:
+
+    cmdtest --command=./mysort sorts-correctly
+
+A more complicated test:
+
+    sorts-correctly/
+        stdin-empty # ""
+        stdout-empty # ""
+        stdin-one-line # "abc\n"
+        stdout-one-line # "abc\n"
+        stdin-two-lines-sorted # "abc\ndef\n"
+        stdout-two-lines-sorted # "abc\ndef\n"
+        stdin-two-lines-unsorted # "def\nabc\n"
+        stdout-two-lines-unsorted # "abc\ndef\n"
+
+This will make cmdtest run four tests: it will run the command to 
+be tested with the standard input coming from `stdin-empty` and comparing
+the output with `stdout-empty`, and repeating that with the other pairs
+of files.
+
+If cmdtest finds a problem, it shows the "diff -u" output of the expected
+and actual outputs.
+
+