EVENT PRODUCTION METHODS

Which one do I use?

The "pass*" and "fail*" are optimal if they meet your situation, using one of them will always be the most optimal. That said they are optimal by eliminating many features.

Method such as "ok", and "note" are shortcuts for generating common 1-task events based on the old API, however they are forward compatible, and easy to use. If these meet your needs then go ahead and use them, but please check back often for alternatives that may be added.

If you want to generate new style events, events that do many things at once, then you want the "*ev2*" methods. These let you directly specify which facets you wish to use.

$event = $ctx->pass()

$event = $ctx->pass($name)

This will send and return an Test2::Event::Pass event. You may optionally provide a $name for the assertion.

The Test2::Event::Pass is a specially crafted and optimized event, using this will help the performance of passing tests.

$true = $ctx->pass_and_release()

$true = $ctx->pass_and_release($name)

This is a combination of "pass()" and "release()". You can use this if you do not plan to do anything with the context after sending the event. This helps write more clear and compact code.

    sub shorthand {
        my ($bool, $name) = @_;
        my $ctx = context();
        return $ctx->pass_and_release($name) if $bool;
        ... Handle a failure ...
    }
    sub longform {
        my ($bool, $name) = @_;
        my $ctx = context();
        if ($bool) {
            $ctx->pass($name);
            $ctx->release;
            return 1;
        }
        ... Handle a failure ...
    }
    

my $event = $ctx->fail()

my $event = $ctx->fail($name)

my $event = $ctx->fail($name, @diagnostics)

This lets you send an Test2::Event::Fail event. You may optionally provide a $name and @diagnostics messages.

Diagnostics messages can be simple strings, data structures, or instances of Test2::EventFacet::Info::Table (which are converted inline into the Test2::EventFacet::Info structure).

my $false = $ctx->fail_and_release()

my $false = $ctx->fail_and_release($name)

my $false = $ctx->fail_and_release($name, @diagnostics)

This is a combination of "fail()" and "release()". This can be used to write clearer and shorter code.

    sub shorthand {
        my ($bool, $name) = @_;
        my $ctx = context();
        return $ctx->fail_and_release($name) unless $bool;
        ... Handle a success ...
    }
    sub longform {
        my ($bool, $name) = @_;
        my $ctx = context();
        unless ($bool) {
            $ctx->pass($name);
            $ctx->release;
            return 1;
        }
        ... Handle a success ...
    }
    

$event = $ctx->ok($bool, $name)

$event = $ctx->ok($bool, $name, \@on_fail)

NOTE: Use of this method is discouraged in favor of "pass()" and "fail()" which produce Test2::Event::Pass and Test2::Event::Fail events. These newer event types are faster and less crufty.

This will create an Test2::Event::Ok object for you. If $bool is false then an Test2::Event::Diag event will be sent as well with details about the failure. If you do not want automatic diagnostics you should use the "send_event()" method directly.

The third argument "\@on_fail") is an optional set of diagnostics to be sent in the event of a test failure. Unlike with "fail()" these diagnostics must be plain strings, data structures are not supported.

$event = $ctx->note($message)

Send an Test2::Event::Note. This event prints a message to STDOUT.

$event = $ctx->diag($message)

Send an Test2::Event::Diag. This event prints a message to STDERR.

$event = $ctx->plan($max)

$event = $ctx->plan(0, 'SKIP', $reason)

This can be used to send an Test2::Event::Plan event. This event usually takes either a number of tests you expect to run. Optionally you can set the expected count to 0 and give the 'SKIP' directive with a reason to cause all tests to be skipped.

$event = $ctx->skip($name, $reason);

Send an Test2::Event::Skip event.

$event = $ctx->bail($reason)

This sends an Test2::Event::Bail event. This event will completely terminate all testing.

$event = $ctx->send_ev2(%facets)

This lets you build and send a V2 event directly from facets. The event is returned after it is sent.

This example sends a single assertion, a note (comment for stdout in Test::Builder talk) and sets the plan to 1.

    my $event = $ctx->send_event(
        plan   => {count => 1},
        assert => {pass  => 1, details => "A passing assert"},
        info => [{tag => 'NOTE', details => "This is a note"}],
    );
    

$event = $ctx->build_e2(%facets)

This is the same as "send_ev2()", except it builds and returns the event without sending it.

$event = $ctx->send_ev2_and_release($Type, %parameters)

This is a combination of "send_ev2()" and "release()".

    sub shorthand {
        my $ctx = context();
        return $ctx->send_ev2_and_release(assert => {pass => 1, details => 'foo'});
    }
    sub longform {
        my $ctx = context();
        my $event = $ctx->send_ev2(assert => {pass => 1, details => 'foo'});
        $ctx->release;
        return $event;
    }
    

$event = $ctx->send_event($Type, %parameters)

It is better to use send_ev2() in new code.

This lets you build and send an event of any type. The $Type argument should be the event package name with "Test2::Event::" left off, or a fully qualified package name prefixed with a '+'. The event is returned after it is sent.

    my $event = $ctx->send_event('Ok', ...);
    

or

    my $event = $ctx->send_event('+Test2::Event::Ok', ...);
    

$event = $ctx->build_event($Type, %parameters)

It is better to use build_ev2() in new code.

This is the same as "send_event()", except it builds and returns the event without sending it.

$event = $ctx->send_event_and_release($Type, %parameters)

It is better to use send_ev2_and_release() in new code.

This is a combination of "send_event()" and "release()".

    sub shorthand {
        my $ctx = context();
        return $ctx->send_event_and_release(Pass => { name => 'foo' });
    }
    sub longform {
        my $ctx = context();
        my $event = $ctx->send_event(Pass => { name => 'foo' });
        $ctx->release;
        return $event;
    }
    

INIT HOOKS

These are called whenever a context is initialized. That means when a new instance is created. These hooks are NOT called every time something requests a context, just when a new one is created.

GLOBAL

This is how you add a global init callback. Global callbacks happen for every context for any hub or stack.

    Test2::API::test2_add_callback_context_init(sub {
        my $ctx = shift;
        ...
    });

PER HUB

This is how you add an init callback for all contexts created for a given hub. These callbacks will not run for other hubs.

    $hub->add_context_init(sub {
        my $ctx = shift;
        ...
    });

PER CONTEXT

This is how you specify an init hook that will only run if your call to "context()" generates a new context. The callback will be ignored if "context()" is returning an existing context.

    my $ctx = context(on_init => sub {
        my $ctx = shift;
        ...
    });

RELEASE HOOKS

These are called whenever a context is released. That means when the last reference to the instance is about to be destroyed. These hooks are NOT called every time "$ctx->release" is called.

GLOBAL

This is how you add a global release callback. Global callbacks happen for every context for any hub or stack.

    Test2::API::test2_add_callback_context_release(sub {
        my $ctx = shift;
        ...
    });

PER HUB

This is how you add a release callback for all contexts created for a given hub. These callbacks will not run for other hubs.

    $hub->add_context_release(sub {
        my $ctx = shift;
        ...
    });

PER CONTEXT

This is how you add release callbacks directly to a context. The callback will ALWAYS be added to the context that gets returned, it does not matter if a new one is generated, or if an existing one is returned.

    my $ctx = context(on_release => sub {
        my $ctx = shift;
        ...
    });