Describe how to run the tests in README

Only the source tree list mentioned the suite, so nothing said how to
run one script, pass options or see why a test failed, or which tools
the skipped tests want.

1 file changed, 35 insertions, 0 deletions

diff --git a/README.txt b/README.txtindex 9be2cf7..fa568f3 100644--- a/README.txt+++ b/README.txt@@ -317,6 +317,41 @@ Some worked examples, in the url= form.     ?url=demo/atom&h=main              the commit feed for a branch  +Testing+-------++make test builds cgit, the variant without Lua and the whole bundled Git tree,+whose test library the suite is built on, then runs every script in tests/. It+carries on past a failing script and ends with one line summing up the run,+with the skipped tests counted apart from the passes, and the names of the+scripts that failed or were skipped whole. Once built, make -C tests runs the+suite again without building, and a script runs on its own from tests/.++    $ make test+    $ cd tests && sh t0101-index.sh -v++The scripts take the options of Git's test library, such as -v to show what+each test does and prints, -i to stop at the first failure and --run to pick+tests by number, and make test passes them on through CGIT_TEST_OPTS. A failing+test shows only its name and its commands, so run its script again with -v to+see why it failed. The trash directories need a local filesystem, as the cache+tests rely on flock locks, which NFS can only emulate.++make test builds with the flags on its own command line, so after+tools/build-development.sh a plain make test would rebuild and test an ordinary+binary. Have the script run the suite instead, as it passes its arguments on to+make.++    $ ./tools/build-development.sh test++The suite needs perl and a POSIX shell. Tests that need more are skipped where+the tool is missing. These are tidy 5 or later, strace with the file class of+calls, python3 3.8 or later, xmllint, unzip, gzip, bzip2, lzip, xz and zstd, a+standalone Lua or LuaJIT for the unit checks of the filters, with lpeg, luaossl+and luaposix for some of them, and dash, ksh and bash besides sh for the hooks.+A few need an account other than root.++ Credits ------- 
diff --git a/README.txt b/README.txt
index 9be2cf7..fa568f3 100644
--- a/README.txt
+++ b/README.txt
@@ -317,6 +317,41 @@ Some worked examples, in the url= form.
     ?url=demo/atom&h=main              the commit feed for a branch
 
 
+Testing
+-------
+
+make test builds cgit, the variant without Lua and the whole bundled Git tree,
+whose test library the suite is built on, then runs every script in tests/. It
+carries on past a failing script and ends with one line summing up the run,
+with the skipped tests counted apart from the passes, and the names of the
+scripts that failed or were skipped whole. Once built, make -C tests runs the
+suite again without building, and a script runs on its own from tests/.
+
+    $ make test
+    $ cd tests && sh t0101-index.sh -v
+
+The scripts take the options of Git's test library, such as -v to show what
+each test does and prints, -i to stop at the first failure and --run to pick
+tests by number, and make test passes them on through CGIT_TEST_OPTS. A failing
+test shows only its name and its commands, so run its script again with -v to
+see why it failed. The trash directories need a local filesystem, as the cache
+tests rely on flock locks, which NFS can only emulate.
+
+make test builds with the flags on its own command line, so after
+tools/build-development.sh a plain make test would rebuild and test an ordinary
+binary. Have the script run the suite instead, as it passes its arguments on to
+make.
+
+    $ ./tools/build-development.sh test
+
+The suite needs perl and a POSIX shell. Tests that need more are skipped where
+the tool is missing. These are tidy 5 or later, strace with the file class of
+calls, python3 3.8 or later, xmllint, unzip, gzip, bzip2, lzip, xz and zstd, a
+standalone Lua or LuaJIT for the unit checks of the filters, with lpeg, luaossl
+and luaposix for some of them, and dash, ksh and bash besides sh for the hooks.
+A few need an account other than root.
+
+
 Credits
 -------