=head1 INTRODUCTION

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.

=head1 RULES AND RECOMMENDATIONS FOR TEST CODE

=over

=item 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.

=item Make as few assumptions as possible.

When the entry method in a test module is called, it can only rely on a handful of things about the testing process so far:

=over

=item

The zone object it's given has a parent.

=item

The zone object it's given has glue records.

=item

The zone object it's given has nameservers.

=back

=item Favor code clarity over performance.

Strive to make the test code as easily understandable 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 Case specifications.

=back

=head1 TEST MODULE STRUCTURE

The Zonemaster framework will attempt to load and call all modules in the namespace C<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.

=head2 Metadata methods

=over

=item C<version()>

This method should return a string representing the current version of the test module. The version information will be logged in a C<SYSTEM>
message, but otherwise not used.

=item C<metadata()>

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 methods can emit.

=back

=head2 Test-running method(s)

The framework expects to be able to run all tests in a module by calling a class method L<all()|Zonemaster::Engine::Test/all()> with a
L<Zonemaster::Engine::Zone> object as the argument.
The return value from this method is expected to be a list of L<Zonemaster::Engine::Logger::Entry> objects describing the results of the tests run.

=cut
