From 45329ccb8cd9fe1118ec7c4d3854cb584d52ddad Mon Sep 17 00:00:00 2001
From: emma <emma@tebibyte.media>
Date: Sun, 7 Jul 2024 19:19:38 -0600
Subject: [PATCH] tests/README: initial commit; tests/posix_env, tests/test.sh:
 updated to match README

---
 tests/README          | 60 +++++++++++++++++++++++++++++++++++++++++++
 tests/posix/posix_env |  2 ++
 tests/test.sh         |  6 +++--
 3 files changed, 66 insertions(+), 2 deletions(-)
 create mode 100644 tests/README

diff --git a/tests/README b/tests/README
new file mode 100644
index 0000000..ee370b8
--- /dev/null
+++ b/tests/README
@@ -0,0 +1,60 @@
+The testing suite contains two main trees (plus translations for strings used in
+the shell scripts): the Bonsai tree and the POSIX tree:
+
+.
+├── bonsai
+│   ├── test_env
+│   ├── dj.sh
+│   ├── false.sh
+│   ├── fop.sh
+│   ├── hru.sh
+│   ├── intcmp.sh
+│   ├── mm.sh
+│   ├── strcmp.sh
+│   └── true.sh
+├── locales
+│   ├── en_US.UTF-8
+│   └── tok
+├── posix
+│   ├── bin
+│   │   ├── cat
+│   │   ├── false
+│   │   └── true
+│   └── posix_env
+├── README
+└── test.sh
+
+The Bonsai tree tests the functionality of Harakit utilities for regressions and
+other issues relating to compliance to our standards of practice.
+
+The POSIX tree tests the use of Harakit utilities in place of the standard usage
+of POSIX utilities. These scripts test the ability of Harakit to comply to POSIX
+standards using its native utilities in shell scripts as a compatibility shim.
+Each shell script in the top directory should contain a set of tests for each
+POSIX utility and be named for that utility. The bin directory should contain
+a set of shim scripts which will be imported into the path as POSIX utilities.
+Each test will compare the behavior of the shim script to the real utility on
+the system.
+
+Currently, due to the limitations of POSIX shell quoting, a subset of argument
+parsing is supported: arguments containing characters from POSIX’s Portable
+Filename Character Set [0].
+
+The bonsai/test_env and posix/posix_env files contain prerequisite shared
+environments for each of the tests. These scripts both contain lines which set
+the shell to write all commands run in them (-x) and to fail if any command
+fails (-e). See set(1p) for more information.
+
+Both sets of tests also inherit the environment set by the test.sh script, which
+sets the $BIN environment variable to the bin directory at the root of the
+project for easy and idiomatic access to the built Harakit binaries. When
+calling the POSIX test scripts, test.sh also sets the variable $realutil to be
+the absolute path to the currently tested utility’s counterpart on the system.
+
+[0] <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282>
+
+--
+Copyright © 2024 Emma Tebibyte <emma@tebibyte.media>
+
+This work is licensed under CC BY-SA 4.0. To view a copy of this license, visit
+<http://creativecommons.org/licenses/by-sa/4.0/>.
diff --git a/tests/posix/posix_env b/tests/posix/posix_env
index 56c5701..b436601 100644
--- a/tests/posix/posix_env
+++ b/tests/posix/posix_env
@@ -1,3 +1,5 @@
 #!/bin/sh
 
+set -ex
+
 PATH="$PWD/bin:$PATH"
diff --git a/tests/test.sh b/tests/test.sh
index 61bb814..bc68c65 100755
--- a/tests/test.sh
+++ b/tests/test.sh
@@ -28,9 +28,11 @@ for script in tests/bonsai/*.sh; do
 	printf '\n'
 done
 
-for test in tests/posix/*.sh; do
+for test_util in tests/posix/*.sh; do
+	realutil="$(command -v "$(printf '%s\n' "$test" | sed 's/\.sh$//g')")"
+	export realutil
 	export PATH="$BIN:$PATH"
 	printf '%s: %s: %s\n' "$0" "$test" "$TEST_STR"
-	"$utility"
+	"$test_util"
 	printf '\n'
 done