Introduction
------------

Since nobody had any preferences, I went ahead and decided to use
CUnit as a framework for writing unit tests for initng. You can read
about the CUnit framework from the home page:

http://cunit.sourceforge.net/

I picked it because it seems pretty straightforward, and it turns out
that it is. :)


Running the Tests
-----------------

To run the tests:

1. ./configure && make 
   Run this from the main directory. This will compile the source
   files, which you need for the tests.

2. Install CUnit
   Basically also ./configure && make. If you don't want to install it
   system-wide, you can use the "--prefix" command and put it anywhere
   you want.

3. Compile
   Edit the CUNIT_DIR in the Makefile to point to whereever you
   installed CUnit. Run "make".

4. Execute
   ./test_initng

Don't worry about scary "FAIL" messages - these are tests for the 
memory allocation routines.

At the end you will see a "Run Summary". If all goes well, you will
see "0" in the "Failed" column. If there are any failures, they must
be fixed!


Adding Tests
------------

Adding a test is simple. Create a function like this:

void test_xxx(void)
{
      ...
    CU_ASSERT(condition1);
      ...
    CU_ASSERT(condition2);
      ...
}

The CU_ASSERT() is a macro that CUnit uses to declare conditions that
have to be maintained.

Once the function is written, add it to the tests to be run in the 
test file:

    CU_add_test(suite, "test description", test_xxx);


Each source module has a separate test file. The test file includes 
a couple of headers from CUnit, as well as "test_initng.h" and any
necessary header files, both from initng and standard libraries.

Each test file includes a setup routine, like this:

void test_foo_setup(void)
{
    CU_pSuite suite;

    suite = CU_add_suite("foo", empty_init, empty_cleanup);
    CU_add_test(suite, "desc test1", test_1);
    CU_add_test(suite, "desc test2", test_2);
       ...
    CU_add_test(suite, "desc testN", test_N);
}

If you want to add a file to test: 

1. Create the test file (like above).
2. Add the setup function from the test file to main() in test_initng.
3. Modify the Makefile to compile and include the file.

That's it!

- Shane, 2005-08-02
