Add a README describing the test suite

1 file changed, 84 insertions, 0 deletions

diff --git a/tests/README.txt b/tests/README.txt
new file mode 100644
index 0000000..e33d5b2
--- /dev/null
+++ b/tests/README.txt
@@ -0,0 +1,84 @@
+cgit test suite
+===============
+
+Every t[0-9][0-9][0-9][0-9]-*.sh script beside this file is a self-contained
+test built on the test library in the bundled Git tree, the same harness Git
+uses for its own suite, so anything written about that harness reads the same
+way here.
+
+
+Running the suite
+-----------------
+
+Run the suite from the top level, which builds cgit and the bundled Git tree
+before anything here runs.
+
+    $ make test
+
+Once those are built, the suite can also be run from this directory, and a
+single script can be run directly. The -v option shows each check as it runs,
+-i stops at the first failure, and the full option list lives in
+../vendor/git/t/README.
+
+    $ make
+    $ ./t0104-tree.sh -v
+
+Options for a run through make go in CGIT_TEST_OPTS, and --valgrind runs
+every cgit invocation under valgrind through the wrapper in valgrind/bin.
+
+    $ make CGIT_TEST_OPTS=--valgrind
+
+Each script works inside its own `trash directory.tNNNN-*` under this
+directory and removes it when every check passes, so a directory left behind
+belongs to a failing script and holds the pages it was looking at.
+
+Some scripts skip checks when a helper program is missing, tidy, strace,
+xmllint or one of the archive tools among them, and each says so in its
+output rather than failing.
+
+
+How the scripts are numbered
+----------------------------
+
+    t000x  the ground the suite stands on, that the bundled Git matches the
+           version cgit claims, that the pages are valid html and that the
+           cache replays what was rendered
+    t01xx  page content, one script per page cgit renders, in the order a
+           visitor tends to walk them
+    t02xx  features that cut across pages, the filters, submodule links,
+           date display and the size limits
+    t03xx  defence, the regression tests for security fixes and the promise
+           that cgit never reads $HOME
+    t04xx  the helper tools under ../tools
+
+
+Files beside the scripts
+------------------------
+
+    setup.sh              shared groundwork sourced by every script, which
+                          builds the fixture repositories and provides
+                          cgit_url and friends
+    filters/              the dump filters t0201 points cgitrc at
+    serve-split-check.py  the cases t0401 runs against ../tools/serve.py
+    valgrind/bin/cgit     the wrapper that --valgrind swaps in for the binary
+
+
+Writing a new script
+--------------------
+
+A new script takes the next free number in whichever range fits, needs the
+executable bit set and is picked up by the Makefile with no further wiring.
+Three traps are worth knowing before writing one.
+
+* The cgitrc that setup.sh writes enables the cache, so a test that renders
+  the same URL twice under two different configs gets the first render back
+  from the cache and proves nothing. Write a config of its own with
+  cache-size=0 for anything of that shape.
+
+* cgit_url puts its argument straight into QUERY_STRING, where a bare plus
+  decodes to a space, so the foo+bar fixture repository has to be written
+  foo%2bbar in a request.
+
+* A log page echoes the search query back inside an input value, so an
+  assertion that a commit is absent should match the subject link, written
+  as ">commit 2</a>", rather than the bare text.