
Using the testsuite
===================

If you want to verify that our distribution has no obvious bugs please
run "make check".  It won't work if you haven't already compiled
dents.  Run "make check" from the "/test" directory to speed things
up.

The output should contain something like:

 PASS: test_link
 PASS: test_event
 PASS: test_arg_list
 PASS: test_addr_tools
 PASS: test_db_rb
 ==================
 All 5 tests passed
 ==================

The POSIX-standard for "testing frameworks" requires that the results
may only be "PASS", "FAIL" and some other keywords which automake
doesn't use.

(FYI: "XFAIL", "UNTESTED", "UNSUPPORTED", "UNRESOLVED")


We think it's easier for you to report bugs to our mailing-list if we
display a short description of the error:

 ...
 Got 173 callbacks but wanted only 172.
 FAIL: test_event
 ...

We will exit after the first error by default. If you want to
examine what happened try to run "./test_event --verbose".


Writing new tests
=================

If you want to write a new test start by choosing a name that makes it
obvious what will be checked. If you are testing functions in  a
single source module, (e.g. link.c) then simply prepend the 'test'
prefix to the front of it.  For more complex tests, a more descriptive 
name might be better.

Then you'll have to choose what kind of test you want to write:

 - simple test -

Your test will be called without any parameters and you have to return
0 if it passed and 1 if not. If you want you may print a short
explanation for one error you detected.

 - regression test -

Your test will be called with "--regress" as first parameter and you
still have to return 0 if it passed and 1 if not.  In addition your
complete output will be compared with the saved output from a previous
run. This implies that you are not allowed to print non-deterministic
massages. Be sure that the functions you call won't generate such
output. (Check what happens with/without -DDEBUG.)

Just copy one of the "*.regress" scripts to "<check>.regress" and run
"./<check>.regress update" to initialize it.

 - script for DejaGnu -

We don't use it yet, but if you want to build something complicated
that's probably the way to go. DejaGnu is a portable "test framework"
that is perfect for asserting results of interactive commands and
other things.


Current situation
=================

Right now we try to write "simple tests" if possible. We don't have to
worry about updating scripts and it's possible to display a diagnostic
message when an error is detected.

We still support the "--verbose" and "--regress" switches. This way
it's easier to enhance a test in the future.

./anything.regress
==================

(TODO: remove this section, as soon as it's used)

#!/bin/sh
if test "$1" = "update"; then
  sed -n "1,/^# CUT HERE$/ p" $0 > $0.new
  `echo $0 | sed 's/\(.*\)\.[^\.]*/\1/'` --determ >> $0.new
  ERRORLEVEL=$?
  if test "$ERRORLEVEL" -ne "0"; then
    rm $0.new
    echo "$0: Program has errors. Not updated." 1>&2
    exit "$ERRORLEVEL"
  fi
  chmod u+x $0.new
  mv $0.new $0
else # check consistency
  `echo $0 | sed 's/\(.*\)\.[^\.]*/\1/'` --determ 2>&1 > $0.out1
  ERRORLEVEL=$?
  if test "$ERRORLEVEL" -ne "0"; then
    rm $0.out1
    exit "$ERRORLEVEL"
  fi
  sed "1,/^# CUT HERE$/ d" $0 > $0.out2
  cmp -s $0.out1 $0.out2
  ERRORLEVEL=$?
  rm $0.out1 $0.out2
fi
exit "$ERRORLEVEL"
# CUT HERE
