use Test2::API qw/context/;
sub my_ok {
my ($bool, $name) = @_;
my $ctx = context();
$ctx->ok($bool, $name);
$ctx->release; # You MUST do this!
return $bool;
}
Context objects make it easy to wrap other tools that also use context. Once you grab a context, any tool you call before releasing your context will inherit it:
sub wrapper {
my ($bool, $name) = @_;
my $ctx = context();
$ctx->diag("wrapping my_ok");
my $out = my_ok($bool, $name);
$ctx->release; # You MUST do this!
return $out;
}
There are a handful of cases where a tool author may want to create a new context by hand, which is why the "new" method exists. Unless you really know what you are doing you should avoid this.
If you are certain that you want a different tool to use the same context you may pass it a snapshot. "$ctx->snapshot" will give you a shallow clone of the context that is safe to pass around or store.
If you are certain that you want to save the context for later, you can use a snapshot. "$ctx->snapshot" will give you a shallow clone of the context that is safe to pass around or store.
"context()" has some mechanisms to protect you if you do cause a context to persist beyond the scope in which it was obtained. In practice you should not rely on these protections, and they are fairly noisy with warnings.
Note: If a context is acquired more than once an internal refcount is kept. "release()" decrements the ref count, none of the other actions of "release()" will occur unless the refcount hits 0. This means only the last call to "release()" will reset $?, $!, $@,and run the cleanup tasks.
This DOES NOT affect context on other hubs, only the hub used by the context will be affected.
my $ctx = ...;
$ctx->do_in_context(sub {
my $ctx = context(); # returns the $ctx the sub is called on
});
Note: The context will actually be cloned, the clone will be used instead of the original. This allows the thread id, process id, and error variables to be correct without modifying the original context.
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.
The Test2::Event::Pass is a specially crafted and optimized event, using this will help the performance of passing tests.
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 ...
}
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 ...
}
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.
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"}],
);
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;
}
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', ...);
This is the same as "send_event()", except it builds and returns the event without sending it.
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;
}
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;
...
});
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;
...
});
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/