tests/HOWTO-unit-test

   1 Introduction
   2 ------------
   3
   4 In DHCP, a unit test exercises a particular piece of code in
   5 isolation. There is a separate unit test per module or API. Each unit
   6 test lives in a directory beneath the code it is designed to exercise.
   7 So, we have:
   8
   9     client/tests/
  10     common/tests/
  11     dhcpctl/tests/
  12
  13 And so on.
  14
  15 Ideally each function would be invoked with every possible type of
  16 input, and each branch of every function would be checked. In practice
  17 we try to be a bit more pragmatic, and target the most basic
  18 operations, as well tricky code, and areas we have seen bugs in the
  19 past.
  20
  21
  22 Running Unit Tests
  23 ------------------
  24
  25 In order to run the unit tests for DHCP, use:
  26
  27 $ make check
  28
  29 This will run all of the unit tests.
  30
  31 You can run a single test by going to the appropriate test directory
  32 and invoking the test directly:
  33
  34 $ cd common/tests
  35 $ make test_alloc
  36 $ ./test_alloc
  37
  38 There are also a number of options that you can use when running a
  39 test. To see these, use the "-u" flag on the program.
  40
  41
  42 Adding a New Unit Test
  43 ----------------------
  44
  45 To add an additional test to an existing test program, you must create
  46 a function for the new test in the C source file:
  47
  48 static void
  49 mynewtest(void) {
  50         static const char *test_desc = "describe the test";
  51
  52         t_assert("mynewtest", 1, T_REQUIRED, test_desc);
  53
  54         /* ... test code ... */
  55
  56         t_result(T_PASS);
  57 }
  58
  59 Then add this function to the T_testlist[] array in the file:
  60
  61 testspec_t T_testlist[] = {
  62         ...
  63         {       mynewtest,      "some new test" },
  64         {       NULL,           NULL            }
  65 };
  66
  67 Then you should be able to compile and run your new test.
  68
  69
  70 Adding a New Unit Test Program
  71 ------------------------------
  72
  73 To add a new program, such as when a new module is added, you can copy
  74 the "unit_test_sample.c" file (in this directory) to a new name, add
  75 the new file as a target in Makefile.am, and begin adding tests. Do
  76 not forget to add it to CVS via "cvs add".
  77
  78 If there is no "tests" directory for a given subdirectory, then one
  79 must be created. This can be done by:
  80
  81 1. Creating the directory:
  82
  83     $ mkdir $subdir/tests
  84     $ cvs add tests
  85
  86 2. Adding the subdirectory to the build system:
  87
  88     Add to $subdir/Makefile.am:
  89
  90         SUBDIRS = tests
  91
  92     Add to the AC_OUTPUT macro in configure.ac:
  93
  94         $subdir/tests/Makefile
  95
  96 3. Create a Makefile.am in the new directory, something like this:
  97
  98     AM_CPPFLAGS = -I../..
  99
 100     check_PROGRAMS = test_foo
 101
 102     TESTS = test_foo
 103
 104     test_foo_SOURCES = test_foo.c
 105     test_foo_LDADD = ../../tests/libt_api.a     # plus others...
 106
 107
 108 See existing Makefile.am for examples, and the Automake documentation:
 109
 110     http://www.gnu.org/software/automake/manual/html_node/Tests.html
 111
 112
 113 Support Functions
 114 -----------------
 115
 116 Here are a few of the most useful functions defined in t_api that you
 117 can use in testing:
 118
 119         void
 120         t_assert(const char *component, int anum, int class,
 121                  const char *what, ...);
 122
 123                 The name of this function is slightly misleading. It
 124                 actually just prints out an error message in the test
 125                 output.
 126
 127         void
 128         t_info(const char *format, ...);
 129
 130                 Prints out a message in the test output. You should
 131                 include "\n" at the end.
 132
 133         void
 134         t_result(int result);
 135
 136                 Prints out the result in the test output. You should
 137                 use one of the constants for this:
 138
 139                         T_PASS
 140                         T_FAIL
 141                         T_UNRESOLVED
 142                         T_UNSUPPORTED
 143                         T_UNTESTED
 144                         T_THREADONLY
 145
 146 Additional Testing
 147 ------------------
 148
 149 Other static or runtime testing is always an option. For instance, you
 150 can use valgrind to check for memory leaks.
 151
 152
 153 $Id: HOWTO-unit-test,v 1.2 2007/11/16 11:04:12 shane Exp $