Zonema...erview(3pm)

📦
version 8.001.001 · 5 versions
, in ubuntu stonking

✨ Zonemaster::Engine::Overview — the Zonemaster Test Engine ✨

okay bestie, so this is Zonemaster::Engine::Overview, a section 3pm (User Contributed Perl Documentation) page, and it's literally the tour bus of the whole Zonemaster test engine. buckle up 💖

🌸 NAME 🌸

Zonemaster::Engine::Overview — The Zonemaster Test Engine. that's the whole name, she's simple, she's iconic, periodt.

🦋 INTRODUCTION 🦋

So. Zonemaster is a quality control tool for DNS zones, and it's the glow-up baby of a collab between AFNIC and IIS — those are the top-level registries for France and Sweden respectively, in case you were wondering who's holding the aux cord 🇫🇷🇸🇪. She's the successor to two earlier tools: AFNIC's Zonecheck and IIS's DNSCheck. And not to be shady, but the whole point is that Zonemaster is meant to be an upgrade over both of them. ate that, no crumbs.

The system as a whole is the test engine plus, as the project ships it, two different front ends:

  • one is a command-line interface — that one's for experienced technicians, iykyk
  • one is a web interface — that one's for literally anyone

and this doc? this doc is only about the test engine. just the engine. nothing else. don't @ me about the front ends 💅

👑 DESCRIPTION 👑

🌈 Brief overview

So conceptually the test engine is a bunch of test implementation modules vibing inside a support framework. If you wanna use Zonemaster to run tests, you talk to the framework from the "outside", and every module that implements tests sees the whole world entirely through the framework. nobody goes around the framework, that's the rule. 🚫

And the way we do things here is what unlocks the cute features: testing domains before they're even published, recording entire test runs so you can analyze them later, and making sure test results are (as far as reality lets us, bestie, we can't fight physics) predictable and repeatable. it's giving reliability. periodt.

🎀 For users of Zonemaster

If all you wanna do is run tests, you only need to care about four or five modules. that's it. that's the whole list.

  • Zonemaster::Engine is the main access point to the framework. it's through its methods that you set the configuration (if you even need to), ask for tests to be started, and get at the logger.
  • the logger is where the test results end up. so yeah, pretty important, lowkey the main character here.
  • on top of those, you might wanna bring in Zonemaster::Engine::Translator to turn results into human-readable messages. that's the translator's whole job ✨

Now, there are two ways to get the results of a test you requested: the simple-but-inflexible way, and the flexible-but-complex way. pick your fighter.

the simple-but-inflexible way 🍼 — every method in Zonemaster::Engine that runs tests returns lists of Zonemaster::Engine::Logger::Entry objects. those lists contain all the results the writer of the test module(s) thought were important enough to return by default. the upside? it's extremely easy to use. the following is a functional (if not very useful) way to run a full test and print the results from a command-line prompt:

perl -MZonemaster::Engine -E 'say "$_" for Zonemaster::Engine->new->test_zone("example.org")'

the main drawbacks of this method, bestie, are two:

  1. you get no choice about which messages you see.
  2. it's entirely synchronous. the code that started the test gets to do absolutely nothing until the whole test suite has finished — and that may be several minutes later. not me waiting around 😭

the flexible-but-complex way 💅 — this is how we dodge those drawbacks. it consists of installing a callback that gets executed every time a message is logged. code-wise it's genuinely not that much more complicated. this example does roughly the same thing as the one above:

perl -MZonemaster::Engine -E 'Zonemaster::Engine->logger->callback(sub {say "$_[0]"}); Zonemaster::Engine->new->test_zone("example.org");'

if you run both of those, you'll notice two main differences:

  1. the second variant prints results as they are generated.
  2. it generates a lot more output. on the author's machine at the time, the first example gave 94 lines of output. the second example gave 17684. yeah. 💀

You can do pretty much whatever you want with the message objects in the callback — including modifying them, though we don't promise that behavior will stick around, so don't get too attached 🙈.

⚠️ If the callback code throws an exception, and that exception is not a subclass of Zonemaster::Engine::Exception, the callback will be removed. gone. deleted.

Also note: while the callback is running, the test engine itself is not. so think twice before doing potentially time-consuming tasks in the callback — like sticking the message in a database, for example. and here's why: after waiting for responses from remote name servers (which usually stands for more than 90% of the time used), the result logging is the single most time-consuming task in a whole Zonemaster test run. so like, that callback is not free, bestie 🫶

From here, you probably wanna go read the documentation for:

  • Zonemaster::Engine
  • Zonemaster::Engine::Logger
  • Zonemaster::Engine::Logger::Entry
  • Zonemaster::Engine::Profile
  • Zonemaster::Engine::Translator

🧚 For developers of Zonemaster Test Modules

Okay so if you wanna develop a test module of your own: the standard set of modules serve as your examples. use them, learn them, love them 💜

As an entry point to the "inside" of the Zonemaster framework, you want to read Zonemaster::Engine::Zone and follow references from there. and of particular interest after the Zone class should be the Zonemaster::Engine::Nameserver class, and possibly the Zonemaster::Engine::Recursor class.

If you do write your own test module, the author would very much appreciate feedback on which parts were tricky to figure out — because honestly they're not sure what needs explaining here. so please, if there's something you think really needs to be written about, create an issue at:

https://github.com/zonemaster/zonemaster-engine/issues

(that's <https://github.com/zonemaster/zonemaster-engine/issues> if you like your links pointy-bracketed 🎀)

🍓 For developers of the Zonemaster Test Framework

Random recommendations and advice. May be replaced with more coherent developer documentation in the future. (lowkey a vibe check in bullet form, let's go)

  • Stability, predictability and reliability are more important than performance. say it louder for the people in the back 📣
  • Don't forget that starting with Perl version 5.18, the order in which you get the keys out of a hash will be different every time the script is run. get used to always writing sort keys %hash. always. every time. no cap.
  • If two (or more) test modules implement the same (or very similar) thing, it should probably be extracted into the framework. don't be copy-paste besties.
  • The unit tests run against pre-recorded data, unless the environment variable ZONEMASTER_RECORD is set to a (perl-)true value. in that case, it runs against the live DNS world and records all results for future use. Unfortunately this sometime means that some tests fail, when we were relying on seeing certain problems in certain domains, and those no longer look the same. DNS said plot twist 😭
  • The translation strings returned from a test module are used as keys in the GNU gettext system, so if you change anything in them don't forget to also change the translation .po files in share. fr fr, don't forget.
  • Adding a new message tag is more work than it first looks, since it needs to be added to the test module metadata, the default profile and the translation system in order to be fully functional. three places, bestie. three. 👑

more coming, stay tuned 💖

🦋 REFERENCES 🦋

okay bestie, the receipts section. everything the test specs cite lives here, so you can go straight to the source whenever you're like "wait, says who?" 💅

🌸 List of all RFCs referred to in the test specifications 🌸

here's the full roster 🫶 every single RFC the test specifications point at. it's a long list and honestly? iconic. scroll with love. ✨

aaaand that's the whole reading list, bestie 💖 you made it to the end, which is genuinely main character energy 👑 if you're ever fact-checking a test result at 2am, this is the page to come back to. iykyk.

this page came out of perl v5.40.1, dated 2026-03-21, and it's the Zonema...erview(3pm) page from the User Contributed Perl Documentation. periodt. 💅🦋

📦 where this page comes from