regress/infra-unittests: rewrite documentation, adjust code a little

The documentation now starts with a high-level introduction instead of
listing only the details.

The name of the function test_file had to be changed since the old name
was not expressive enough. Same for the variable real_pkgsrcdir.

5 files changed, 144 insertions, 81 deletions

diff --git a/regress/infra-unittests/extract.sh b/regress/infra-unittests/extract.sh
index 36d3b6b09d6..ef6f2fde3d6 100644
--- a/regress/infra-unittests/extract.sh
+++ b/regress/infra-unittests/extract.sh
@@ -16,9 +16,6 @@ test_case_set_up() {
 	export LC_ALL
 }
 
-# XXX: This definition should be available everywhere.
-pkgsrcdir="`cd "$real_pkgsrcdir" && exec pwd`"
-
 if test_case_begin "exclude directory by basename"; then
 
 	# Demonstrates that excluding a directory name also excludes that
diff --git a/regress/infra-unittests/mocked-include.sh b/regress/infra-unittests/mocked-include.sh
index 7fa25296ce2..1475deb6ef9 100644
--- a/regress/infra-unittests/mocked-include.sh
+++ b/regress/infra-unittests/mocked-include.sh
@@ -16,7 +16,7 @@ all:
 	@echo 'the mocked definition wins'
 EOF
 
-	out=$(test_file "including.mk")
+	out=$(run_bmake "including.mk")
 
 	assert_that "$out" --equals "the mocked definition wins"
 
diff --git a/regress/infra-unittests/subst.sh b/regress/infra-unittests/subst.sh
index 5a01fc44934..30c6c060721 100644
--- a/regress/infra-unittests/subst.sh
+++ b/regress/infra-unittests/subst.sh
@@ -33,7 +33,7 @@ STEP_MSG=	echo "=>"
 DO_NADA=	: do-nada
 INFO_MSG=	echo "info:"
 WARNING_MSG=	echo "warning:"
-FAIL_MSG=	sh $PWD/$real_pkgsrcdir/mk/scripts/fail echo "fail:"
+FAIL_MSG=	sh $pkgsrcdir/mk/scripts/fail echo "fail:"
 
 WRKDIR=		$tmpdir
 WRKSRC=		$tmpdir
@@ -60,7 +60,7 @@ EOF
 	create_file_lines "subst-single.txt" \
 		"before"
 
-	test_file "subst-single.mk" > "$tmpdir/output"
+	run_bmake "subst-single.mk" > "$tmpdir/output"
 
 	assert_that "output" --file-contains-exactly "=> Substituting \"class\" in subst-single.txt"
 	assert_that "subst-single.txt" --file-contains-exactly "after"
@@ -89,7 +89,7 @@ EOF
 	create_file_lines "second"	"the second file"
 	create_file_lines "third"	"the third file"
 
-	output=$(test_file "testcase.mk")
+	output=$(run_bmake "testcase.mk")
 
 	assert_that "$output" --equals "=> Substituting \"class\" in first second third"
 	assert_that "first" --file-contains-exactly "the first example"
@@ -121,7 +121,7 @@ EOF
 	create_file_lines "pattern-second"	"the second file"
 	create_file_lines "pattern-third"	"the third file"
 
-	output=$(test_file "testcase.mk")
+	output=$(run_bmake "testcase.mk")
 
 	assert_that "$output" --equals "=> Substituting \"class\" in pattern-*"
 	assert_that "pattern-first" --file-contains-exactly "the first example"
@@ -157,7 +157,7 @@ EOF
 	create_file_lines "pattern-second"	"the second is already an example"
 	create_file_lines "pattern-third"	"the third file"
 
-	test_file "testcase.mk" > "$tmpdir/actual-output"
+	run_bmake "testcase.mk" > "$tmpdir/actual-output"
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in pattern-*' \
 		'info: [subst.mk:class] Nothing changed in ./pattern-second.'
