Introduction
------------
In DHCP, a unit test exercises a particular piece of code in
isolation. There is a separate unit test per module or API. Each unit
test lives in a directory beneath the code it is designed to exercise.
So, we have:
client/tests/
common/tests/
dhcpctl/tests/
And so on.
Ideally each function would be invoked with every possible type of
input, and each branch of every function would be checked. In practice
we try to be a bit more pragmatic, and target the most basic
operations, as well tricky code, and areas we have seen bugs in the
past.
Running Unit Tests
------------------
In order to run the unit tests for DHCP, use:
$ make check
This will run all of the unit tests.
You can run a single test by going to the appropriate test directory
and invoking the test directly:
$ cd common/tests
$ make test_alloc
$ ./test_alloc
There are also a number of options that you can use when running a
test. To see these, use the "-u" flag on the program.
Adding a New Unit Test
----------------------
To add an additional test to an existing test program, you must create
a function for the new test in the C source file:
static void
mynewtest(void) {
static const char *test_desc = "describe the test";
t_assert("mynewtest", 1, T_REQUIRED, test_desc);
/* ... test code ... */
t_result(T_PASS);
}
Then add this function to the T_testlist[] array in the file:
testspec_t T_testlist[] = {
...
{ mynewtest, "some new test" },
{ NULL, NULL }
};
Then you should be able to compile and run your new test.
Adding a New Unit Test Program
------------------------------
To add a new program, such as when a new module is added, you can copy
the "unit_test_sample.c" file (in this directory) to a new name, add
the new file as a target in Makefile.am, and begin adding tests. Do
not forget to add it to CVS via "cvs add".
If there is no "tests" directory for a given subdirectory, then one
must be created. This can be done by:
1. Creating the directory:
$ mkdir $subdir/tests
$ cvs add tests
2. Adding the subdirectory to the build system:
Add to $subdir/Makefile.am:
SUBDIRS = tests
Add to the AC_OUTPUT macro in configure.ac:
$subdir/tests/Makefile
3. Create a Makefile.am in the new directory, something like this:
AM_CPPFLAGS = -I../..
check_PROGRAMS = test_foo
TESTS = test_foo
test_foo_SOURCES = test_foo.c
test_foo_LDADD = ../../tests/libt_api.a # plus others...
See existing Makefile.am for examples, and the Automake documentation:
http://www.gnu.org/software/automake/manual/html_node/Tests.html
Support Functions
-----------------
Here are a few of the most useful functions defined in t_api that you
can use in testing:
void
t_assert(const char *component, int anum, int class,
const char *what, ...);
The name of this function is slightly misleading. It
actually just prints out an error message in the test
output.
void
t_info(const char *format, ...);
Prints out a message in the test output. You should
include "\n" at the end.
void
t_result(int result);
Prints out the result in the test output. You should
use one of the constants for this:
T_PASS
T_FAIL
T_UNRESOLVED
T_UNSUPPORTED
T_UNTESTED
T_THREADONLY
Additional Testing
------------------
Other static or runtime testing is always an option. For instance, you
can use valgrind to check for memory leaks.
$Id: HOWTO-unit-test,v 1.1 2012/02/21 22:30:18 misho Exp $
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>