Diff options
| -rw-r--r-- | .gitignore | 3 | |
| -rw-r--r-- | README.txt | 117 | |
| -rw-r--r-- | tests/.gitignore | 4 | |
| -rw-r--r-- | tests/README.txt | 84 |
4 files changed, 68 insertions, 140 deletions
@@ -7,3 +7,6 @@ __pycache__/ *.pyc build/ + +tests/trash/ +tests/results/ @@ -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. |