path: root/camel/tests/README

This directory is to contain regression tests that should be run
before committing anything to camel.

In each subdirectory of tests there is a README containing a
one-line description of each test file.  This README must be kept
uptodate.

To write a new test: copy an existing one and replace the contents.

See camel-test.h for a number of functions and macros which setup and
define the test environmet, and help provide meaningful messages when
something actually fails.

All tests have the following options:
 -v[vvvv]
    verbose.  more v's more verbose.  2 v's will give you
    a simple test backtrace of any partially failed tests.
    No v's give you a simple backtrace of any failed tests.
 -q
    quiet.  Dont print anything, unless there is a SEGV.

See the other files in lib/* for utility functions that help to
write the tests (object comparison, creation, etc functions).

Tests may fail and be non-fatal.  In this case, you will see "Partial
success" on the result of each test line.  To get more information
about the test, run the test manually with a -v command line argument.
The more v's you have the more detail you get (upto about -vvvvv),
generally use -vv to find out which parts of a partially successful
test failed, and where.

Note that if writing tests, non-fatal tests (bracketed by a
camel_test_nonfatal() and camel_test_fatal() pair) should only be
defined where: 1. The test in question should ideally pass, and 2. The
code has known limitations currently that stop it passing, but
otherwise works for nominal input.

To debug tests, set a breakpoint on camel_test_fail, which will be
called for any failure, even a non-fatal one.  Or set it to
camel_test_break, which will only be called for fatal errors which are
to print to the screen.

 Michael <notzed@helixcode.com>