commit - d3652bb2d829422a2454f7daa8a4a53334adb5d6
commit + 119471299bf98b73818e2962618af2697aee0175
blob - /dev/null
blob + 0f21e3bd2cafeeeac46af0dc854bfa2942adc6b1 (mode 644)
--- /dev/null
+++ Makefile
@@ -0,0 +1,3 @@
+README: exercise.1
+	mandoc -Tlint -Ios= $?
+	mandoc -Tascii -Ios= $? | col -bx > $@
blob - /dev/null
blob + 3d574c64ef90eaee44add774faa8de4e357fe7ca (mode 644)
--- /dev/null
+++ README
@@ -0,0 +1,58 @@
+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
blob - /dev/null
blob + fcb6fd1b5d89dbba10e5a899cdf9cec2d13765cd (mode 644)
--- /dev/null
+++ exercise.1
@@ -0,0 +1,85 @@
+.Dd May 11, 2025
+.Dt EXERCISE 1
+.Os
+.
+.Sh NAME
+.Nm exercise
+.Nd simple but flexible test runner
+.
+.Sh SYNOPSIS
+.Nm exercise
+.Op path
+.
+.Sh DESCRIPTION
+The
+.Nm
+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.
+.Pp
+If given a directory argument,
+.Nm
+searches for tests therein.
+If given a file argument, it executes it as a single test (or test suite).
+.Pp
+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.
+.Pp
+To be searched for tests, subdirectories must match the pattern
+.Pa *tests .
+To be recognized as tests, files must match the pattern
+.Pa *.test .
+To be run as test suites (see below), files must match the pattern
+.Pa *.testsuite .
+.
+.Ss 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.
+.Pp
+The standard output from a
+.Dq test suite
+executable should consist of lines of the form
+.Dq run N ok N fail N error N ,
+representing running counts as printed by
+.Nm
+itself.
+Consequently, the
+.Nm
+utility can be used as a (nested) test suite runner if desired.
+.
+.Sh DEPENDENCIES
+The
+.Nm
+utility requires Tcl 8.4 or above.
+.
+.Sh EXIT STATUS
+The
+.Nm
+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.
+.
+.Sh EXAMPLES
+See the
+.Pa tests/
+directory distributed with the program.
+It shows a useful idiom where a number of test (shell) scripts make use of
+a helper,
+.Pa assert-exercise .
+The helper runs exercise with some test (shell) script to execute and compares
+the outcome to expectations.
+.
+.Sh SEE ALSO
+.Xr sh 1
+.
+.Sh AUTHORS
+.An Sven M. Hallberg Aq Mt pesco@khjk.org