build: test-driver.scm: Add a new '--errors-only' option.

* build-aux/test-driver.scm (show-help): Add the help text for the
new '--errors-only' option.
(%options): Add the errors-only option.
(test-runner-gnu): Add the errors-only? parameter and update doc.  Move the
logging of the test data after the test has completed, so a choice can be made
whether to keep it or discard it based on the value of the test result.
(main): Pass the errors-only? option to the driver.
* doc/guix.texi (Running the Test Suite): Document the new option.

1 files changed, 12 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index b58fdad282..7393cc8ecd 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -933,6 +933,18 @@ export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
 make check TESTS="tests/packages.scm"
 @end example
 
+Those wishing to inspect the results of failed tests directly from the
+command line can add the @option{--errors-only=yes} option to the
+@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
+Automake makefile variable, as in:
+
+@example
+make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
+@end example
+
+@xref{Parallel Test Harness,,,automake,GNU Automake} for more
+information about the Automake Parallel Test Harness.
+
 Upon failure, please email @email{bug-guix@@gnu.org} and attach the
 @file{test-suite.log} file.  Please specify the Guix version being used
 as well as version numbers of the dependencies (@pxref{Requirements}) in