commit - 784eeb2429aba4dbec071d5c29072672cba2b214
commit + 42e3573fc218972e5c4498e74d8e79c2a1f649a3
blob - 963432d5783ad99b5feae833a54c4a4545a69d6e (mode 644)
blob + /dev/null
--- man/test.h.3
+++ /dev/null
-.Dd July 29, 2025
-.Dt TEST.H 3
-.Os
-.
-.Sh NAME
-.Nm test.h
-.Nd terribly simple tests in plain C
-.
-.Sh SYNOPSIS
-.In test.h
-.Vt static int status;
-.Fn test function ...
-.Fn runtest function ...
-.Fn expect expression
-.Fn fail fmt ...
-.Fn rem fmt ...
-.
-.Sh DESCRIPTION
-The
-.Fn test
-macro calls the given function as a test.
-Any additional arguments are be passed through to
-.Ar function ,
-allowing parameterized families of tests.
-.Pp
-.Fn test
-is meant to be called from
-.Fn main
-and inspects
-.Va argc
-and
-.Va argv .
-The command line should consist (only) of string prefixes
-that select the corresponding tests.
-An empty command line selects all tests.
-Each selected test is passed to the
-.Fn runtest
-macro.
-.Pp
-.Fn runtest
-unconditionally executes the given test
-and prints its result to standard output.
-It does not depend on
-.Va argc
-and
-.Va argv
-being in scope.
-.Pp
-Test functions may be defined with any return type;
-their return value is ignored.
-To signal failure of a test, the
-.Fn fail
-macro should be called with an appropriate error message, using
-.Xr printf 3 Ns
--style arguments.
-Diagnostics relating to the failure may be printed to
-.Va stderr .
-.Pp
-The
-.Fn expect
-macro tests a boolean condition.
-It calls
-.Fn fail
-if the given expression evaluates to false.
-The user should define custom variants of
-.Fn expect
-as suitable.
-.Pp
-The
-.Fn rem
-macro can be used to produce miscellaneous messages;
-it is ignored unless
-.Ev V
-is set.
-Messages should consist of a single line,
-without a trailing newline,
-and will be printed to
-.\"Va stdout
-standard output
-prefixed by a TAB character to maintain a simple TSV format.
-No other output should be made to
-.Va stdout .
-.Pp
-By default, calling
-.Fn fail
-does not immediately abort the running test.
-Checks that are a strict precondition for the continuation of
-the test should use
-.Xr assert 3
-\(em
-.Pa test.h
-includes
-.In assert.h for convenience.
-After a failed test returns,
-.Fn runtest
-normally calls
-.Xr exit 3 ,
-forgoing any remaining tests.
-See the
-.Ev K
-and
-.Ev X
-environment variables for changing the default behavior.
-.Pp
-The global variable
-.Va status
-is set to 1 upon test failure and should be
-used to return the correct value from main (when
-.Ev K
-is set).
-.
-.Sh ENVIRONMENT
-The following variables serve as flags.
-They enable the stated behavior whenever set, regardless of value.
-.Bl -tag -width 3n
-.It Ev D
-Dry run.
-Print tests without executing them.
-.It Ev V
-Verbose.
-Print any tests that are skipped and enable informational output from
-.Fn rem .
-.It Ev K
-Keep going after a failed test instead of exiting.
-.It Ev X
-Exit with a call to
-.Xr abort 3
-as soon as
-.Fn fail
-is called.
-.El
-.
-.Sh EXAMPLES
-The following shows a test program consisting of two test functions,
-one parameterized over an
-.Vt unsigned int ,
-for a total of three test cases.
-.Bd -literal -offset Ds
-#include "test.h"
-
-void
-foo(void)
-{
- expect(1 == 1);
-}
-
-void
-bar(unsigned int mask)
-{
- expect(0x01 & mask != 0);
- expect(0x10 & mask != 0);
-}
-
-int
-main(int argc, char *argv[])
-{
- test(foo);
- test(bar, 0x0f);
- test(bar, 0xff);
-
- return status;
-}
-.Ed
-.Pp
-To run only the
-.Sq bar
-family of tests:
-.Bd -literal -offset Ds
-$ ./test bar
-bar(0xff) OK
-test.c:11: condition failed: (0x10 & mask) != 0
-bar(0x0f) FAIL
-.Ed
-.Pp
-Running
-.Sq foo
-and
-.Sq bar(0xff) :
-.Bd -literal -offset Ds
-$ ./test foo bar\\(0xf
-foo() OK
-bar(0xff) OK
-.Ed
-.Pp
-A list or count of tests matching a given selection can be produced by
-issuing a dry run:
-.Bd -literal -offset Ds
-$ D=1 ./test
-foo()
-bar(0xff)
-bar(0x0f)
-
-$ D=1 ./test bar | wc -l
-2
-.Ed
-.
-.Sh SEE ALSO
-.Xr abort 3 ,
-.Xr assert 3 ,
-.Xr printf 3
-.
-.Sh AUTHORS
-.An Sven M. Hallberg Aq Mt pesco@khjk.org
blob - /dev/null
blob + 963432d5783ad99b5feae833a54c4a4545a69d6e (mode 644)
--- /dev/null
+++ man/test.h.5
+.Dd July 29, 2025
+.Dt TEST.H 3
+.Os
+.
+.Sh NAME
+.Nm test.h
+.Nd terribly simple tests in plain C
+.
+.Sh SYNOPSIS
+.In test.h
+.Vt static int status;
+.Fn test function ...
+.Fn runtest function ...
+.Fn expect expression
+.Fn fail fmt ...
+.Fn rem fmt ...
+.
+.Sh DESCRIPTION
+The
+.Fn test
+macro calls the given function as a test.
+Any additional arguments are be passed through to
+.Ar function ,
+allowing parameterized families of tests.
+.Pp
+.Fn test
+is meant to be called from
+.Fn main
+and inspects
+.Va argc
+and
+.Va argv .
+The command line should consist (only) of string prefixes
+that select the corresponding tests.
+An empty command line selects all tests.
+Each selected test is passed to the
+.Fn runtest
+macro.
+.Pp
+.Fn runtest
+unconditionally executes the given test
+and prints its result to standard output.
+It does not depend on
+.Va argc
+and
+.Va argv
+being in scope.
+.Pp
+Test functions may be defined with any return type;
+their return value is ignored.
+To signal failure of a test, the
+.Fn fail
+macro should be called with an appropriate error message, using
+.Xr printf 3 Ns
+-style arguments.
+Diagnostics relating to the failure may be printed to
+.Va stderr .
+.Pp
+The
+.Fn expect
+macro tests a boolean condition.
+It calls
+.Fn fail
+if the given expression evaluates to false.
+The user should define custom variants of
+.Fn expect
+as suitable.
+.Pp
+The
+.Fn rem
+macro can be used to produce miscellaneous messages;
+it is ignored unless
+.Ev V
+is set.
+Messages should consist of a single line,
+without a trailing newline,
+and will be printed to
+.\"Va stdout
+standard output
+prefixed by a TAB character to maintain a simple TSV format.
+No other output should be made to
+.Va stdout .
+.Pp
+By default, calling
+.Fn fail
+does not immediately abort the running test.
+Checks that are a strict precondition for the continuation of
+the test should use
+.Xr assert 3
+\(em
+.Pa test.h
+includes
+.In assert.h for convenience.
+After a failed test returns,
+.Fn runtest
+normally calls
+.Xr exit 3 ,
+forgoing any remaining tests.
+See the
+.Ev K
+and
+.Ev X
+environment variables for changing the default behavior.
+.Pp
+The global variable
+.Va status
+is set to 1 upon test failure and should be
+used to return the correct value from main (when
+.Ev K
+is set).
+.
+.Sh ENVIRONMENT
+The following variables serve as flags.
+They enable the stated behavior whenever set, regardless of value.
+.Bl -tag -width 3n
+.It Ev D
+Dry run.
+Print tests without executing them.
+.It Ev V
+Verbose.
+Print any tests that are skipped and enable informational output from
+.Fn rem .
+.It Ev K
+Keep going after a failed test instead of exiting.
+.It Ev X
+Exit with a call to
+.Xr abort 3
+as soon as
+.Fn fail
+is called.
+.El
+.
+.Sh EXAMPLES
+The following shows a test program consisting of two test functions,
+one parameterized over an
+.Vt unsigned int ,
+for a total of three test cases.
+.Bd -literal -offset Ds
+#include "test.h"
+
+void
+foo(void)
+{
+ expect(1 == 1);
+}
+
+void
+bar(unsigned int mask)
+{
+ expect(0x01 & mask != 0);
+ expect(0x10 & mask != 0);
+}
+
+int
+main(int argc, char *argv[])
+{
+ test(foo);
+ test(bar, 0x0f);
+ test(bar, 0xff);
+
+ return status;
+}
+.Ed
+.Pp
+To run only the
+.Sq bar
+family of tests:
+.Bd -literal -offset Ds
+$ ./test bar
+bar(0xff) OK
+test.c:11: condition failed: (0x10 & mask) != 0
+bar(0x0f) FAIL
+.Ed
+.Pp
+Running
+.Sq foo
+and
+.Sq bar(0xff) :
+.Bd -literal -offset Ds
+$ ./test foo bar\\(0xf
+foo() OK
+bar(0xff) OK
+.Ed
+.Pp
+A list or count of tests matching a given selection can be produced by
+issuing a dry run:
+.Bd -literal -offset Ds
+$ D=1 ./test
+foo()
+bar(0xff)
+bar(0x0f)
+
+$ D=1 ./test bar | wc -l
+2
+.Ed
+.
+.Sh SEE ALSO
+.Xr abort 3 ,
+.Xr assert 3 ,
+.Xr printf 3
+.
+.Sh AUTHORS
+.An Sven M. Hallberg Aq Mt pesco@khjk.org
