Return to HOWTO-unit-test CVS log

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

Annotation of embedaddon/dhcp/tests/HOWTO-unit-test, revision 1.1

1.1     ! misho       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 $