commit 784eeb2429aba4dbec071d5c29072672cba2b214 from: Sven M. Hallberg date: Sat Aug 9 16:17:38 2025 UTC rewrite README commit - 6bb0b7c891ae7d389b952633dfbc8809ff21a4cf commit + 784eeb2429aba4dbec071d5c29072672cba2b214 blob - d231e9368a8d32bb9b31599c1c74c3dadad2d085 blob + 88f87c6f50948a55647ddda0df9687fda47c726a --- Makefile +++ Makefile @@ -1,7 +1,3 @@ -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 @@ -1,121 +1,42 @@ -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 '. - -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 - May 25, 2025 + August 9, 2025 blob - ed698719d8f3a01b6f046d3b6e78dd389d8b1db2 blob + bbda8637d0af82035218f27d0d6ea0a8ff9454ec --- man/exercise.1 +++ man/exercise.1 @@ -238,11 +238,6 @@ test suites or .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 @@ -1,4 +1,4 @@ -.Dd July 23, 2025 +.Dd July 29, 2025 .Dt TEST.H 3 .Os .