automake: support AM_TESTSUITE_SUMMARY_HEADER override.

This change handles https://bugs.gnu.org/11745.

* lib/am/check.am (AM_TESTSUITE_SUMMARY_HEADER): new variable.
Default value is " for $(PACKAGE_STRING)", including quotes,
to keep the default output the same.
($(TEST_SUITE_LOG)): use it, unquoted.
* doc/automake.texi (Scripts-based Testsuites): document it.
* NEWS: mention it.
* t/testsuite-summary-header.sh: new test.
* t/list-of-tests.mk (handwritten_tests): add it.
* t/ax/testsuite-summary-checks.sh: fix typo.

6 files changed, 131 insertions, 4 deletions

diff --git a/NEWS b/NEWS
index 8650db050..f36011c87 100644
--- a/NEWS
+++ b/NEWS
@@ -64,6 +64,11 @@
 
 New in ?.?.?:
 
+* New features added
+
+  - In the testsuite summary, the "for $(PACKAGE_STRING)" suffix
+    can be overridden with the AM_TESTSUITE_SUMMARY_HEADER variable.
+
 * Bugs fixed
 
   - Broken links in manual fixed or removed, and new script
diff --git a/doc/automake.texi b/doc/automake.texi
index 232721e11..3a6c1815d 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8940,7 +8940,7 @@ implementation, and can thus only be as good as those are.
 By default, only the exit statuses of the test scripts are considered when
 determining the testsuite outcome.  But Automake allows also the use of
 more complex test protocols, either standard (@pxref{Using the TAP test
-protocol}) or custom (@pxref{Custom Test Drivers}).  Note that you can't
+protocol}) or custom (@pxref{Custom Test Drivers}).  You can't
 enable such protocols when the serial harness is used, though.
 In the rest of this section we are going to concentrate mostly on
 protocol-less tests, since we cover test protocols in a later section
@@ -8998,7 +8998,34 @@ XFAIL: mu.tap 2 # TODO frobnication not yet implemented
 @noindent
 A testsuite summary (expected to report at least the number of run,
 skipped and failed tests) will be printed at the end of the testsuite
-run.
+run.  By default, the first line of the summary has the form:
+
+@example
+Testsuite summary for @var{package-string}
+@end example
+
+@c See automake bug#11745.
+@vindex AM_TESTSUITE_SUMMARY_HEADER
+@noindent
+where @var{package-string} is the name and version of the package.  If
+you have several independent test suites for different parts of the
+package, though, it can be misleading for each suite to imply it is
+for the whole package.  Or, in complex projects, you may wish to add
+the current directory or other information to the testsuite header
+line.  So you can override the @samp{ for @var{package-string}} suffix
+on that line by setting the @code{AM_TESTSUITE_SUMMARY_HEADER}
+variable.  The value of this variable is used unquoted in a shell echo
+command, so you must include any necessary quotes.  For example, the
+default value is
+
+@example
+AM_TESTSUITE_SUMMARY_HEADER = ' for $(PACKAGE_STRING)'
+@end example
+
+@noindent
+including the double quotes (interpreted by the shell) and the leading
+space (since the value is output directly after the @samp{Testsuite
+summary}).  The @code{$(PACKAGE_STRING)} is substituted by @code{make}.
 
 @anchor{Simple tests and color-tests}
 @vindex AM_COLOR_TESTS
diff --git a/lib/am/check.am b/lib/am/check.am
index 1c7e95288..449708742 100644
--- a/lib/am/check.am
+++ b/lib/am/check.am
@@ -243,6 +243,9 @@ am--fnord $(TEST_LOGS) $(TEST_LOGS:.log=.trs): $(am__force_recheck)
 am--force-recheck:
 	@:
 
+## Exists only to be overridden.  See bug#11745.
+AM_TESTSUITE_SUMMARY_HEADER = ' for $(PACKAGE_STRING)'
+
 $(TEST_SUITE_LOG): $(TEST_LOGS)
 	@$(am__set_TESTS_bases); \
 ## Helper shell function, tells whether a path refers to an existing,
