documentation about writing recursor regression tests

diff --git a/regression-tests.recursor/README.md b/regression-tests.recursor/README.md
new file mode 100644 (file)
index 0000000..91bbe1a
--- /dev/null
+++ b/regression-tests.recursor/README.md
@@ -0,0 +1,114 @@
+Some notes on running and extending the recursor tests
+
+SYSTEM CONFIG
+-------------
+
+The recursor regression suite requires a series of available IPs to bind to.
+
+Debian/Ubuntu example:
+
+    $ grep -w lo /etc/network/interfaces 
+    auto lo
+    iface lo inet loopback
+        up /sbin/ip addr add 10.0.3.0/24 dev lo
+
+The suite also requires `bind()` access to port 53. The example config
+relies on authbind for this:
+
+    $ ls -al /etc/authbind/byport/53
+    -rwxr-xr-x 1 root root 0 May 31  2012 /etc/authbind/byport/53
+
+Other dependencies: daemontools.
+
+SETTING UP
+----------
+
+Copy `vars.sample` to `vars`
+
+    $ cp vars.sample vars
+
+Edit `vars`.
+
+The /24 to bind the various daemons in:
+
+    PREFIX=10.0.3
+
+How to run the auth server (usually no need to change this):
+
+    AUTHRUN="exec authbind ../../../pdns/pdns_server --config-dir=. > logfile 2>&1"
+
+How to run the recursor (usually, again, no need to change this):
+
+    RECRUN="exec authbind ../../../pdns/pdns_recursor --config-dir=. --socket-dir=. --daemon=no --trace=yes --dont-query= --local-address=$PREFIX.9 --hint-file=hintfile --packetcache-ttl=0 --max-cache-ttl=15 --threads=1 > logfile 2>&1"
+
+
+RUNNING
+-------
+
+Write out the various configuration files, create the service dirs (this uses
+`vars`):
+
+    $ ./config.sh
+
+Start all daemons:
+
+    $ ./start.sh
+
+Check that they are all up:
+
+    $ svstat configs/*
+    configs/10.0.3.10: up (pid 1145) 13 seconds
+    configs/10.0.3.11: up (pid 1141) 13 seconds
+    configs/10.0.3.12: up (pid 1137) 13 seconds
+    ...
+    configs/10.0.3.8: up (pid 1138) 13 seconds
+    configs/recursor-service: up (pid 1140) 13 seconds
+    configs/run-auth: unable to chdir: not a directory
+
+(They all need to be up more than a few seconds, otherwise they might be
+crashing on startup. Check the per-service `logfile` if something is wrong).
+The `run- auth` error is normal.
+
+Run the tests:
+
+    $ ./runtests
+
+Various things might go wrong the first time you run the tests. Correct them
+and try again. If you think you have fixed everything and you still have some
+tests failing (most importantly the ghost-* tests), run `svc -t configs/*` and
+try again.
+
+Eventually:
+
+    12 out of 12 (100.00%) tests passed, 0 were skipped
+
+CLEANING UP 
+-----------
+
+Stop all daemons:
+
+    $ ./stop.sh
+
+Remove config dirs:
+
+    $ ./clean.sh
+
+ADDING TESTS
+------------
+
+The testing setup consists of one recursor (at .9), one auth for our fake root
+zone (at .8) and another bunch of auths for deeper zones (at .10 and up).
+
+`config.sh` creates all the daemon configs, zonefiles, and, where necessary,
+Lua prequery scripts to emulate behaviour that `pdns_server` cannot produce
+natively.
+
+Figure out whether your new test needs another zone, and edit config.sh accordingly.
+
+Create a new directory for your test. It should at least have `command` (don't forget
+chmod +x), `description`, and an `expected_result` file (often empty at this stage).
+
+When you have that set up, run `./runtests` again. Your test will fail; check the
+`real_result` file. If it looks alright, copy it to `expected_result`.
+
+Congratulations, you have just written a test!