1 files changed, 89 insertions, 0 deletions
diff --git a/tests/HOWTO-unit-test b/tests/HOWTO-unit-test
new file mode 100644
index 0000000..e00b7d5
--- /dev/null
+++ b/tests/HOWTO-unit-test
@@ -0,0 +1,89 @@
+Introduction
+------------
+
+That is only a brief overview of tests in ISC DHCP. For more thorough
+description, see ISC DHCP Developer's Guide. You can generate it, by
+having Doxygen installed and doing:
+
+ cd doc
+ make devel
+
+and then opening doc/html/index.html
+
+Tests 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:
+
+    server/tests/
+    client/tests/
+    common/tests/
+    dhcpctl/tests/
+
+And so on.
+
+We are using ATF (Automated Test Framework) as a framework to run our
+unit tests. See ISC DHCP Developer's Guide for much more thorough
+description of unit-test and ATF framework in general.
+
+Installing ATF
+--------------
+ATF sources can be downloaded from https://github.com/jmmv/kyua. ATF
+must be configured, compiled and then installed to be available during
+the DHCP configure procedure. Please follow INSTALL file supplied with
+ATF sources (it's essentially the typical ./configure && make &&
+make install procedure).
+
+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.
+
+Running Unit Tests
+------------------
+
+In order to run the unit tests for DHCP, enable ATF support during configure:
+
+$ ./configure --with-atf{=<atf-path>}
+
+    where <atf-path> is the path into which ATF was installed.  This would
+    be same value used for --prefix when ATF was configured (default is
+    /usr/local).
+
+And then build ISC_DHCP with:
+
+$ make
+
+Finally build and run unit tests with:
+
+$ 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
+
+You can run a single test by going to the appropriate test directory
+and invoking the test directly:
+
+$ cd server/tests
+$ make check
+
+Adding a New Unit Test
+----------------------
+
+See ISC DHCP Developer's Guide.
+
+Adding a New Unit Test Program
+------------------------------
+
+See ISC DHCP Developer's Guide.