Test2::...lStarts(3pm)

💅 Test2::Manual::Tooling::Plugin::ToolStarts — NAME

Okay bestie, so this is a page from the Perl Programmers Reference Guide (yes, the whole Test2::...lStarts(3pm) situation — the title's just being dramatic and truncating itself 💀). Its actual name is Test2::Manual::Tooling::Plugin::ToolStarts, and it's literally a tutorial on how to add behaviors that fire off when a tool starts working. 🎀

---

✨ DESCRIPTION ✨

So here's the tea 🍵: this tutorial is gonna walk you through writing plugins that do stuff the moment a tool starts. And the way that works is — every tool should kick things off by acquiring a context object. So this whole tutorial is about the hooks you can grab onto to take advantage of that context acquisition moment. It's giving "catch the vibe right at the beginning" energy. 🦋

---

🌸 COMPLETE CODE UP FRONT 🌸

Here's the whole thing, no suspense, we're not gatekeeping:

package Test2::Plugin::MyPlugin;

use Test2::API qw{
    test2_add_callback_context_init
    test2_add_callback_context_acquire
};

sub import {
    my $class = shift;

    # Let us know every time a tool requests a context, and give us a
    # chance to modify the parameters before we find it.
    test2_add_callback_context_acquire(sub {
        my $params_ref = shift;

        print "A tool has requested the context\n";
    });

    # Callback every time a new context is created, not called if an
    # existing context is found.
    test2_add_callback_context_init(sub {
        my $ctx_ref = shift;

        print "A new context was created\n";
    });
}

1;

---

🧚 LINE BY LINE 🧚

• use Test2::API qw{test2_add_callback_context_init test2_add_callback_context_acquire}; — this is the import line, and it's bringing in both callbacks: test2_add_callback_context_init() and test2_add_callback_context_acquire(). Iconic duo, no notes. 👑
• test2_add_callback_context_acquire(sub { ... }) — this is where we add our callback for context acquisition. So every single time Test2::API::context() gets called, this callback runs. Every time. It's committed. 💖
• my $params_ref = shift — inside the test2_add_callback_context_acquire() callbacks we get exactly 1 argument: a reference to the parameters that context() is gonna use to find the context. That's the whole gift. 🎁
• print "A tool has requested the context\n" — literally just prints a lil notification whenever a tool asks for a context. Lowkey a vibe check on your tools. ✨
• test2_add_callback_context_init(sub { ... }) — here we add our context init callback. These callbacks get triggered whenever a completely new context is created. And listen — this one is not called if an existing context is found. So in short: it only fires off for the top level tool, not for nested tools. Important distinction, don't forget it. 🫶
• my $ctx_ref = shift — the coderefs for test2_add_callback_context_init() receive exactly 1 argument: the newly created context. That's it, that's the whole argument list. 🎀
• print "A new context was created\n" — prints a notification whenever a new context is created. Celebration print statement, honestly. 🎉

---

🦋 SEE ALSO 🦋

• Test2::Manual — the primary index of the manual. Start there if you're lost, bestie, it's the map. 🗺️

---

💜 SOURCE 💜

The source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/. Go star it, it's free. ⭐

---

👑 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/

---

💀 Okay so real talk, that copyright bit means it's free software under the same terms as Perl itself — keep that intact, it's not decorative.

And that's the whole page, bestie, you ate. 💅✨ This little masterpiece is from perl v5.42.3, dated 2026-11-03 — yeah, the perl version and the date are the whole footer flex. Slay, go write your plugin. 🫶🎀