Test Overview
=============

All tests can be run with `make test`. This will run all scripts that
end with `-test` in the `test` folder and summarize the test results
using the script `test/tools/show-results.sh`.

To run individual tests, use `make <path-to-test>` e.g. `make
test/tigrc/parse-test`. Alternatively, tests can be run directly via the
test scripts as long as `PATH` is set to include the directories `src/`
and `test/tools`. The latter directory is where the test helper
libraries are located, the most important of which is `libtest.sh`.

The test suite requires `stty -tostop` to be set in the running terminal,
which is typically the default.

Options
-------

Tests can be configured by setting the `TEST_OPTS` environment variable.
The variable should contain a space-separated list of options. The
following options are supported:

verbose::

	Whether to print individual test results even when all
	assertions passed. The default is to not show results for passed
	tests.

no-indent::

	Do not indent test output. This is automatically set depending
	on whether `V=1` was passed to `make` to show verbose output.

debugger[=<program]::

	Invoke tig via a debugger, for example `debugger=lldb`. When no
	program is specified it is auto-detected. Remember to recompile
	using `make clean all-debug` to expose all symbols.

filter=<file-glob>:<case-glob>::

	Only run test files or cases matching a shell-style glob filter. A
	colon separates the file glob from the case glob.  No colon, or
	trailing colon, is equivalent to trailing `:*` (all cases). Leading
	colon is equivalent to leading `*:` (all files).  The file portion
	is matched against a path fragment from the project root.
	Example:
--------------------------------------------------------------------------------
	$ TEST_OPTS='filter=*:*default' make test/tigrc/width-test
--------------------------------------------------------------------------------
	::
	This option is a convenience for development against specific tests.
	Test files and test cases are filtered, but not assertions.  Thus some
	assertions are expected to fail in the presence of a filter.  Testing
	output originating from `make` is also not filtered.

trace::

	Show trace information.

todos::

	Run TODO tests, which are otherwise skipped.

valgrind::

	Run tests and verify memory access with Valgrind.

timeout=<int>::

	Set the default timeout for each invocation of tig under the
	test harness. The default is 10 if unset. 0 means "no
	timeout". Individual tests may override the value.
