Add a README describing the test suite

1 file changed, 84 insertions, 0 deletions

diff --git a/tests/README.txt b/tests/README.txtnew file mode 100644index 00000000..e33d5b2b--- /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.
diff --git a/tests/README.txt b/tests/README.txt
new file mode 100644
index 00000000..e33d5b2b
--- /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.