dhcp  4.3.6-P1
About: ISC DHCP implements the "Dynamic Host Configuration Protocols" for connection to a local network. 4.3.x release series.
  Fossies Dox: dhcp-4.3.6-P1.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  


Testing Overview

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 (will eventually) have:


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.

We are using ATF (Automated Test Framework) as a framework to run our unittests.

ATF unit-tests

ATF stands for Automated Test Framework, and is the framework used for unit tests in ISC DHCP and BIND9. ATF sources can be downloaded from https://github.com/jmmv/kyua . ATF itself must be configured, compiled and then installed to be available during the DHCP configure procedure.

There are three options for installing ATF. 1) Get the ATF sources and follow INSTALL file supplied with ATF sources (it's essentially the typical ./configure && make && make install procedure). 2) install Kyua with the ATF compatibility package, or 3) use the ATF version included in bind sources.

To configure and build the ATF from BIND you should set the "--with-atf" option to "bind".

./configure --with-atf=bind

Beginning with ATF version 0.16, it is necessary to include the following options –enable-tools and –disable-shared when configuring ATF:

    configure --prefix=<prefix> --enable-tools --disable-shared

ISC DHCP unittests will run with ATF releases upto 0.19. Beginning with ATF 0.20, the tools, atf-run and atf-report required by ISC DHCP, were deprecated and are no longer included with ATF.

The ATF successor, called Kyua, is being developed. As of August 2012, the latest available release of Kyua is 0.5. It claims to offer feature parity with ATF. Migration to Kyua may be planned some time in the future, but DHCP uses ATF for now. Such an upgrade should be done in coordination with BIND.

To build and run the unit-tests, use the following:

$ ./configure --with-atf
$ make
$ make check

This will traverse the source tree running the unit tests in each unit test subdirectory. Note that if one or more tests in a unit test subdirectory fail the make process will stop. To run all of the tests regardless of outcome, use "make -k check"

The following syntax is supported as well:

$ ./configure --with-atf=/path/to/your/atf/install

but it seems to have troubles sometimes detecting ATF installation, at least with ATF 0.14 and Mac OS X 10.6.8.

Each code directory (e.g. server/) that has unit-tests has a sub-directory named tests (e.g. server/tests). You can execute "make check" in that directory to run specific subset of tests.

Unit-tests are grouped into suites, each suite being a separate executable. The typical way to run tests is:

$ atf-run | atf-report
(This assumes atf-run and atf-report are in your path)
$ sh ../../tests/unittests.sh

atf-run will read the Atffile in the current directory and execute all the tests specified in it. Using atf-run - rather than calling the test binary directly - has several major benefits. The main one is that atf-run is able to recover from test segfault and continue execution from the next case onwards. Another is that it is possible to specify a timeout for a test. atf-run will kill the test in case of any infinite loops and will continue running next tests.

It is possible to run atf-run without passing its output to atf-report, but its output is somewhat convoluted. That is useful in some situations, e.g. when one wants to see test output.

It is possible to run test binary directly. The only required parameter is the test case name. The binary will print out a warning that direct binary execution is not recommended as it won't be able to recover from crash. However, such an approach is convenient for running the test under the debugger.

Adding new unit-tests

There are a small number of unit-tests that are not ATF based. They will be converted to ATF soon. Please do not use any other frameworks.

Sadly, the DHCP code was not written with unit-testing in mind: often a non-standard approach is required for writing unit-tests. The existing code often has many dependencies that make testing a single piece of code awkward to unit test. For example, to test hash tables, one needs to also include the OMAPI code. Rather than significantly refactoring the code (a huge task that could take months), we decided to link whatever is needed in the tests. If developing new test suite, it is recommended that you take a look at existing tests and just copy them as a starting point.

In particular, the following things should be done for adding new tests:

1. Tests directory. For each code component (server, client, common, etc.) there should be a tests subdirectory. If it isn't there yet, then it must be created. This can be done by:

a). Creating the directory:

    $ mkdir $subdir/tests
    $ cvs add tests

b). Adding the subdirectory to the build system:

Add to $subdir/Makefile.am:
    SUBDIRS = tests
Add to the AC_OUTPUT macro in configure.ac:

c. Create a Makefile.am in the new directory, something similar to 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:


2. Implement the test. That typically means that you create a new file that will hold test code. It is recommended you name it (tested_feature_name)_unittest.c and put the file in specified tests directory. For example tests related to hash tables used on the server side should be named server/tests/hash_unittest.c. If in doubt, it is convenient to name the test code after the file that holds tested code, e.g. server/mdb6.c is tested in server/tests/mdb6_unittest.c.

The file server/tests/simple_unittest.c holds a template explaining the basic layout of the ATF tests. There may be many test cases in a single *_unittest.c file. Make sure that you register all your test cases using ATF_TP_ADD_TC() macro, and try to minimize modifications to the tested code if possible. Keep in mind that we are using modernized Coding Guidelines for test development. You are advised to also look at atf-c-api(3) man page.

To add a new test, such as when a new module is added or when you want to start testing existing code, you can copy the server/tests/simple_unittest.c as a new new file, add the new file as a target in Makefile.am, and begin adding tests. Reviewing that file is a good idea, even if you decide to write your test from scratch, as it give you quick overview of the essential capabilities of the ATF framework (how to write test, how to make checks, pass or fail test etc.). Do not forget to add your new file to git via "git add yourtest_unittest.c".

3. Extend Makefile.am to build your test. In particular, add your binary name to ATF_TESTS. The tests directory will be built only in case where ATF is enabled, using –with-atf during configure phase.

4. Modify Atffile to include your new test, if needed. Tests in the specified directory must be registered in Atffile. See server/tests/Atffile for an example. Currently every executable with name of the form *_unittest will be executed automatically. If you followed naming convention proposed in a previous step, your test will be included and will be included automatically.

5. Enjoy your improved confidence in the code, as you can run the tests after any change you may want to do:

$ make check

to run all tests for all components. See atfTests section for more details on running tests.

ATF Coding Guidelines

As the unit-test code creates an evironment that works under a different regime than the production code, there are slight differences to standard coding guidelines. In particular:

  • The code is written using C99. Double slash comments are allowed.
  • Please do not use tabs. Use 4 spaces for each indent level.