TEST::BUILDER::MODULE(3perl)

✨ NAME ✨

Test::Builder::Module — it's the base class for test modules, bestie 💅 (the manual page lives in the 3perl section, Perl Programmers Reference Guide energy 👑)

---

🎀 SYNOPSIS 🎀

# Emulates Test::Simple
package Your::Module;

my $CLASS = __PACKAGE__;

use parent 'Test::Builder::Module';
@EXPORT = qw(ok);

sub ok ($;$) {
    my $tb = $CLASS->builder;
    return $tb->ok(@_);
}

1;

---

🦋 DESCRIPTION 🦋

Okay so real talk: this is a superclass for all the modules built on top of Test::Builder. It hands you a little bundle of shared functionality plus a whole method for reaching the actual Test::Builder object underneath. Lowkey iconic.

🌸 Importing 🌸

Test::Builder::Module is a subclass of Exporter, which means — surprise — your module is also a subclass of Exporter. So @EXPORT, @EXPORT_OK, etc. ... they all act totally normally, no notes. ✨

And it also gives you a few methods that do the whole use Your::Module tests => 23 part for you, so you don't have to. Obsessed.

💖 import

Test::Builder::Module ships an import() method that basically does the same vibe as Test::More's: it sets the plan, and it controls the exporting of functions and variables. The whole point is that your module can set the plan independent of Test::More. Slay.

Every argument you pass to import() gets passed straight on to "Your::Module->builder->plan()" — with one single exception, and that exception is "import =>[qw(things to import)]".

use Your::Module import => [qw(this that)], tests => 23;

Translation: import the functions this() and that(), AND set the plan to be 23 tests. Two birds, one cute little line. 🐦

import() also sets the exported_to() attribute of your builder to be the caller of the import() function. iykyk.

Wanna add extra behaviors to your import() method? Override import_extra(). That's the move.

💜 import_extra

Your::Module->import_extra(\@import_args);

import_extra() gets called by import(). It's your opportunity to add behaviors to your module based on its import list. Super handy.

Any extra arguments that shouldn't be passed on to plan()? You strip those off yourself in this method. That's on you, bestie.

See Test::More for an example of its use. 👀

NOTE This mechanism is VERY ALPHA AND LIKELY TO CHANGE — it feels like a bit of an ugly hack in its current form. So like ... don't build your whole personality on it, fr fr. 💀

🧚 Builder 🧚

Test::Builder::Module also provides some methods for getting at the underlying Test::Builder object. Let's go.

⭐ builder

my $builder = Your::Class->builder;

This method returns the Test::Builder object associated with Your::Class. And get this — it is not a constructor, so you can call it as often as you like. No guilt, no commitment. 🫶

This is the preferred way to get the Test::Builder object. You should not get it via "Test::Builder->new" as was previously recommended. That's the old lore, we've moved on. 💅

Heads up: the object returned by builder() may change at runtime, so you should call builder() inside each function rather than store it in a global. Do not hoard it. 🙈

sub ok {
    my $builder = Your::Class->builder;

    return $builder->ok(@_);
}

---

👑 SEE ALSO 👑

• Test2::Manual::Tooling::TestBuilder — this one describes the improved options for writing testing modules provided by Test2. If you're building tooling, go read it, no cap. 🔥

---

And that's the whole page, babe 🌈 — brought to you by perl v5.44.0, dated 2026-10-17, straight out of the Test::...:Module(3perl) manual. Periodt. 💖