diff options
Diffstat (limited to '')
| -rw-r--r-- | tests/deckard/README.rst | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/tests/deckard/README.rst b/tests/deckard/README.rst new file mode 100644 index 0000000..c24156a --- /dev/null +++ b/tests/deckard/README.rst @@ -0,0 +1,98 @@ +DNS test harness (Deckard) +========================== + +Deckard is a DNS software testing tool that creates a controlled network environment for reproducible tests. + +In essence, it works like this: + +- Deckard runs given binaries as subprocesses in an isolated network environment. +- When binaries are up, Deckard sends scripted queries and checks replies. +- When a binary attempts to contact another server, Deckard intercepts the communication and replies with scripted answer. +- Deckard can simulate network issues, DNS environment changes, and fake time (for DNSSEC validation tests). + +No changes to real network setup are required because all network communications are redirected over UNIX sockets (and recorded to PCAP). + +Test cases are described by `scenarios <doc/scenario_guide.rst>`_ that contain: + +- A declarative description of the environment (e.g. what queries can the binary under test make and what Deckard should answer) +- A sequence of queries (and expected answers), and other events (e.g. time jumps forward) + + +Requirements +------------ + +Deckard requires following software to be installed: + +- Python >= 3.5 +- augeas_ - library for editing configuration files +- dnspython_ - DNS library for Python +- Jinja2_ - template engine for generating config files +- PyYAML_ - YAML parser for Python +- python-augeas_ - Python bindings for augeas API +- pytest_ - testing framework for Python, used for running the test cases +- pytest-xdist_ - module for pytest for distributed testing +- custom C libraries (installed automatically, see below) + +For convenient use it is strongly recommended to have a C compiler, Git, and ``make`` available. +First execution of ``make`` will automatically download and compile following libraries: + +- libfaketime_ - embedded because Deckard requires a rather recent version +- `modified socket_wrapper`_ - custom modification of `original socket_wrapper`_ library (part of the cwrap_ tool set for creating an isolated networks) + + +Compatibility +------------- + +Works well on Linux, Mac OS X [#]_ and probably all BSDs. Tested with `Knot DNS Resolver`_, `Unbound`_, and `PowerDNS Recursor`_. It should work with other software as well as long as all functions used by the binary under test are supported by our `modified socket_wrapper`_. + +.. [#] Python from Homebrew must be used, as the built-in Python is protected by the CSR_ from OS X 10.11 and prevents library injection. + + +Usage +----- + +- `User guide <doc/user_guide.rst>`_ describes how to run tests on a binary. +- `Scenario guide <doc/scenario_guide.rst>`_ describes how to write a new test. +- `Devel guide <doc/devel_guide.rst>`_ contains some tips for Deckard developers. + + +License +------- + +See `LICENSE <LICENSE>`_ file. + + +Acknowledgments +--------------- + +The test scenario design and a lot of tests were written by `NLnet Labs`_ for ``testbound`` suite used by `Unbound`_ (BSD licensed). We are grateful that ``testbound`` authors are `willing to discuss <https://unbound.nlnetlabs.nl/pipermail/unbound-users/2017-March/004699.html>`_ further Deckard development. + +The original test case format is described in the `header file replay.h <http://unbound.net/documentation/doxygen/replay_8h.html#a6f204646f02cc4debbaf8a9b3fdb59a7>`_ distributed with `Unbound`_. + + +Contacting us +------------- + +Please report problems to our GitLab: https://gitlab.labs.nic.cz/knot/deckard/issues + +If you have any comments feel free to send e-mail to knot-dns@labs.nic.cz! Do not get confused by the name, we are happy if you want to use Deckard with any software. + +Happy testing. + + +.. _`augeas`: http://augeas.net/ +.. _`CSR`: http://apple.stackexchange.com/questions/193368/what-is-the-rootless-feature-in-el-capitan-really +.. _`Jinja2`: http://jinja.pocoo.org/ +.. _`Knot DNS Resolver`: https://gitlab.labs.nic.cz/knot/resolver/blob/master/README.md +.. _`NLnet Labs`: https://www.nlnetlabs.nl/ +.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/ +.. _`PyYAML`: http://pyyaml.org/ +.. _`Unbound`: https://www.unbound.net/ +.. _`cwrap`: https://cwrap.org/ +.. _`dnspython`: http://www.dnspython.org/ +.. _`libfaketime`: https://github.com/wolfcw/libfaketime +.. _`modified socket_wrapper`: https://gitlab.labs.nic.cz/labs/socket_wrapper +.. _`original socket_wrapper`: https://cwrap.org/socket_wrapper.html +.. _`python-augeas`: https://pypi.org/project/python-augeas/ +.. _`pytest`: https://pytest.org/ +.. _`pytest-xdist`: https://pypi.python.org/pypi/pytest-xdist |