[hackers] [sbase][PATCH] Test framework created. See tests/README for details. Individual test cases can be run from tests dir using command line. Entire test suite can be run using: make && make tests

---
 .gitignore               |   2 +
 Makefile                 |  11 ++--
 tests/README             | 109 +++++++++++++++++++++++++++++++++++++++
 tests/echo-n.sh          |  10 ++++
 tests/echo-n.sh.expected |   1 +
 5 files changed, 130 insertions(+), 3 deletions(-)
 create mode 100644 tests/README
 create mode 100755 tests/echo-n.sh
 create mode 100644 tests/echo-n.sh.expected
diff --git a/.gitignore b/.gitignore
index 247ecd3..9efe314 100644
--- a/.gitignore
+++ b/.gitignore
_AT_@ -1,4 +1,6 @@
 *.o
+*.out
+*.tmp
 /build
 /getconf.h
 /libutf.a
diff --git a/Makefile b/Makefile
index 2d409ff..6655a51 100644
--- a/Makefile
+++ b/Makefile
_AT_@ -237,7 +237,7 @@ sbase-box-uninstall: sbase-box proto
 
 dist: clean
 	mkdir -p sbase
-	cp -R LICENSE Makefile README TODO config.mk *.c *.1 *.h libutf libutil sbase
+	cp -R LICENSE Makefile README TODO config.mk *.c *.1 *.h libutf libutil scripts tests sbase
 	mv sbase sbase-$(VERSION)
 	tar -cf sbase-$(VERSION).tar sbase-$(VERSION)
 	gzip sbase-$(VERSION).tar
_AT_@ -247,10 +247,15 @@ sbase-box: $(BIN)
 	scripts/mkbox
 	$(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) -o $_AT_ build/*.c $(LIB)
 
+tests:
+	cd tests; \
+	for t in *.sh; do \
+		echo "test: $$t"; sh "$$t" || echo "$$t FAIL ($$?)"; done
+
 clean:
 	rm -f $(BIN) $(OBJ) $(LIB) sbase-box sbase-$(VERSION).tar.gz
 	rm -f getconf.h
 	rm -f proto
-	rm -rf build
+	rm -rf build tests/*.out tests/*.tmp
 
-.PHONY: all install uninstall dist sbase-box-install sbase-box-uninstall clean
+.PHONY: all install uninstall dist sbase-box-install sbase-box-uninstall tests clean
diff --git a/tests/README b/tests/README
new file mode 100644
index 0000000..d21fc08
--- /dev/null
+++ b/tests/README
_AT_@ -0,0 +1,109 @@
+Test framework
+==============
+
+MIT License
+-----------
+
+© 2025 Xan Phung
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+Although MIT is the current licence, future consideration may be made for
+other licence types for individual tests in future, to allow use of
+test cases from other projects.
+
+Synopsis
+--------
+
+The full test suite within the 'tests' directory can be run by::
+
+    make && make tests
+
+Individual test cases however must be runnable directly from shell,
+after cd to the test directory, and not rely on make setup.
+
+Description
+-----------
+
+Test scripts are to be added to the 'tests' directory over time. It is
+proposed that each major new feature or revision to a tool come with
+(at least some) test script coverage of the feature.
+
+Each test script has the format '<tool>-<option_or_feature>.sh'. If a
+test script already exists for the feature, then append to or augment
+this script rather than creating a new script.
+
+Test scripts generate a (merged) stdout & stderr output file, named by
+appending '.out' to the script path, which is compared against an
+expected (.expected) output file.  Diagnostic messages may be printed
+to terminal, typically by the system (ie: search PATH) cmp command for
+test failure, but otherwise no terminal output is produced if test
+passes.
+
+Input files and temporary files
+-------------------------------
+
+If any input directories/files need to be supplied to test script,
+use the name '<tool>-<option_or_feature>.data' or use the TESTINP
+shell variable (see example below).
+
+If any temporary directories/files need to be created, use the name
+'<tool>-<option_or_feature>.tmp'. Temporary and output files can
+can be deleted by::
+
+    make clean
+
+Exit status
+-----------
+
+The following exit values shall be returned:
+
+0    Test passed
+1    Test ran but failed
+2    Test not runnable due to a miscellaneous error
+127  Test not runnable due to test executable not found
+
+Examples
+--------
+
+The `echo-n.sh` test is an example test script and is a template for
+creating other tests. Scripts must be POSIX shell executable, and set
+the following 3 shell variables::
+
+    #!/bin/sh
+    TESTEXE="${TESTEXE:-../echo}"
+    TESTARG="-n --hello-- --world--!"
+    TESTINP=""
+
+The above specifies the test executable (TESTEXE, in this case echo)
+and test arguments (TESTARG, in this case '-n' and the message text).
+Optionally, standard input stream data can be provided by TESTINP,
+(none in the case of echo). If TESTEXE has already been set, the test
+script will use the existing value, otherwise the default is the
+executable created by make (in parent of test directory).
+
+The echo tool is invoked by this line of the test script:
+
+	printf '%s' "$TESTINP" | "$TESTEXE" $TESTARG >"$0.out" 2>&1 || fail=1
+
+Other tests may vary the above invocation, depending on tool tested.
+Standard output and standard error from the echo tool will be sent to
+'echo-n.sh.out'. Expected output and expected errors are to be provided
+in 'echo-n.sh.expected'.
+
diff --git a/tests/echo-n.sh b/tests/echo-n.sh
new file mode 100755
index 0000000..e175188
--- /dev/null
+++ b/tests/echo-n.sh
_AT_@ -0,0 +1,10 @@
+#!/bin/sh
+TESTEXE="${TESTEXE:-../echo}"
+TESTARG="-n --hello-- --world--!"
+TESTINP=""
+
+command -v "$TESTEXE" >/dev/null || exit 127
+printf '%s' "$TESTINP" | "$TESTEXE" $TESTARG >"$0.out" 2>&1 || fail=1
+cmp "$0.expected" "$0.out" || fail=1
+exit $fail
+
diff --git a/tests/echo-n.sh.expected b/tests/echo-n.sh.expected
new file mode 100644
index 0000000..d49dbeb
--- /dev/null
+++ b/tests/echo-n.sh.expected
_AT_@ -0,0 +1 @@
+--hello-- --world--!
\ No newline at end of file
-- 
2.49.0