Let us say we have written a new module histogram.[ch] in a (currently fictitious) statistics package. We now wish to add a test harness statistics/histogram_test.[ch] (actually we should write the test harness first according to Extreme Programming principles). The first thing is to copy another test program, say common/list_test.[ch]. Remove the test code and change the names of all the definitions and strings to correspond to the new test program, leaving the following template files. Firstly histogram_test.h should like like this:
/**
* File: $RCSfile: testing.tex,v $
* Module: Histogram test program
* Part of: Gandalf Library
*
* Revision: $Revision: 1.3 $
* Last edited: $Date: 2003/02/24 10:06:15 $
* Author: $Author: pm $
* Copyright: (c) 2002 YOUR INSTITUTION
*
* Notes: Tests the histogram functions
*/
/* This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#include <gandalf/TestFramework/cUnit.h>
#ifndef CUNIT_HISTOGRAM_TEST_H
#define CUNIT_HISTOGRAM_TEST_H
cUnit_test_suite * histogram_test_build_suite(void);
#endif
Make sure you keep the header and license sections. The histogram_test.c
file should be:
/**
* File: $RCSfile: testing.tex,v $
* Module: Histogram test program
* Part of: Gandalf Library
*
* Revision: $Revision: 1.3 $
* Last edited: $Date: 2003/02/24 10:06:15 $
* Author: $Author: pm $
* Copyright: (c) 2002 YOUR INSTITUTION
*
* Notes: Tests the histogram functions
*/
/* This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#include <stdlib.h>
#include <stdio.h>
#include <gandalf/TestFramework/cUnit.h>
#include <gandalf/statistics/histogram_test.h>
#include <gandalf/statistics/histogram.h>
static Gan_Bool setup_test(void)
{
printf("\nSetup for histogram_test completed.\n\n");
return GAN_TRUE;
}
static Gan_Bool teardown_test(void)
{
printf("\nTeardown for histogram_test completed.\n\n");
return GAN_TRUE;
}
/* Tests all the histogram functions */
static Gan_Bool run_test(void)
{
return GAN_TRUE;
}
#ifdef HISTOGRAM_TEST_MAIN
int main ( int argc, char *argv[] )
{
/* set default Gandalf error handler without trace handling */
gan_err_set_reporter ( gan_err_default_reporter );
gan_err_set_trace ( GAN_ERR_TRACE_OFF );
setup_test();
if ( run_test() )
printf ( "Tests ran successfully!\n" );
else
printf ( "At least one test failed\n" );
teardown_test();
gan_heap_report(NULL);
return 0;
}
#else
/* This function registers the unit tests to a cUnit_test_suite. */
cUnit_test_suite *histogram_test_build_suite(void)
{
cUnit_test_suite *sp;
/* Get a new test session */
sp = cUnit_new_test_suite("histogram_test suite");
cUnit_add_test(sp, "histogram_test", run_test);
/* register a setup and teardown on the test suite 'histogram_test' */
if (cUnit_register_setup(sp, setup_test) != GAN_TRUE)
printf("Error while setting up test suite histogram_test");
if (cUnit_register_teardown(sp, teardown_test) != GAN_TRUE)
printf("Error while tearing down test suite histogram_test");
return( sp );
}
#endif /* #ifdef HISTOGRAM_TEST_MAIN */
There are now three functions, setup_test(), teardown_test()
and run_test() for you to fill with your test code.
setup_test() should create any data structures to be used multiple
times by the tests. Then run_test() performs the tests, and
teardown_test() frees the memory allocated by setup_test().
You can leave setup_test() and teardown_test() blank if you
like, and allocate & free the memory in run_test().
It is up to you.
The next stage is to add a rule in the package Makefile.in program to make your test program. Add histogram-test as a target to the all: line in statistics/Makefile.in. Then add the following lines to statistics/Makefile.in:
histogram-test:
$(LIBTOOL) $(CC) -I$(TOPLEVEL)/.. $(CFLAGS) -DHISTOGRAM_TEST_MAIN histogram_test.c $(PATH_BUILDER_C) -o histogram_test $(LDFLAGS) $(LIB) $(LIBS)
Remember that there must be a tab character at the start of the
$(LIBTOOL) line. Note the predefined symbol HISTOGRAM_TEST_MAIN.
This is to make sure that the section of histogram_test.c with the
main() function is compiled in. The other section of the code is
for when the test functions are linked against the Gandalf test harness.
For now, rerun ./configure from the gandalf directory to
recreate statistics/Makefile with the new rules, and make the
test program with the commands:
cd statistics
make histogram-test
./histogram_test
(or make all). The tests should be designed so that if the data is
successfully allocated and all the tests pass, setup_test(),
run_test() and teardown_test() should all return GAN_TRUE.
There is a special macro cu_assert(), which operates like assert()
in the sense that it tests an expression and fails if zero is returned.
In the cu_assert() either GAN_TRUE (one, success) is returned
if the expression is non-zero, and GAN_FALSE (zero, failure) is returned
if the expression is zero. In the latter case an error message is also
printed, providing the line at which failure occurs. This provides a
convenient shorthand for testing the results of the tests.
The next stage is to incorporate the test into the main Gandalf test harness. To do this, first edit gandalf/TestFramework/Makefile.in and add the following:
HISTOGRAM_TEST_C = $(TOPLEVEL)/statistics/hisogram_test.c
to the list below the OBJS list.
histogram_test.o: $(HISTOGRAM_TEST_C)
$(LIBTOOL) $(CC) -I$(TOPLEVEL)/.. $(CFLAGS) -c $(HISTOGRAM_TEST_C)
(remember the tab character again before $(LIBTOOL)).
#include <gandalf/statistics/histogram_test.h>
among the other #include declarations. Find the line
which has #define maxAutoTests in it and add one to the number
you see there. You will also need to add a line
auto_tests[iIndex++] = "histogram_test";
in the list of similar lines below, and finally the lines
pSuite = cUnit_add_test_suite(auto_tests[iIndex++],
histogram_test_build_suite);
gan_list_insert_last(glstAutoSuiteList, pSuite);
at the corresponding place in the next set of similar lines.
You will need to run configure again to recreate the
TestFramework/Makefile file, and then typing
cd TestFramework
make
./cUnit -menu
should give you the extended menu of test programs with your new test
as one of the options.