- RULES AND RECOMMENDATIONS FOR TEST CODE
- TEST MODULE STRUCTURE
The Zonemaster system intends to provide a framework for implementing DNS tests. In order to do this, it exposes APIs to the test code for examining a DNS zone, to emit examination results and to access configuration information on how the tests should be performed.
- Only access the outside world via the framework APIs.
The framework is built to make test results traceable, repeatable and understandable. If the test code itself goes around the framework and accesses things on its own, all those attributes are lost. If the test you're writing needs something the framework doesn't provide, request that it be added to the framework.
- Make as few assumptions as possible.
When the entry method in a test module is called, it can rely on only a handful of things about the testing process so far:
The zone object it's given has a parent.
The zone object it's given has glue records.
The zone object it's given has nameservers.
- Favor code clarity over performance.
Strive to make the test code as easily understood as possible. Ideally, it should be possible for a person with only a basic understanding of Perl to read the code and verify that it correctly implements the corresponding test specification.
The Zonemaster framework will attempt to load and call all modules in the namespace
Zonemaster::Engine::Test. These modules must have three class methods defined. One to run all tests it provides, and two to expose metadata about the module. Apart from that (and the rules above) the module can be implemented as desired.
There is an example module included in the standard Zonemaster distribution, Zonemaster::Engine::Test::Example, that demonstrates what a test module should look like. Incidentally, it also serves to demonstrate how to use the policy to block a test module from being run.
This method should return a string representing the current version of the test module. The version information will be logged in a
SYSTEMmessage, but otherwise not used.
This method should return a reference to a hash. The keys of this hash should be the names of the individual test methods in the module, and the values for each key should be a reference to an array listing all the possible messages that test method can emit.
The framework expects to be able to run all tests in a module by calling a class method
all() with a Zonemaster::Engine::Zone object as the argument. The return value from this method is expected to be a list of Zonemaster::Engine::Logger::Entry objects describing the results of the tests run. The example test module has one possible implementation of this.
In the case where one test module wants to use a test in another, the top-level Zonemaster::Engine module has a method
test_method() to request that. This method will call the other test, if it is available and the current policy allows its execution. It's up to the caller to know what arguments the other test needs, and what it returns.