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.