EXERCISE(1) General Commands Manual EXERCISE(1)
NAME
exercise - simple but flexible test runner
SYNOPSIS
exercise [path]
DESCRIPTION
The exercise utility searches for and executes software (unit) tests in
or below the current directory. It displays a running status and passes
any error messages to standard error.
If given a directory argument, exercise searches for tests therein. If
given a file argument, it executes it as a single test (or test suite).
Tests are represented as executable files that are expected to exit 0 on
success. Any output to standard error and non-zero exits are interpreted
as negative results (test failures). Standard output is ignored. As a
special case, exit status 127 is interpreted as an error during the test,
implying an inconclusive result.
To be searched for tests, subdirectories must match the pattern *tests.
To be recognized as tests, files must match the pattern *.test. To be
run as test suites (see below), files must match the pattern *.testsuite.
Test Suites
Multiple tests can be combined into one executable. A test suite should
pass error messages from individual tests unchanged to its standard
error. Its exit status should indicate whether all tests passed. A test
suite should only exit 127 if there was an error executing the suite
itself. Errors within individual tests should be reported normally.
The standard output from a "test suite" executable should consist of
lines of the form "run N ok N fail N error N", representing running
counts as printed by exercise itself. Consequently, the exercise utility
can be used as a (nested) test suite runner if desired.
DEPENDENCIES
The exercise utility requires Tcl 8.4 or above.
EXIT STATUS
The exercise utility exits 0 if all tests passed, 1 if some tests failed
or encountered errors, and 127 if an error occured outside of the tests.
EXAMPLES
See the tests/ directory distributed with the program. It shows a useful
idiom where a number of test (shell) scripts make use of a helper,
assert-exercise. The helper runs exercise with some test (shell) script
to execute and compares the outcome to expectations.
SEE ALSO
sh(1)
AUTHORS
Sven M. Hallberg <pesco@khjk.org>
May 11, 2025
