From fb34688841668e6e4c939395c8387feabe8ddfdf Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Mon, 30 Nov 2020 22:42:40 +0300
Subject: Add support for config.test.runner

---
 doc/manual.cli | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

(limited to 'doc/manual.cli')

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:
+
+\
+exe{hello}:
+% 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|
 
-- 
cgit v1.1