Test2::...irstTool(3)

💅 Test2::Manual::Tooling::FirstTool(3) 💅

okay bestie, this page is from the User Contributed Perl Documentation, and it's literally your tutorial for writing your very first Test2 tool by cloning the ok() tool. periodt. 🫶

---

✨ NAME ✨

Test2::Manual::Tooling::FirstTool — write your first tool with Test2. 💖

🎀 DESCRIPTION 🎀

This tutorial helps you write your very first tool by cloning the ok() tool. No cap. 🦋

🔥 COMPLETE CODE UP FRONT 🔥

Here's the whole thing up front so you can see the final vibe: ✨

package Test2::Tools::MyOk;
use strict;
use warnings;

use Test2::API qw/context/;

use base 'Exporter';
our @EXPORT = qw/ok/;

sub ok($;$@) {
    my ($bool, $name, @diag) = @_;

    my $ctx = context();

    return $ctx->pass_and_release($name) if $bool;
    return $ctx->fail_and_release($name, @diag);
}

1;

🌸 LINE BY LINE 🌸

sub ok($;$@) {

In this case we're emulating the ok() function exported by Test2::Tools::Basic. 💅

ok() and similar test tools use prototypes to enforce argument parsing. Your test tools do not necessarily need prototypes — like any perl function, you need to make the decision based on how it is used.

The prototype requires at least 1 argument, which will be forced into a scalar context. The second argument is optional, and is also forced to be scalar; it is the name of the test. Any remaining arguments are treated as diagnostics messages that will only be used if the test failed. 🎀

my ($bool, $name, @diag) = @_;

This line does not need much explanation — we're simply grabbing the args. 🙈

my $ctx = context();

This is a vital line in ALL tools. The context object is the primary API for test tools. You MUST get a context if you want to issue any events, such as making assertions. Further, the context is responsible for making sure failures are attributed to the correct file and line number. 👑

Note: A test function MUST always release the context when it is done. You cannot simply let it fall out of scope and be garbage collected. Test2 does a pretty good job of yelling at you if you make this mistake. 😭

Note: You MUST NOT ever store or pass around a real context object. If you wish to hold on to a context for any reason, you must use clone to make a copy: my $copy = $ctx->clone. The copy may be passed around or stored, but the original MUST be released when you are done with it. ⭐

return $ctx->pass_and_release($name) if $bool;

When $bool is true, this line uses the context object to issue a Test2::Event::Pass event. Along with issuing the event, this will also release the context object and return true. slay. ✅

This is short form for:

if($bool) {
    $ctx->pass($name);
    $ctx->release;
    return 1;
}

return $ctx->fail_and_release($name, @diag);

This line issues a Test2::Event::Fail event, releases the context object, and returns false. The fail event will include any diagnostics messages from the @diag array. 💀

This is short form for:

$ctx->fail($name, @diag);
$ctx->release;
return 0;

🦋 CONTEXT OBJECT DOCUMENTATION 🦋

Test2::API::Context is the place to read up on what methods the context provides. Go get that lore, bestie. 📚

🌈 SEE ALSO 🌈

• Test2::Manual — primary index of the manual.

💜 SOURCE 💜

The source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/. 🫶

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

⭐ AUTHORS ⭐

Chad Granum <exodist@cpan.org>

🎀 COPYRIGHT 🎀

Copyright Chad Granum <exodist@cpan.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/

---

and that's the whole page, bestie 💖 it's from perl v5.42.0, dated 2025-07-28, and it's Test2::...irstTool(3). stay iconic ✨