TESTING: start testing document/script

TESTING

@@ -0,0 +1,74 @@
+#!/bin/sh
+
+### Overview
+#
+# Testing is conducted with this script, in the source tree root, using the
+# tests in tests/.
+#
+# Basically, tests follow the format:
+#
+# - tests/[utility].[number].test
+# 	Test #[number]. This is an executable file (typically a script).
+# - tests/[utility].[number].expected
+# 	This is the expected standard output of test #[number].
+#
+# This script runs the executable [utility].[number].test and the following
+# file is written during testing:
+#
+# - tests/[utility].[number].output
+# 	The actual standard output from test #[number].
+#
+# If the actual standard output from the test differs from the expected
+# standard output, the testing ends, showing the difference.
+
+set -e
+
+alias emit="printf '%s: %s\n' '$0' \"\$1\""
+
+export PATH="$PATH:./build/bin/"
+
+if strcmp '' "$1"; then
+	printf 'Usage: %s [utilities...]\n' "$0" >&2
+	exit 64 # sysexits.h(3) EX_USAGE
+fi
+
+### Details
+
+while ! strcmp '' "$1"; do # $1 refers to the given utility
+
+# Tests are called [utility].[number].test. Tests are numbered from 1 with no
+# leading zeroes in the numbers, so (for example) scrut(1)'s first three tests
+# are scrut.1.test, scrut.2.test, and scrut.3.test. Tests are run sequentially
+# in the numbered order.
+
+	i=1
+	while scrut -e "$1.$i.test"; do # $i refers to the test number
+		emit "$1.$i.test: Running test..."
+
+# A test is an executable file. This runs each test for given utilities
+# and writes the standard output from the test to [utility].[number].output,
+# then uses diff(1p) (with the "-u" option) to highlight differences between
+# the actual output and the expected output, which is located at
+# [utility].[number].expected. If there are no differences none are shown and
+# testing continues.
+
+		# $1.$i.test is the same as [utility].[number].test
+		./"$1.$i.test" \
+			| mm -o "$1.$i.output" -o - \
+			| diff -u - "$1.$i.expected" \
+				|| emit '$1.$i.test: Test passed.\n'
+				# "set -e" terminates on an unsuccessful exit
+
+# The ideal output of this script is no output at all and each
+# [utility].[number].output written matching its associated
+# [utility].[number].expected.
+
+		i=$(rpn 1 "$i" +)
+	done
+
+	shift
+done
+
+# --
+# This work © 2024 by DTB is licensed under CC BY-SA 4.0. To view a copy of
+# this license, visit <http://creativecommons.org/licenses/by-sa/4.0/>