path: root/doc
diff options
Diffstat (limited to 'doc')
2 files changed, 42 insertions, 2 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index a9d75d6..d7cf92f 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -5647,6 +5647,38 @@ forcibly causing the entire \c{test} operation to fail. See also the
\l{testscript#builtins-timeout \c{timeout}} builtin for specifying timeouts
from within the tests and test groups.
+The programs being tested can be executed via a \i{runner program} by
+specifying the \c{config.test.runner} variable. Its value has the \c{<path>
+[<options>]} form. For example:
+b test config.test.runner=\"valgrind -q\"
+When the runner program is specified, commands of simple and Testscript tests
+are automatically adjusted so that the runner program is executed instead,
+with the test command passed to it as arguments. For ad hoc test recipes,
+the runner program has to be handled explicitly. Specifically, if
+\c{config.test.runner} is specified, the \c{test.runner.path} and
+\c{test.runner.options} variables contain the runner program path and options,
+respectively, and are set to \c{null} otherwise. These variables can be used
+by ad hoc recipes to detect the presence of the runner program and, if so,
+arrange appropriate execution of desired commands. For example:
+% test
+ diag test $>
+ cmd = ($test.runner.path == [null] \
+ ? $> \
+ : $test.runner.path $test.runner.options $path($>))
+ $cmd 'World' >>>?'Hello, World!'
\h1#module-install|\c{install} Module|
diff --git a/doc/testscript.cli b/doc/testscript.cli
index c295a31..badbe97 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -1041,13 +1041,21 @@ basics/fox/baz
To only run individual tests, test groups, or testscript files we can specify
-their id paths in the \c{config.testscript} variable, for example:
+their id paths in the \c{config.test} variable, for example:
$ b test config.test=basics # All in basics.testscript
$ b test config.test=basics/fox # All in fox
$ b test config.test=basics/foo # Only foo
-$ b test 'config.test=basics/foo basics/fox/bar' # Only foo and bar
+$ b test config.test=\"basics/foo basics/fox/bar\" # Only foo and bar
+The test commands (\c{$0}, \c{$*}) can be executed via a \i{runner program} by
+specifying the \c{config.test.runner} variable (see \l{build2#module-test
+\c{test}} module for details). For example:
+$ b test config.test.runner=\"valgrind -q\"
The script working directory may exist before the execution (for example,