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/test-more/.

MAINTAINERS#

AUTHORS#