Test2::...lStarts(3)

💖 NAME 💖

okay bestie, this page is Test2::Manual::Tooling::Plugin::ToolStarts — how to add behaviors that occur when a tool starts work. It lives in the User Contributed Perl Documentation manual, and the header truncates the title to Test2::...lStarts(3) like it's too iconic for the full width. 🫶

✨ DESCRIPTION ✨

This tutorial is gonna help you write plugins that have behavior when a tool starts. Every tool should start by acquiring a context object — that's the move. This tutorial shows you the hooks you can use to take advantage of that context acquisition. Lowkey essential if you're doing plugin tooling. 🦋

💻 COMPLETE CODE UP FRONT 💻

Here's the complete code up front, no 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 🧚

Let's read the receipts line by line, bestie. 💖

• Here's the import line, exactly:

use Test2::API qw{test2_add_callback_context_init
test2_add_callback_context_acquire};

This imports the test2_add_callback_context_init() and test2_add_callback_context_acquire() callbacks. Slay.

• test2_add_callback_context_acquire(sub { ... }) — this is where we add our callback for context acquisition. Every time Test2::API::context() is called the callback will be run. 🔥
• my $params_ref = shift — in the test2_add_callback_context_acquire() callbacks we get exactly 1 argument, a reference to the parameters that context() will use to find the context. Yes, exactly 1. No cap.
• print "A tool has requested the context\n" — print a notification whenever a tool asks for a context. 💬
• test2_add_callback_context_init(sub { ... }) — add our context init callback. These callbacks are triggered whenever a completely new context is created. This is not called if an existing context is found. In short this only fires off for the top level tool, not nested tools. Important. 🫶
• my $ctx_ref = shift — the coderefs for test2_add_callback_context_init() will receive exactly 1 argument, the newly created context. 🌸
• print "A new context was created\n" — print a notification whenever a new context is created. ✨

👀 SEE ALSO 👀

• Test2::Manual — primary index of the manual. Go read it, bestie. 💖

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

---

That's the whole page, bestie — Perl v5.42.0, dated 2025-07-28, footer still rocking Test2::...lStarts(3). Slay. 💅✨