Zonemaster::Test(3pm)

💖 Zonemaster::Test 💖

okay bestie, so this is Zonemaster::Test, a module that goes and finds, loads, and executes all the test modules ✨ It's giving "manager of the whole test squad" and honestly? iconic.

---

🌸 SYNOPSIS 🌸

my @results = Zonemaster::Test->run_all_for($zone);
my @results = Zonemaster::Test->run_module('DNSSEC', $zone);

like, that's the whole vibe. two lines. slay. 💅

---

🎀 TEST MODULES 🎀

so a "test module" is literally just any module whose name starts with Zonemaster::Test::. that's the whole membership criteria, no audition needed 🫶

they're expected to provide at least four class methods, plus optionally a fifth one if they're feeling extra.

• all($zone) — gets a zone object as its only argument (just the one, bestie, don't overthink it) and is expected to return a list of Zonemaster::Logger::Entry objects. this is the entry point that run_all_for and run_module call, so like, it matters. main character method fr fr.
• version() — must return the version of the test module. that's it. that's the whole job. no cap. 🌈
• metadata() — must return a reference to a hash. the keys are the names of callable methods that implement tests, and the values are references to arrays holding the tags of the messages those test methods can generate. yes it's nested. yes you'll get used to it. 💜
• translation() — must return a reference to a hash where the keys are all the message tags the test module can produce, and the corresponding values are the english translations of those messages.

⚠️ heads up queen: those translation strings get used as keys to look up translations into other languages. so think twice before editing them. like, really think. editing them is a whole thing. 😭

• policy() — optional! a test module can implement this one if it wants. if it does, it should return a reference to a hash where the keys are all the message tags the module can produce, and the corresponding values are their recommended default log levels. (yes the original says "correspondning" and no i will not be fixing that, we respect the source 💀)

---

👑 CLASS METHODS 👑

• modules() — returns a list with the names of all available test modules, except Zonemaster::Test::Basic. why not Basic? because that one is a bit special, duh. it's the VIP with its own entrance. 🎀
• run_all_for($zone) — runs all the (default) tests in all the test modules it found, and returns a list of the log entry objects they returned.

the order the found test modules get executed in is not defined — it's a mystery, it's a vibe, nobody knows — except that Zonemaster::Test::Basic is always executed first. periodt.

🛑 and listen: if the Basic tests fail to indicate a very basic level of function for the zone (meaning: it must have a parent domain, and it must have at least one functional nameserver), then no further tests will be executed. that's it. doors closed. go home. 🙈

• run_module($module, $zone) — runs all the default tests in the named module, for the given zone. targeted. precise. focused. we love a specialist. ✨
• run_one($module, $method, @arguments) — runs one particular test method in one particular module. very "i just need this one thing" energy.

for this to work, the requested module has to be in the list of active loaded modules (aka not a module that's been disabled by the current policy), and the method has to be listed in the metadata the module exports. both boxes checked? then the method gets called with the arguments you provided. 💅

😬 but here's the thing: no attempt is made to check that the provided arguments make sense for the particular method being called. that responsibility is left entirely to the user. you are the adult here. you are on your own. good luck bestie 🫶

---

and that's the whole page!! this gem of a doc came from perl v5.32.0, dated 2021-01-06, and it lives under the name Zonemaster::Test(3pm) — go forth and run some tests, you absolute legend 💖✨🦋