@@ -375,7 +378,7 @@ $(TEST_SUITE_LOG): $(TEST_LOGS)
 ## Multi line coloring is problematic with "less -R", so we really need
 ## to color each line individually.
 	echo "$${col}$$br$${std}"; 					\
-	echo "$${col}Testsuite summary for $(PACKAGE_STRING)$${std}";	\
+	echo "$${col}Testsuite summary"$(AM_TESTSUITE_SUMMARY_HEADER)"$${std}";	\
 	echo "$${col}$$br$${std}"; 					\
 ## This is expected to go to the console, so it might have to be colorized.
 	create_testsuite_report --maybe-color;				\
diff --git a/t/ax/testsuite-summary-checks.sh b/t/ax/testsuite-summary-checks.sh
index 30dba7560..0b5967a48 100644
--- a/t/ax/testsuite-summary-checks.sh
+++ b/t/ax/testsuite-summary-checks.sh
@@ -15,7 +15,7 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 # Check the testsuite summary with the parallel test harness.  This
-# script is meant to be sourced by other test script, so that it can
+# script is meant to be sourced by other test scripts, so that it can
 # be used to check different scenarios (colorized and non-colorized
 # testsuite output, packages with and without bug-report addresses,
 # testsuites in subdirectories, ...)
diff --git a/t/list-of-tests.mk b/t/list-of-tests.mk
index 43ea245a9..16083137d 100644
--- a/t/list-of-tests.mk
+++ b/t/list-of-tests.mk
@@ -817,6 +817,7 @@ t/tests-environment-backcompat.sh \
 t/testsuite-summary-color.sh \
 t/testsuite-summary-count.sh \
 t/testsuite-summary-count-many.sh \
+t/testsuite-summary-header.sh \
 t/testsuite-summary-reference-log.sh \
 t/test-driver-acsubst.sh \
 t/test-driver-cond.sh \
diff --git a/t/testsuite-summary-header.sh b/t/testsuite-summary-header.sh
new file mode 100644
index 000000000..f1940860d
--- /dev/null
+++ b/t/testsuite-summary-header.sh
@@ -0,0 +1,91 @@
+#! /bin/sh
+# Copyright (C) 2011-2020 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+# Check that we can override the "Testsuite summary" header line,
+# per bug#11745.
+
+. test-lib.sh
+
+use_colors=no; use_vpath=no
+. testsuite-summary-checks.sh
+
+./configure
+
+# Cut down from do_check in ax/testsuite-summary-checks.sh
+# so that we can pass a make variable setting in $1.
+#
+do_header_check ()
+{
+  cat > summary.exp
+  run_make -O -e IGNORE check "$1"
+  test $am_make_rc -eq 0 || exit 1
+  $PERL "$am_testaux_srcdir"/extract-testsuite-summary.pl stdout >summary.got \
+   || fatal_ "cannot extract testsuite summary"
+  cat summary.exp
+  cat summary.got
+  compare=diff
+  $compare summary.exp summary.got || exit 1
+}
+
+# We don't actually run any tests, only interested in the header line.
+results="\
+# TOTAL: 0
+# PASS:  0
+# SKIP:  0
+# XFAIL: 0
+# FAIL:  0
+# XPASS: 0
+# ERROR: 0"
+#
+success_footer=${br}
+
+# Check the default.
+header="\
+${br}
+Testsuite summary for GNU AutoFoo 7.1
+${br}"
+#
+do_header_check 'junkvar=junkval' <<END
+$header
+$results
+$success_footer
+END
+
+# Elide the "for $(PACKAGE_STRING)".
+header_min="\
+${br}
+Testsuite summary
+${br}"
+#
+do_header_check 'AM_TESTSUITE_SUMMARY_HEADER=""' <<END
+$header_min
+$results
+$success_footer
+END
+
+# Add a suffix.
+header_more="\
+${br}
+Testsuite summary for GNU AutoFoo 7.1 (hi)
+${br}"
+#
+do_header_check 'AM_TESTSUITE_SUMMARY_HEADER=" for $(PACKAGE_STRING) (hi)"' <<END
+$header_more
+$results
+$success_footer
+END
+
+: