Re: [PATCH] tests/init.sh: new file to be used via most *.sh tests

[Bruno Haible]

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  <address@hidden>

        * 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.