1DNS test harness (Deckard) 2========================== 3 4Deckard is a DNS software testing tool that creates a controlled network environment for reproducible tests. 5 6In essence, it works like this: 7 8- Deckard runs given binaries as subprocesses in an isolated network environment. 9- When binaries are up, Deckard sends scripted queries and checks replies. 10- When a binary attempts to contact another server, Deckard intercepts the communication and replies with scripted answer. 11- Deckard can simulate network issues, DNS environment changes, and fake time (for DNSSEC validation tests). 12 13No changes to real network setup are required because all network communications are made in a network namespace. 14 15Test cases are described by `scenarios <doc/scenario_guide.rst>`_ that contain: 16 17- A declarative description of the environment (e.g. what queries can the binary under test make and what Deckard should answer) 18- A sequence of queries (and expected answers), and other events (e.g. time jumps forward) 19 20 21Requirements 22------------ 23 24Deckard requires following software to be installed: 25 26- Python >= 3.6 27- Linux kernel >= 3.8 28- augeas_ - library for editing configuration files 29- dnspython_ - DNS library for Python 30- Jinja2_ - template engine for generating config files 31- PyYAML_ - YAML parser for Python 32- python-augeas_ - Python bindings for augeas API 33- pytest_ - testing framework for Python, used for running the test cases 34- pytest-xdist_ - module for pytest for distributed testing 35- pyroute2_ - Python netlink library (managing IP addresses, routes,…) 36- dumpcap_ - command line tool for network capture (part of Wireshark) 37- faketime_ - used for faking the time in tests of DNSSEC 38 39Compatibility 40------------- 41 42Deckard uses user and network namespaces to simulate the network environment 43so only Linux (with kernel version 3.8 or newer) is supported. It however is possible 44to run Deckard on other platforms in Docker. Just note that your container has to run as 45`--priviledged` for the namespaces to run properly. 46 47Usage 48----- 49 50- `User guide <doc/user_guide.rst>`_ describes how to run tests on a binary. 51- `Scenario guide <doc/scenario_guide.rst>`_ describes how to write a new test. 52- `Devel guide <doc/devel_guide.rst>`_ contains some tips for Deckard developers. 53 54 55License 56------- 57 58See `LICENSE <LICENSE>`_ file. 59 60 61Acknowledgments 62--------------- 63 64The 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. 65 66The original test case format is described in the `header file replay.h <http://unbound.net/documentation/doxygen/replay_8h.html#a6f204646f02cc4debbaf8a9b3fdb59a7>`_ distributed with `Unbound`_. 67 68 69Contacting us 70------------- 71 72Please report problems to our GitLab: https://gitlab.labs.nic.cz/knot/deckard/issues 73 74If 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. 75 76Happy testing. 77 78 79.. _`augeas`: http://augeas.net/ 80.. _`CSR`: http://apple.stackexchange.com/questions/193368/what-is-the-rootless-feature-in-el-capitan-really 81.. _`Jinja2`: http://jinja.pocoo.org/ 82.. _`Knot DNS Resolver`: https://gitlab.labs.nic.cz/knot/resolver/blob/master/README.md 83.. _`NLnet Labs`: https://www.nlnetlabs.nl/ 84.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/ 85.. _`PyYAML`: http://pyyaml.org/ 86.. _`Unbound`: https://www.unbound.net/ 87.. _`dnspython`: http://www.dnspython.org/ 88.. _`libfaketime`: https://github.com/wolfcw/libfaketime 89.. _`python-augeas`: https://pypi.org/project/python-augeas/ 90.. _`pytest`: https://pytest.org/ 91.. _`pytest-xdist`: https://pypi.python.org/pypi/pytest-xdist 92.. _`pyroute2`: https://pyroute2.org/ 93.. _`dumpcap`: https://www.wireshark.org/docs/man-pages/dumpcap.html 94