Hi Jim,
> I want to use something like this for each of the tests I own ...
> ...
> I'll post some examples of using this new framework later today.
One of the most important aspects of unit tests is that users are able to
1. execute a single test, rather than all tests,
2. single step through the test. Since we have no debugger for shell
scripts, this means the ability to copy&paste line by line.
This is still possible to do with your test framework, but not 100% obvious.
Therefore IMO it requires some documentation.
Here is a proposed patch. While at it, I also mentioned the trick with
VERBOSE=yes. Again, not immediate, because in other packages one uses
VERBOSE=1.
2009-11-25 Bruno Haible <br...@clisp.org>
* tests/init.sh: Add some developer and user documentation.
*** tests/init.sh.orig 2009-11-25 23:20:46.000000000 +0100
--- tests/init.sh 2009-11-25 23:20:43.000000000 +0100
***************
*** 15,20 ****
--- 15,58 ----
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+ # Using this file in a test
+ # =========================
+ #
+ # The typical skeleton of a test looks like this:
+ #
+ # #!/bin/sh
+ # : ${srcdir=.}
+ # . $srcdir/init.sh --set-path=.
+ # Execute some commands.
+ # Note that these commands are executed in a subdirectory, therefore you
+ # need to prepend "../" to relative filenames in the build dir.
+ # Set the exit code 0 for success, 77 for skipped, or 1 or other for
failure.
+ # Exit $?
+
+ # Executing a test that uses this file
+ # ====================================
+ #
+ # Running a single test:
+ # $ make check TESTS=test-foo.sh
+ #
+ # Running a single test, with verbose output:
+ # $ export VERBOSE=yes
+ # $ make check TESTS=test-foo.sh
+ #
+ # Running a single test, with single-stepping:
+ # 1. Go into a sub-shell:
+ # $ bash
+ # 2. Set relevant environment variables from TESTS_ENVIRONMENT in the
+ # Makefile:
+ # $ export srcdir=../../tests # this is an example
+ # 3. Execute the commands from the test, copy&pasting them one by one:
+ # $ . "$srcdir/init.sh" --set-path=.
+ # ...
+ # 4. Finally
+ # $ exit
+
+
# We use a trap below for cleanup. This requires us to go through
# hoops to get the right exit status transported through the handler.
# So use `Exit STATUS' instead of `exit STATUS' inside of the tests.