@@ -188,7 +188,7 @@ EOF
 
 	create_file_lines "single"	"already an example"
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in single' \
@@ -218,7 +218,7 @@ EOF
 
 	create_file_lines "single"	"already an example"
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in single' \
@@ -251,7 +251,7 @@ SUBST_NOOP_OK.class=	no
 all: subst-class
 EOF
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in nonexistent' \
@@ -283,7 +283,7 @@ SUBST_NOOP_OK.class=	yes
 all: subst-class
 EOF
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in nonexistent' \
@@ -311,7 +311,7 @@ EOF
 
 	create_file_lines "exists"	"this file exists"
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in *exist* *not-found*' \
@@ -336,7 +336,7 @@ SUBST_SED.class=	-e 'sahara'
 .include "mk/subst.mk"
 EOF
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in does not exist' \
@@ -365,7 +365,7 @@ EOF
 	create_file_lines "second"	"second"
 	create_file_lines "third"	"third"
 
-	test_file "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
+	run_bmake "testcase.mk" > "$tmpdir/actual-output" && exitcode=0 || exitcode=$?
 
 	create_file_lines "expected-output" \
 		'=> Substituting "class" in first second third' \
@@ -410,7 +410,7 @@ prepare-subst-class:
 	\${RUN} \${ECHO} "from" > "\${WRKSRC}/third"
 EOF
 
-	test_file "testcase.mk" "subst-class" \
+	run_bmake "testcase.mk" "subst-class" \
 		1> "$tmpdir/actual-output" \
 		2> "$tmpdir/actual-stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -450,7 +450,7 @@ EOF
 	create_file_lines "--no-option"		"before"
 	create_file_lines ".hidden"		"before"
 
-	test_file "testcase.mk" "subst-class" \
+	run_bmake "testcase.mk" "subst-class" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -494,7 +494,7 @@ EOF
 	create_file_lines "*"	"before"
 	create_file_lines "[*]"	"before"
 
-	test_file "testcase.mk" "subst-class" \
+	run_bmake "testcase.mk" "subst-class" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -527,7 +527,7 @@ all:
 .include "mk/subst.mk"
 EOF
 
-	test_file "testcase.mk" "all" \
+	run_bmake "testcase.mk" "all" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -568,7 +568,7 @@ SUBST_SED.three=	-e 's,three,III,'
 .include "mk/subst.mk"
 EOF
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -604,7 +604,7 @@ SUBST_SHOW_DIFF.two=	yes
 EOF
 
 	LC_ALL=C \
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -644,7 +644,7 @@ SUBST_SHOW_DIFF=	yes
 .include "mk/subst.mk"
 EOF
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -695,7 +695,7 @@ if test_case_begin "SUBST_VARS"; then
 		"@PRINTABLE@" \
 		"@UNDEFINED@"
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -740,7 +740,7 @@ if test_case_begin "SUBST_VARS with surrounding whitespace"; then
 		"@TAB@" \
 		"@NEWLINE@"
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -776,7 +776,7 @@ if test_case_begin "SUBST_VARS with backslashes"; then
 		'.include "mk/subst.mk"'
 	create_file_lines "backslash.txt" "@BACKSLASHES@"
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -818,7 +818,7 @@ if test_case_begin "SUBST_VARS for variables with regex characters"; then
 		"@VAR.<>@" \
 		"@VAR.[]@"
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -865,7 +865,7 @@ if test_case_begin "pattern matches directory"; then
 	create_file_lines "subst-file" \
 		"@VAR@"
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
@@ -905,7 +905,7 @@ if test_case_begin "pattern matches only directory"; then
 	create_file_lines "subdir/subfile" \
 		"@VAR@"
 
-	test_file "testcase.mk" "pre-configure" \
+	run_bmake "testcase.mk" "pre-configure" \
 		1> "$tmpdir/stdout" \
 		2> "$tmpdir/stderr" \
 	&& exitcode=0 || exitcode=$?
diff --git a/regress/infra-unittests/test.subr b/regress/infra-unittests/test.subr
index 4c62c97b6cc..f2fa49a03ba 100644
--- a/regress/infra-unittests/test.subr
+++ b/regress/infra-unittests/test.subr
@@ -1,56 +1,118 @@
 #! /bin/sh
-# $NetBSD: test.subr,v 1.8 2020/03/27 21:41:33 rillig Exp $
+# $NetBSD: test.subr,v 1.9 2020/03/27 22:56:29 rillig Exp $
 set -eu
 
-# This file defines utilities for testing Makefile fragments in a mocked
-# environment. It is used primarily to test the pkgsrc infrastructure.
+# This file defines utilities for testing Makefile fragments and shell
+# programs from the pkgsrc infrastructure. While testing one part of the
+# infrastructure, other parts can be mocked away.
 #
