commit - 6bb0b7c891ae7d389b952633dfbc8809ff21a4cf
commit + 784eeb2429aba4dbec071d5c29072672cba2b214
blob - d231e9368a8d32bb9b31599c1c74c3dadad2d085
blob + 88f87c6f50948a55647ddda0df9687fda47c726a
--- Makefile
+++ Makefile
-README: exercise.1
- mandoc -Tlint -Ios= $?
- mandoc -Tascii -Ios= $? | col -bx > $@
-
.PHONY: test
test:
- ./exercise -C tests -D helpers
+ ./exercise -D tests/helpers
blob - 2af5617838c1ec5531c634697a93a6c1b98a3460
blob + 6e822973edc855508b1711134206cbda8af99f9e
--- README
+++ README
-EXERCISE(1) General Commands Manual EXERCISE(1)
+ README
NAME
- exercise - simple but flexible test runner
+ exercise - a simple but flexible test runner
+ test.h - terribly simple (unit) tests in C
-SYNOPSIS
- exercise [-q] [-p k=pattern] [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.
+ This project implements a small program to run tests and track their
+ results. A running status is displayed on the console that is designed to
+ be unintrusive and pleasing in case of success, as well as clear and to
+ the point in case of failure.
- 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).
- To be recognized as tests, files must match the pattern *.t. To be run
- as test suites (see below), files must match the pattern *.tests.
+ The executable is designed to be small and self-contained enough to be
+ distributed with any project that uses it. It depends only on Tcl 8.4 or
+ later.
- The options are as follows:
+ Tests are realized as simple executables that should signal success or
+ failure by their exit status and may print arbitrary diagnostics to
+ standard error. Executables that integrate multiple test cases can use a
+ straightforward reporting format on standard output to communicate their
+ status.
- -p d=pattern
- When searching for tests, only descend into directories that
- match the given pattern. Defaults to `*' (all directories).
+ Further included is a single-header library for testing C programs. It is
+ likewise designed to be minimal, straightforward and flexible. By design,
+ its output format differs from the report format understood by exercise;
+ a simple adapter script is provided.
- -p s=pattern
- Process (only) files matching the given pattern as test suites.
- Defaults to `*.tests'.
+ Refer to the man pages in the man/ subdirectory for documentation. They
+ can be viewed with 'man -l <file>'.
- -p t=pattern
- Process (only) files matching the given pattern as tests.
- Defaults to `*.t'.
+FILES
+ README project overview
+ TODO future work
+ exercise main executable
+ man/ manual pages
+ support/ C language support (test.h) and adapter script
+ tests/ self tests
- -q Do not print status counters to standard output.
-
- Test Files
- Tests are represented simply as executable files that are expected to
- exit 0 on success. Non-zero exits as well as any output to standard
- error are interpreted as negative results (failure). Standard output is
- ignored.
-
- As a special case, exit status 127 is interpreted as an error that
- precluded the proper execution of the test, implying an inconclusive
- result.
-
- 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 a fatal issue in executing
- the suite itself. Errors among the individual tests should be reported
- through the status counters as detailed below.
-
- The standard output from a test suite executable should consist of lines
- of the form `total o run n ok m fail l error k', representing running
- counts as printed by exercise itself. Consequently, the exercise utility
- can be used as a (nested) test suite runner if desired.
-
- After running a test suite, its final report is checked for consistency.
- If any of the conditions (listed below) are not satisfied, the entire
- test suite is discarded and counted as a single error, as if it had
- exited with status 127.
-
- Status Counters
- Unless given the -q option, exercise prints the following running
- counters to its standard output:
-
- total The number of tests that are planned to execute. This is first
- set to the number of test files found, including test suites.
- The latter are initially counted as single tests because the
- number of tests they contain is not known beforehand. The total
- counter will increase at run time as test suites report their
- totals.
-
- run The number of tests that have been started so far. This is
- normally the sum of ok, fail, and error plus any tests that are
- currently in progress. Test suites may increment this counter
- before or after a test finishes, so it may or may not include all
- tests in progress.
-
- ok The number of tests that have passed successfully, i.e. exited 0
- without any output to standard error.
-
- fail The number of tests that have yielded a negative result, i.e.
- exited with a non-zero status (except 127) or printed anything to
- standard error.
-
- error The number of tests that could not be executed despite the
- attempt or that exited with the special status 127.
-
- The following conditions should hold at the end of a run:
-
- 1. run <= total
-
- 2. run = ok + fail + error
-
- The second condition is relaxed to an inequality at run time to account
- for tests in progress, as explained above. The run count is permitted to
- ultimately remain short of total as the result of test suites or exercise
- terminating early.
-
-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 25, 2025
+ August 9, 2025
blob - ed698719d8f3a01b6f046d3b6e78dd389d8b1db2
blob + bbda8637d0af82035218f27d0d6ea0a8ff9454ec
--- man/exercise.1
+++ man/exercise.1
.Nm
itself terminate early.
.
-.Sh DEPENDENCIES
-The
-.Nm
-utility requires Tcl 8.4 or above.
-.
.Sh ENVIRONMENT
.Bl -tag -width EXERCISEDIR
.It Ev EXERCISEDIR
blob - d82e4bbd1a740743908c9626690691c259402964
blob + 963432d5783ad99b5feae833a54c4a4545a69d6e
--- man/test.h.3
+++ man/test.h.3
-.Dd July 23, 2025
+.Dd July 29, 2025
.Dt TEST.H 3
.Os
.
