Return to HOWTO-unit-test CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / tests

Initial revision

    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.1 2012/02/21 22:30:18 misho Exp $