-# It defines the following shell variables:
+# A test case is defined by the following functions:
 #
-#	cleanup
-#		If yes (the default), clean up the temporary directory
-#		after the test has run successfully.
+#	test_case_begin
+#	test_case_set_up
+#	test_case_tear_down
+#	test_case_end
 #
-# It defines the following shell functions:
+# These functions form the structure for a test. To define a test, use the
+# following pattern:
 #
-#	mock_cmd
-#		Returns the path to a newly created shell program whose
-#		behavior (output and exit status) is specified by pairs
-#		of --when-args/--then-output or --when-args/--then-exit.
-#		Example:
+# 	if test_case_begin "description of the test"; then
+#		...
+#		test_end
+#	fi
 #
-#		hello=$(mock_cmd mock-hello \
-#			--when-args "" --then-output "Hello, world!" \
-#			--when-args "-t" --then-output "hello, world" \
-#			--when-args "-?" --then-exit 1
-#		)
+# The functions test_case_set_up and test_case_tear_down can be defined in the
+# test file to provide a test fixture that is common to all test cases. These
+# functions are called by test_case_begin and test_case_end, respectively.
 #
-#	create_file $filename <<EOF ... EOF
-#		Creates a file in the temporary directory. The filename
-#		is relative to the temporary directory.
+# During a test case, the following variables are defined:
 #
-#	create_file_lines $filename $line1 $line2 ...
-#		Creates a file in the temporary directory containing the
-#		given lines.
+#	tmpdir		a directory for creating intermediate files
+#	pkgsrcdir	the real pkgsrc directory
+#	mocked_pkgsrcdir
+#			the directory where the mock files are installed,
+#			which override the Makefile fragments from the real
+#			pkgsrc infrastructure
 #
-#	create_pkgsrc_file $filename <<EOF ... EOF
-#		Creates a file in the temporary pkgsrc directory. This
-#		file will be included instead of the one in the real
-#		pkgsrc infrastructure. The filename is relative to the
-#		pkgsrc directory, such as mk/defaults/mk.conf.
 #
-#		This is typically used for creating an empty file for
-#		mk/bsd.prefs.mk or similar files that are included by the
-#		file that is currently under test.
+# Setting up a test
 #
-#	test_file $filename $bmake_args...
-#		Runs bmake with the correct environment so that it picks
-#		up the mocked infrastructure files first and then the ones
-#		from the real pkgsrc installation. The filename is
-#		relative to the temporary directory.
+# mock_cmd
+#	Returns the path to a newly created shell program whose behavior
+#	(output and exit status) is specified by pairs of
+#	--when-args/--then-output or --when-args/--then-exit.
+#
+#	Example:
+#
+#	hello=$(mock_cmd mock-hello \
+#		--when-args "" --then-output "Hello, world!" \
+#		--when-args "-t" --then-output "hello, world" \
+#		--when-args "-?" --then-exit 1
+#	)
+#
+# create_file $filename <<EOF ... EOF
+#	Creates a file in the temporary directory. The filename is relative
+#	to the temporary directory.
+#
+# create_file_lines $filename $line1 $line2 ...
+#	Creates a file in the temporary directory containing the given lines.
+#
+# create_pkgsrc_file $filename <<EOF ... EOF
+#	Creates a file in the temporary pkgsrc directory. If it is a Makefile
+#	fragment, it will be included instead of the one in the real pkgsrc
+#	infrastructure.
+#
+#	This is typically used for creating an empty file for mk/bsd.prefs.mk
+#	or similar files that are included by the file that is currently under
+#	test.
+#
+#	Example:
+#
+#	create_pkgsrc_file "mk/pkg-build-options.mk" <<EOF
+#	# nothing
+#	EOF
+#
+#
+# Running the code to be tested
+#
+# run_bmake $filename $bmake_args...
+#	Runs bmake with the correct environment so that it picks up the mocked
+#	infrastructure files first and then the ones from the real pkgsrc
+#	installation. The filename is relative to the temporary directory.
+#
+#
+# Checking the result
+#
+# assert_that $actual --equals $expected
+#	Complains loudly if the string $actual is not equal to $expected.
+#
+# assert_that $tmpfile --file-contains-exactly $content
+#	Complains loudly if the file in $tmpdir does not contain the $content,
+#	plus a trailing newline.
+#
+# assert_that $tmpfile1 --file-equals $tmpfile2
+#	Complains loudly if the two files in $tmpdir differ.
+#
+# assert_that $tmpfile --file-is-empty
+#	Complains loudly if the file in $tmpdir is not empty.
+#
+# assert_that $tmpfile --file-is-lines $lines...
+#	Complains loudly if the file in $tmpdir does not consist of exactly
+#	the given lines.
+#
+# assert_succeed
+#	Counts one succeeded assertion, for the verbose statistics.
+#
+# assert_fail $format $args...
+#	Marks the current test as failed but continues to execute it.
+#
+#
+# Misc
+#
+# cleanup
+#	If this variable is yes (the default), clean up the temporary
+#	directory after the test has run successfully.
 #
