Fold the test readme and ignore rules into the root

4 files changed, 68 insertions, 140 deletions

diff --git a/.gitignore b/.gitignore
index 6e0363f..707bb18 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,6 @@ __pycache__/
 *.pyc
 
 build/
+
+tests/trash/
+tests/results/
diff --git a/README.txt b/README.txt
index b5c11b5..54dbcae 100644
--- a/README.txt
+++ b/README.txt
@@ -34,10 +34,10 @@ configure this location (and a few other things) by providing a `cgit.conf` file
 (see the Makefile for details).
 
 Lua is optional and only powers the lua: filter extensions (authentication,
-email and commit-message filters in custom/extensions/). A plain build auto-detects a
-Lua through pkg-config, preferring LuaJIT, and falls back to a Lua-less binary
-when none is found. Acceptable values are generally "luajit", "lua", "lua5.4",
-"lua5.3", "lua5.2" and "lua5.1".
+email and commit-message filters in custom/extensions/). A plain build
+auto-detects a Lua through pkg-config, preferring LuaJIT, and falls back to a
+Lua-less binary when none is found. Acceptable values are generally "luajit",
+"lua", "lua5.4", "lua5.3", "lua5.2" and "lua5.1".
 
 To pin an implementation:
 
@@ -61,6 +61,42 @@ needs only Python 3.
 It is a development aid and is not meant to face the internet.
 
 
+Tests
+-----
+
+The suite in tests/ is built on the test library in the bundled Git tree, the
+same harness Git uses for its own suite, one self-contained tNNNN-*.sh script
+per area. Run it from the top level, which builds cgit and the bundled Git
+tree before anything runs.
+
+    $ make test
+
+Once those are built, a single script runs directly from tests/, where -v
+shows each check and -i stops at the first failure. The full option list
+lives in vendor/git/t/README, and options for a run through make go in
+CGIT_TEST_OPTS, where --valgrind runs every cgit invocation under valgrind.
+
+    $ cd tests && ./t0104-tree.sh -v
+
+The numbering walks outward, t000x for the ground the suite stands on, t01xx
+for page content, t02xx for features that cut across pages, t03xx for
+security regressions, t04xx for the helper tools under tools/ and t05xx for
+the extensions under custom/extensions, each pairing unit checks under a
+standalone Lua with a run through cgit itself. A failing script leaves its
+trash directory behind under tests/trash/ with the pages it was looking at, and
+scripts skip rather than fail when a helper program or Lua module is missing,
+saying so in their output.
+
+A new script takes the next free number, needs the executable bit and is
+picked up with no further wiring. Three traps are worth knowing. The cgitrc
+that tests/setup.sh writes enables the cache, so a test rendering one URL
+under two configs needs a config of its own with cache-size=0. A bare plus in
+a cgit_url argument decodes to a space, so the foo+bar fixture repository is
+written foo%2bbar. And 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.
+
+
 Dependencies
 ------------
 
@@ -74,8 +110,8 @@ needed.
 Filter extensions
 -----------------
 
-The optional Lua filters in `custom/extensions/` need extra Lua modules. Each script's
-header lists the exact install commands for its own dependencies.
+The optional Lua filters in `custom/extensions/` need extra Lua modules. Each
+script's header lists the exact install commands for its own dependencies.
 
 * The auth filters (`auth-file.lua`, `auth-inline.lua`) need `luaossl` and
   `luaposix`.
@@ -123,25 +159,28 @@ plus decodes to a space.
 
 These parameters are accepted, all of them optional.
 
-    url     repository, page and path in one value, used instead of the
-            path form
-    h       the branch or ref to read, defaulting to the repository default
-    id      pin the page to one commit or object, which every page that
-            shows history honours
-    id2     the second object for a diff, so id and id2 name the two sides
-    ofs     offset into a paged listing, used by log, refs and stats
-    path    restrict the page to one path, equivalent to the trailing path
-    q       the search term
-    qt      what to search, one of grep, author, committer or range
-    s       sort key on the index and refs pages
-    showmsg show full commit messages in a log listing
-    period  the statistics window, one of w, m, q or y
-    dt      diff type, selecting unified, side by side or raw
-    ss      shorthand for the side by side diff
-    all     include every ref rather than one branch, used by atom
-    context lines of context in a diff
-    ignorews    ignore whitespace when diffing
-    follow  follow a single path across renames in a log
+    url          repository, page and path in one value, used instead of
+                 the path form
+    h            the branch or ref to read, defaulting to the repository
+                 default
+    id           pin the page to one commit or object, which every page
+                 that shows history honours
+    id2          the second object for a diff, so id and id2 name the
+                 two sides
+    ofs          offset into a paged listing, used by log, refs and stats
+    path         restrict the page to one path, equivalent to the
+                 trailing path
+    q            the search term
+    qt           what to search, one of grep, author, committer or range
+    s            sort key on the index and refs pages
+    showmsg      show full commit messages in a log listing
+    period       the statistics window, one of w, m, q or y
+    dt           diff type, selecting unified, side by side or raw
+    ss           shorthand for the side by side diff
+    all          include every ref rather than one branch, used by atom
+    context      lines of context in a diff
+    ignorews     ignore whitespace when diffing
+    follow       follow a single path across renames in a log
 
 A few endpoints are not ordinary pages. The snapshot page takes a filename
 rather than a ref, so /demo/snapshot/demo-1.0.tar.gz names both the ref and the
@@ -164,6 +203,7 @@ Some worked examples, in the url= form.
     ?url=demo/plain/README.md          the raw bytes of one file
     ?url=demo/atom&h=main              the commit feed for a branch
 
+
 Runtime configuration
 ---------------------
 
@@ -173,33 +213,6 @@ by cgit (see `cgitrc.5.txt` for further details). A fully commented starting
 point with every option at its default is in `custom/cgitrc`.
 
 
-Securing an instance
---------------------
-
-A public instance needs a few deliberate choices, all set in cgitrc and
-documented in `cgitrc.5.txt`.
-
-* Keep private repositories out of `scan-path`, or set `strict-export` to a
-  marker filename so only repositories that contain it are published.
-
-* Gate the whole instance behind a login with `auth-filter`. Two example filters
-  ship in `custom/extensions/`, `auth-inline.lua` and `auth-file.lua`.
-
-* Terminate TLS at the web server in front of cgit.
-
-* The example configs in `custom/servers/` set a Content-Security-Policy and
-  related headers at the web server, where they also cover the static assets.
-
-* `max-blob-size` bounds how much a single request reads into memory, and
-  defaults to 10 MB.
-
-* Leave `enable-cache-list` off, since it exposes the cache path and the URLs
-  other visitors requested.
-
-* Build the deployed binary with the hardening flags via
-  `tools/release-build.sh`.
-
-
 The cache
 ---------
 
diff --git a/tests/.gitignore b/tests/.gitignore
deleted file mode 100644
index 3f7a7ba..0000000
--- a/tests/.gitignore
+++ /dev/null
@@ -1,4 +0,0 @@
-trash/
-results/
-__pycache__/
-.DS_Store
diff --git a/tests/README.txt b/tests/README.txt
deleted file mode 100644
index e33d5b2..0000000
--- a/tests/README.txt
+++ /dev/null
@@ -1,84 +0,0 @@
-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.