Test2::Manual::Tooling::Plugin::ToolStarts(3)
                                           User Contributed Perl Documentation


NAME
       Test2::Manual::Tooling::Plugin::ToolStarts - How to add behaviors that
       occur when a tool starts work.

DESCRIPTION
       This tutorial will help you write plugins that have behavior when a
       tool starts. All tools should start by acquiring a context object. This
       tutorial shows you the hooks you can use to take advantage of the
       context acquisition.

COMPLETE CODE UP FRONT
           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 imports the test2_add_callback_context_init() and
           test2_add_callback_context_acquire() callbacks.

       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.

       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.

       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.

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

MAINTAINERS
       Chad Granum <exodist@cpan.org>

AUTHORS
       Chad Granum <exodist@cpan.org>

COPYRIGHT
       Copyright 2018 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/

perl v5.38.2                      2024-05-12
                                 Test2::Manual::Tooling::Plugin::ToolStarts(3)