-#	assert_that $actual --equals $expected
-#		Complains loudly if $actual is not equal to $expected.
 
 : "${cleanup:=yes}"
 : "${make:=bmake}"
@@ -60,15 +122,17 @@ mocked_pkgsrcdir="$tmpdir/pkgsrc"
 rm -rf "$tmpdir"
 mkdir -p "$mocked_pkgsrcdir"
 
-real_pkgsrcdir=""
-for rel in .. ../.. ../../..; do
-	[ -f "$rel/mk/bsd.pkg.mk" ] || continue
-	real_pkgsrcdir="$rel"
+pkgsrcdir=""
+for relative_pkgsrcdir in . .. ../.. ../../..; do
+	if [ -f "$relative_pkgsrcdir/mk/bsd.pkg.mk" ]; then
+		pkgsrcdir="$PWD/$relative_pkgsrcdir"
+		break
+	fi
 done
-[ "$real_pkgsrcdir" ] || {
+if [ -z "$pkgsrcdir" ]; then
 	printf 'error: must be run from somewhere inside the pkgsrc directory\n' 1>&2
 	exit 1
-}
+fi
 
 verbose_printf() {
 	$if_verbose printf "$@"
@@ -128,7 +192,9 @@ mock_cmd() {
 	shift 1
 
 	{
-	printf '#! /bin/sh\n\n'
+	printf '#! /bin/sh\n'
+	printf '\n'
+
 	while [ $# -ge 4 ]; do
 		case $1,$3 in
 		(--when-args,--then-output)
@@ -151,7 +217,7 @@ EOF
 		esac
 	done
 	cat <<EOF
-printf 'error: %s: no mock behavior defined for arguments %s\n' "\$0" "\$*" 1>&2
+printf 'error: %s: no mock behavior defined for arguments "%s"\n' "\$0" "\$*" 1>&2
 exit 1
 EOF
 	} > "$tmpdir/$cmdname"
@@ -177,11 +243,11 @@ create_pkgsrc_file() {
 	cat > "$mocked_pkgsrcdir/$1"
 }
 
-test_file() {
+run_bmake() {
 	cat <<EOF > "$tmpdir/test.subr.main.mk"
-PKGSRCDIR=	$real_pkgsrcdir
+PKGSRCDIR=	$relative_pkgsrcdir
 .PATH:		$mocked_pkgsrcdir
-.PATH:		$real_pkgsrcdir
+.PATH:		$pkgsrcdir
 .include "$1"
 EOF
 	shift
diff --git a/regress/infra-unittests/tools-bison.sh b/regress/infra-unittests/tools-bison.sh
index 60393f5e6c1..8f492e16248 100644
--- a/regress/infra-unittests/tools-bison.sh
+++ b/regress/infra-unittests/tools-bison.sh
@@ -35,7 +35,7 @@ all:
 .include "mk/tools/bison.mk"
 EOF
 
-	out=$(test_file "multiple-reqd-entries.mk")
+	out=$(run_bmake "multiple-reqd-entries.mk")
 
 	assert_that "$out" --equals "yes"
 
@@ -63,7 +63,7 @@ all:
 .include "mk/tools/bison.mk"
 EOF
 
-	out=$(test_file "multiple-reqd-entries.mk")
+	out=$(run_bmake "multiple-reqd-entries.mk")
 
 	assert_that "$out" --equals "no"