| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Test2::API::Context 3perl" |
| 58 |
.TH Test2::API::Context 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Test2::API::Context \- Object to represent a testing context. |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
The context object is the primary interface for authors of testing tools |
| 68 |
written with Test2. The context object represents the context in |
| 69 |
which a test takes place (File and Line Number), and provides a quick way to |
| 70 |
generate events from that context. The context object also takes care of |
| 71 |
sending events to the correct Test2::Hub instance. |
| 72 |
.SH SYNOPSIS |
| 73 |
.IX Header "SYNOPSIS" |
| 74 |
In general you will not be creating contexts directly. To obtain a context you |
| 75 |
should always use \f(CWcontext()\fR which is exported by the Test2::API module. |
| 76 |
.PP |
| 77 |
.Vb 1 |
| 78 |
\& use Test2::API qw/context/; |
| 79 |
\& |
| 80 |
\& sub my_ok { |
| 81 |
\& my ($bool, $name) = @_; |
| 82 |
\& my $ctx = context(); |
| 83 |
\& |
| 84 |
\& if ($bool) { |
| 85 |
\& $ctx\->pass($name); |
| 86 |
\& } |
| 87 |
\& else { |
| 88 |
\& $ctx\->fail($name); |
| 89 |
\& } |
| 90 |
\& |
| 91 |
\& $ctx\->release; # You MUST do this! |
| 92 |
\& return $bool; |
| 93 |
\& } |
| 94 |
.Ve |
| 95 |
.PP |
| 96 |
Context objects make it easy to wrap other tools that also use context. Once |
| 97 |
you grab a context, any tool you call before releasing your context will |
| 98 |
inherit it: |
| 99 |
.PP |
| 100 |
.Vb 4 |
| 101 |
\& sub wrapper { |
| 102 |
\& my ($bool, $name) = @_; |
| 103 |
\& my $ctx = context(); |
| 104 |
\& $ctx\->diag("wrapping my_ok"); |
| 105 |
\& |
| 106 |
\& my $out = my_ok($bool, $name); |
| 107 |
\& $ctx\->release; # You MUST do this! |
| 108 |
\& return $out; |
| 109 |
\& } |
| 110 |
.Ve |
| 111 |
.SH "CRITICAL DETAILS" |
| 112 |
.IX Header "CRITICAL DETAILS" |
| 113 |
.IP "you MUST always use the \fBcontext()\fR sub from Test2::API" 4 |
| 114 |
.IX Item "you MUST always use the context() sub from Test2::API" |
| 115 |
Creating your own context via \f(CW\*(C`Test2::API::Context\->new()\*(C'\fR will almost never |
| 116 |
produce a desirable result. Use \f(CWcontext()\fR which is exported by Test2::API. |
| 117 |
.Sp |
| 118 |
There are a handful of cases where a tool author may want to create a new |
| 119 |
context by hand, which is why the \f(CW\*(C`new\*(C'\fR method exists. Unless you really know |
| 120 |
what you are doing you should avoid this. |
| 121 |
.IP "You MUST always release the context when done with it" 4 |
| 122 |
.IX Item "You MUST always release the context when done with it" |
| 123 |
Releasing the context tells the system you are done with it. This gives it a |
| 124 |
chance to run any necessary callbacks or cleanup tasks. If you forget to |
| 125 |
release the context it will try to detect the problem and warn you about it. |
| 126 |
.IP "You MUST NOT pass context objects around" 4 |
| 127 |
.IX Item "You MUST NOT pass context objects around" |
| 128 |
When you obtain a context object it is made specifically for your tool and any |
| 129 |
tools nested within. If you pass a context around you run the risk of polluting |
| 130 |
other tools with incorrect context information. |
| 131 |
.Sp |
| 132 |
If you are certain that you want a different tool to use the same context you |
| 133 |
may pass it a snapshot. \f(CW\*(C`$ctx\->snapshot\*(C'\fR will give you a shallow clone of |
| 134 |
the context that is safe to pass around or store. |
| 135 |
.IP "You MUST NOT store or cache a context for later" 4 |
| 136 |
.IX Item "You MUST NOT store or cache a context for later" |
| 137 |
As long as a context exists for a given hub, all tools that try to get a |
| 138 |
context will get the existing instance. If you try to store the context you |
| 139 |
will pollute other tools with incorrect context information. |
| 140 |
.Sp |
| 141 |
If you are certain that you want to save the context for later, you can use a |
| 142 |
snapshot. \f(CW\*(C`$ctx\->snapshot\*(C'\fR will give you a shallow clone of the context |
| 143 |
that is safe to pass around or store. |
| 144 |
.Sp |
| 145 |
\&\f(CWcontext()\fR has some mechanisms to protect you if you do cause a context to |
| 146 |
persist beyond the scope in which it was obtained. In practice you should not |
| 147 |
rely on these protections, and they are fairly noisy with warnings. |
| 148 |
.IP "You SHOULD obtain your context as soon as possible in a given tool" 4 |
| 149 |
.IX Item "You SHOULD obtain your context as soon as possible in a given tool" |
| 150 |
You never know what tools you call from within your own tool will need a |
| 151 |
context. Obtaining the context early ensures that nested tools can find the |
| 152 |
context you want them to find. |
| 153 |
.SH METHODS |
| 154 |
.IX Header "METHODS" |
| 155 |
.ie n .IP $ctx\->done_testing; 4 |
| 156 |
.el .IP \f(CW$ctx\fR\->done_testing; 4 |
| 157 |
.IX Item "$ctx->done_testing;" |
| 158 |
Note that testing is finished. If no plan has been set this will generate a |
| 159 |
Plan event. |
| 160 |
.ie n .IP "$clone = $ctx\->\fBsnapshot()\fR" 4 |
| 161 |
.el .IP "\f(CW$clone\fR = \f(CW$ctx\fR\->\fBsnapshot()\fR" 4 |
| 162 |
.IX Item "$clone = $ctx->snapshot()" |
| 163 |
This will return a shallow clone of the context. The shallow clone is safe to |
| 164 |
store for later. |
| 165 |
.ie n .IP $ctx\->\fBrelease()\fR 4 |
| 166 |
.el .IP \f(CW$ctx\fR\->\fBrelease()\fR 4 |
| 167 |
.IX Item "$ctx->release()" |
| 168 |
This will release the context. This runs cleanup tasks, and several important |
| 169 |
hooks. It will also restore \f(CW$!\fR, \f(CW$?\fR, and \f(CW$@\fR to what they were when the |
| 170 |
context was created. |
| 171 |
.Sp |
| 172 |
\&\fBNote:\fR If a context is acquired more than once an internal refcount is kept. |
| 173 |
\&\f(CWrelease()\fR decrements the ref count, none of the other actions of |
| 174 |
\&\f(CWrelease()\fR will occur unless the refcount hits 0. This means only the last |
| 175 |
call to \f(CWrelease()\fR will reset \f(CW$?\fR, \f(CW$!\fR, \f(CW$@\fR, and run the cleanup tasks. |
| 176 |
.ie n .IP $ctx\->throw($message) 4 |
| 177 |
.el .IP \f(CW$ctx\fR\->throw($message) 4 |
| 178 |
.IX Item "$ctx->throw($message)" |
| 179 |
This will throw an exception reporting to the file and line number of the |
| 180 |
context. This will also release the context for you. |
| 181 |
.ie n .IP $ctx\->alert($message) 4 |
| 182 |
.el .IP \f(CW$ctx\fR\->alert($message) 4 |
| 183 |
.IX Item "$ctx->alert($message)" |
| 184 |
This will issue a warning from the file and line number of the context. |
| 185 |
.ie n .IP "$stack = $ctx\->\fBstack()\fR" 4 |
| 186 |
.el .IP "\f(CW$stack\fR = \f(CW$ctx\fR\->\fBstack()\fR" 4 |
| 187 |
.IX Item "$stack = $ctx->stack()" |
| 188 |
This will return the Test2::API::Stack instance the context used to find |
| 189 |
the current hub. |
| 190 |
.ie n .IP "$hub = $ctx\->\fBhub()\fR" 4 |
| 191 |
.el .IP "\f(CW$hub\fR = \f(CW$ctx\fR\->\fBhub()\fR" 4 |
| 192 |
.IX Item "$hub = $ctx->hub()" |
| 193 |
This will return the Test2::Hub instance the context recognizes as the |
| 194 |
current one to which all events should be sent. |
| 195 |
.ie n .IP "$dbg = $ctx\->\fBtrace()\fR" 4 |
| 196 |
.el .IP "\f(CW$dbg\fR = \f(CW$ctx\fR\->\fBtrace()\fR" 4 |
| 197 |
.IX Item "$dbg = $ctx->trace()" |
| 198 |
This will return the Test2::EventFacet::Trace instance used by the context. |
| 199 |
.ie n .IP "$ctx\->do_in_context(\e&code, @args);" 4 |
| 200 |
.el .IP "\f(CW$ctx\fR\->do_in_context(\e&code, \f(CW@args\fR);" 4 |
| 201 |
.IX Item "$ctx->do_in_context(&code, @args);" |
| 202 |
Sometimes you have a context that is not current, and you want things to use it |
| 203 |
as the current one. In these cases you can call |
| 204 |
\&\f(CW\*(C`$ctx\->do_in_context(sub { ... })\*(C'\fR. The codeblock will be run, and |
| 205 |
anything inside of it that looks for a context will find the one on which the |
| 206 |
method was called. |
| 207 |
.Sp |
| 208 |
This \fBDOES NOT\fR affect context on other hubs, only the hub used by the context |
| 209 |
will be affected. |
| 210 |
.Sp |
| 211 |
.Vb 4 |
| 212 |
\& my $ctx = ...; |
| 213 |
\& $ctx\->do_in_context(sub { |
| 214 |
\& my $ctx = context(); # returns the $ctx the sub is called on |
| 215 |
\& }); |
| 216 |
.Ve |
| 217 |
.Sp |
| 218 |
\&\fBNote:\fR The context will actually be cloned, the clone will be used instead of |
| 219 |
the original. This allows the thread id, process id, and error variables to be correct without |
| 220 |
modifying the original context. |
| 221 |
.ie n .IP $ctx\->\fBrestore_error_vars()\fR 4 |
| 222 |
.el .IP \f(CW$ctx\fR\->\fBrestore_error_vars()\fR 4 |
| 223 |
.IX Item "$ctx->restore_error_vars()" |
| 224 |
This will set \f(CW$!\fR, \f(CW$?\fR, and \f(CW$@\fR to what they were when the context was |
| 225 |
created. There is no localization or anything done here, calling this method |
| 226 |
will actually set these vars. |
| 227 |
.ie n .IP "$! = $ctx\->\fBerrno()\fR" 4 |
| 228 |
.el .IP "$! = \f(CW$ctx\fR\->\fBerrno()\fR" 4 |
| 229 |
.IX Item "$! = $ctx->errno()" |
| 230 |
The (numeric) value of \f(CW$!\fR when the context was created. |
| 231 |
.ie n .IP "$? = $ctx\->\fBchild_error()\fR" 4 |
| 232 |
.el .IP "$? = \f(CW$ctx\fR\->\fBchild_error()\fR" 4 |
| 233 |
.IX Item "$? = $ctx->child_error()" |
| 234 |
The value of \f(CW$?\fR when the context was created. |
| 235 |
.ie n .IP "$@ = $ctx\->\fBeval_error()\fR" 4 |
| 236 |
.el .IP "$@ = \f(CW$ctx\fR\->\fBeval_error()\fR" 4 |
| 237 |
.IX Item "$@ = $ctx->eval_error()" |
| 238 |
The value of \f(CW$@\fR when the context was created. |
| 239 |
.SS "EVENT PRODUCTION METHODS" |
| 240 |
.IX Subsection "EVENT PRODUCTION METHODS" |
| 241 |
\&\fBWhich one do I use?\fR |
| 242 |
.PP |
| 243 |
The \f(CW\*(C`pass*\*(C'\fR and \f(CW\*(C`fail*\*(C'\fR are optimal if they meet your situation, using one of |
| 244 |
them will always be the most optimal. That said they are optimal by eliminating |
| 245 |
many features. |
| 246 |
.PP |
| 247 |
Method such as \f(CW\*(C`ok\*(C'\fR, and \f(CW\*(C`note\*(C'\fR are shortcuts for generating common 1\-task |
| 248 |
events based on the old API, however they are forward compatible, and easy to |
| 249 |
use. If these meet your needs then go ahead and use them, but please check back |
| 250 |
often for alternatives that may be added. |
| 251 |
.PP |
| 252 |
If you want to generate new style events, events that do many things at once, |
| 253 |
then you want the \f(CW\*(C`*ev2*\*(C'\fR methods. These let you directly specify which facets |
| 254 |
you wish to use. |
| 255 |
.ie n .IP "$event = $ctx\->\fBpass()\fR" 4 |
| 256 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->\fBpass()\fR" 4 |
| 257 |
.IX Item "$event = $ctx->pass()" |
| 258 |
.PD 0 |
| 259 |
.ie n .IP "$event = $ctx\->pass($name)" 4 |
| 260 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->pass($name)" 4 |
| 261 |
.IX Item "$event = $ctx->pass($name)" |
| 262 |
.PD |
| 263 |
This will send and return an Test2::Event::Pass event. You may optionally |
| 264 |
provide a \f(CW$name\fR for the assertion. |
| 265 |
.Sp |
| 266 |
The Test2::Event::Pass is a specially crafted and optimized event, using |
| 267 |
this will help the performance of passing tests. |
| 268 |
.ie n .IP "$true = $ctx\->\fBpass_and_release()\fR" 4 |
| 269 |
.el .IP "\f(CW$true\fR = \f(CW$ctx\fR\->\fBpass_and_release()\fR" 4 |
| 270 |
.IX Item "$true = $ctx->pass_and_release()" |
| 271 |
.PD 0 |
| 272 |
.ie n .IP "$true = $ctx\->pass_and_release($name)" 4 |
| 273 |
.el .IP "\f(CW$true\fR = \f(CW$ctx\fR\->pass_and_release($name)" 4 |
| 274 |
.IX Item "$true = $ctx->pass_and_release($name)" |
| 275 |
.PD |
| 276 |
This is a combination of \f(CWpass()\fR and \f(CWrelease()\fR. You can use this if you do |
| 277 |
not plan to do anything with the context after sending the event. This helps |
| 278 |
write more clear and compact code. |
| 279 |
.Sp |
| 280 |
.Vb 4 |
| 281 |
\& sub shorthand { |
| 282 |
\& my ($bool, $name) = @_; |
| 283 |
\& my $ctx = context(); |
| 284 |
\& return $ctx\->pass_and_release($name) if $bool; |
| 285 |
\& |
| 286 |
\& ... Handle a failure ... |
| 287 |
\& } |
| 288 |
\& |
| 289 |
\& sub longform { |
| 290 |
\& my ($bool, $name) = @_; |
| 291 |
\& my $ctx = context(); |
| 292 |
\& |
| 293 |
\& if ($bool) { |
| 294 |
\& $ctx\->pass($name); |
| 295 |
\& $ctx\->release; |
| 296 |
\& return 1; |
| 297 |
\& } |
| 298 |
\& |
| 299 |
\& ... Handle a failure ... |
| 300 |
\& } |
| 301 |
.Ve |
| 302 |
.ie n .IP "my $event = $ctx\->\fBfail()\fR" 4 |
| 303 |
.el .IP "my \f(CW$event\fR = \f(CW$ctx\fR\->\fBfail()\fR" 4 |
| 304 |
.IX Item "my $event = $ctx->fail()" |
| 305 |
.PD 0 |
| 306 |
.ie n .IP "my $event = $ctx\->fail($name)" 4 |
| 307 |
.el .IP "my \f(CW$event\fR = \f(CW$ctx\fR\->fail($name)" 4 |
| 308 |
.IX Item "my $event = $ctx->fail($name)" |
| 309 |
.ie n .IP "my $event = $ctx\->fail($name, @diagnostics)" 4 |
| 310 |
.el .IP "my \f(CW$event\fR = \f(CW$ctx\fR\->fail($name, \f(CW@diagnostics\fR)" 4 |
| 311 |
.IX Item "my $event = $ctx->fail($name, @diagnostics)" |
| 312 |
.PD |
| 313 |
This lets you send an Test2::Event::Fail event. You may optionally provide a |
| 314 |
\&\f(CW$name\fR and \f(CW@diagnostics\fR messages. |
| 315 |
.Sp |
| 316 |
Diagnostics messages can be simple strings, data structures, or instances of |
| 317 |
Test2::EventFacet::Info::Table (which are converted inline into the |
| 318 |
Test2::EventFacet::Info structure). |
| 319 |
.ie n .IP "my $false = $ctx\->\fBfail_and_release()\fR" 4 |
| 320 |
.el .IP "my \f(CW$false\fR = \f(CW$ctx\fR\->\fBfail_and_release()\fR" 4 |
| 321 |
.IX Item "my $false = $ctx->fail_and_release()" |
| 322 |
.PD 0 |
| 323 |
.ie n .IP "my $false = $ctx\->fail_and_release($name)" 4 |
| 324 |
.el .IP "my \f(CW$false\fR = \f(CW$ctx\fR\->fail_and_release($name)" 4 |
| 325 |
.IX Item "my $false = $ctx->fail_and_release($name)" |
| 326 |
.ie n .IP "my $false = $ctx\->fail_and_release($name, @diagnostics)" 4 |
| 327 |
.el .IP "my \f(CW$false\fR = \f(CW$ctx\fR\->fail_and_release($name, \f(CW@diagnostics\fR)" 4 |
| 328 |
.IX Item "my $false = $ctx->fail_and_release($name, @diagnostics)" |
| 329 |
.PD |
| 330 |
This is a combination of \f(CWfail()\fR and \f(CWrelease()\fR. This can be used to write |
| 331 |
clearer and shorter code. |
| 332 |
.Sp |
| 333 |
.Vb 4 |
| 334 |
\& sub shorthand { |
| 335 |
\& my ($bool, $name) = @_; |
| 336 |
\& my $ctx = context(); |
| 337 |
\& return $ctx\->fail_and_release($name) unless $bool; |
| 338 |
\& |
| 339 |
\& ... Handle a success ... |
| 340 |
\& } |
| 341 |
\& |
| 342 |
\& sub longform { |
| 343 |
\& my ($bool, $name) = @_; |
| 344 |
\& my $ctx = context(); |
| 345 |
\& |
| 346 |
\& unless ($bool) { |
| 347 |
\& $ctx\->pass($name); |
| 348 |
\& $ctx\->release; |
| 349 |
\& return 1; |
| 350 |
\& } |
| 351 |
\& |
| 352 |
\& ... Handle a success ... |
| 353 |
\& } |
| 354 |
.Ve |
| 355 |
.ie n .IP "$event = $ctx\->ok($bool, $name)" 4 |
| 356 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->ok($bool, \f(CW$name\fR)" 4 |
| 357 |
.IX Item "$event = $ctx->ok($bool, $name)" |
| 358 |
.PD 0 |
| 359 |
.ie n .IP "$event = $ctx\->ok($bool, $name, \e@on_fail)" 4 |
| 360 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->ok($bool, \f(CW$name\fR, \e@on_fail)" 4 |
| 361 |
.IX Item "$event = $ctx->ok($bool, $name, @on_fail)" |
| 362 |
.PD |
| 363 |
\&\fBNOTE:\fR Use of this method is discouraged in favor of \f(CWpass()\fR and \f(CWfail()\fR |
| 364 |
which produce Test2::Event::Pass and Test2::Event::Fail events. These |
| 365 |
newer event types are faster and less crufty. |
| 366 |
.Sp |
| 367 |
This will create an Test2::Event::Ok object for you. If \f(CW$bool\fR is false |
| 368 |
then an Test2::Event::Diag event will be sent as well with details about the |
| 369 |
failure. If you do not want automatic diagnostics you should use the |
| 370 |
\&\f(CWsend_event()\fR method directly. |
| 371 |
.Sp |
| 372 |
The third argument \f(CW\*(C`\e@on_fail\*(C'\fR) is an optional set of diagnostics to be sent in |
| 373 |
the event of a test failure. Unlike with \f(CWfail()\fR these diagnostics must be |
| 374 |
plain strings, data structures are not supported. |
| 375 |
.ie n .IP "$event = $ctx\->note($message)" 4 |
| 376 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->note($message)" 4 |
| 377 |
.IX Item "$event = $ctx->note($message)" |
| 378 |
Send an Test2::Event::Note. This event prints a message to STDOUT. |
| 379 |
.ie n .IP "$event = $ctx\->diag($message)" 4 |
| 380 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->diag($message)" 4 |
| 381 |
.IX Item "$event = $ctx->diag($message)" |
| 382 |
Send an Test2::Event::Diag. This event prints a message to STDERR. |
| 383 |
.ie n .IP "$event = $ctx\->plan($max)" 4 |
| 384 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->plan($max)" 4 |
| 385 |
.IX Item "$event = $ctx->plan($max)" |
| 386 |
.PD 0 |
| 387 |
.ie n .IP "$event = $ctx\->plan(0, 'SKIP', $reason)" 4 |
| 388 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->plan(0, 'SKIP', \f(CW$reason\fR)" 4 |
| 389 |
.IX Item "$event = $ctx->plan(0, 'SKIP', $reason)" |
| 390 |
.PD |
| 391 |
This can be used to send an Test2::Event::Plan event. This event |
| 392 |
usually takes either a number of tests you expect to run. Optionally you can |
| 393 |
set the expected count to 0 and give the 'SKIP' directive with a reason to |
| 394 |
cause all tests to be skipped. |
| 395 |
.ie n .IP "$event = $ctx\->skip($name, $reason);" 4 |
| 396 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->skip($name, \f(CW$reason\fR);" 4 |
| 397 |
.IX Item "$event = $ctx->skip($name, $reason);" |
| 398 |
Send an Test2::Event::Skip event. |
| 399 |
.ie n .IP "$event = $ctx\->bail($reason)" 4 |
| 400 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->bail($reason)" 4 |
| 401 |
.IX Item "$event = $ctx->bail($reason)" |
| 402 |
This sends an Test2::Event::Bail event. This event will completely |
| 403 |
terminate all testing. |
| 404 |
.ie n .IP "$event = $ctx\->send_ev2(%facets)" 4 |
| 405 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->send_ev2(%facets)" 4 |
| 406 |
.IX Item "$event = $ctx->send_ev2(%facets)" |
| 407 |
This lets you build and send a V2 event directly from facets. The event is |
| 408 |
returned after it is sent. |
| 409 |
.Sp |
| 410 |
This example sends a single assertion, a note (comment for stdout in |
| 411 |
Test::Builder talk) and sets the plan to 1. |
| 412 |
.Sp |
| 413 |
.Vb 5 |
| 414 |
\& my $event = $ctx\->send_event( |
| 415 |
\& plan => {count => 1}, |
| 416 |
\& assert => {pass => 1, details => "A passing assert"}, |
| 417 |
\& info => [{tag => \*(AqNOTE\*(Aq, details => "This is a note"}], |
| 418 |
\& ); |
| 419 |
.Ve |
| 420 |
.ie n .IP "$event = $ctx\->build_e2(%facets)" 4 |
| 421 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->build_e2(%facets)" 4 |
| 422 |
.IX Item "$event = $ctx->build_e2(%facets)" |
| 423 |
This is the same as \f(CWsend_ev2()\fR, except it builds and returns the event |
| 424 |
without sending it. |
| 425 |
.ie n .IP "$event = $ctx\->send_ev2_and_release($Type, %parameters)" 4 |
| 426 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->send_ev2_and_release($Type, \f(CW%parameters\fR)" 4 |
| 427 |
.IX Item "$event = $ctx->send_ev2_and_release($Type, %parameters)" |
| 428 |
This is a combination of \f(CWsend_ev2()\fR and \f(CWrelease()\fR. |
| 429 |
.Sp |
| 430 |
.Vb 4 |
| 431 |
\& sub shorthand { |
| 432 |
\& my $ctx = context(); |
| 433 |
\& return $ctx\->send_ev2_and_release(assert => {pass => 1, details => \*(Aqfoo\*(Aq}); |
| 434 |
\& } |
| 435 |
\& |
| 436 |
\& sub longform { |
| 437 |
\& my $ctx = context(); |
| 438 |
\& my $event = $ctx\->send_ev2(assert => {pass => 1, details => \*(Aqfoo\*(Aq}); |
| 439 |
\& $ctx\->release; |
| 440 |
\& return $event; |
| 441 |
\& } |
| 442 |
.Ve |
| 443 |
.ie n .IP "$event = $ctx\->send_event($Type, %parameters)" 4 |
| 444 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->send_event($Type, \f(CW%parameters\fR)" 4 |
| 445 |
.IX Item "$event = $ctx->send_event($Type, %parameters)" |
| 446 |
\&\fBIt is better to use send_ev2() in new code.\fR |
| 447 |
.Sp |
| 448 |
This lets you build and send an event of any type. The \f(CW$Type\fR argument should |
| 449 |
be the event package name with \f(CW\*(C`Test2::Event::\*(C'\fR left off, or a fully |
| 450 |
qualified package name prefixed with a '+'. The event is returned after it is |
| 451 |
sent. |
| 452 |
.Sp |
| 453 |
.Vb 1 |
| 454 |
\& my $event = $ctx\->send_event(\*(AqOk\*(Aq, ...); |
| 455 |
.Ve |
| 456 |
.Sp |
| 457 |
or |
| 458 |
.Sp |
| 459 |
.Vb 1 |
| 460 |
\& my $event = $ctx\->send_event(\*(Aq+Test2::Event::Ok\*(Aq, ...); |
| 461 |
.Ve |
| 462 |
.ie n .IP "$event = $ctx\->build_event($Type, %parameters)" 4 |
| 463 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->build_event($Type, \f(CW%parameters\fR)" 4 |
| 464 |
.IX Item "$event = $ctx->build_event($Type, %parameters)" |
| 465 |
\&\fBIt is better to use build_ev2() in new code.\fR |
| 466 |
.Sp |
| 467 |
This is the same as \f(CWsend_event()\fR, except it builds and returns the event |
| 468 |
without sending it. |
| 469 |
.ie n .IP "$event = $ctx\->send_event_and_release($Type, %parameters)" 4 |
| 470 |
.el .IP "\f(CW$event\fR = \f(CW$ctx\fR\->send_event_and_release($Type, \f(CW%parameters\fR)" 4 |
| 471 |
.IX Item "$event = $ctx->send_event_and_release($Type, %parameters)" |
| 472 |
\&\fBIt is better to use send_ev2_and_release() in new code.\fR |
| 473 |
.Sp |
| 474 |
This is a combination of \f(CWsend_event()\fR and \f(CWrelease()\fR. |
| 475 |
.Sp |
| 476 |
.Vb 4 |
| 477 |
\& sub shorthand { |
| 478 |
\& my $ctx = context(); |
| 479 |
\& return $ctx\->send_event_and_release(Pass => { name => \*(Aqfoo\*(Aq }); |
| 480 |
\& } |
| 481 |
\& |
| 482 |
\& sub longform { |
| 483 |
\& my $ctx = context(); |
| 484 |
\& my $event = $ctx\->send_event(Pass => { name => \*(Aqfoo\*(Aq }); |
| 485 |
\& $ctx\->release; |
| 486 |
\& return $event; |
| 487 |
\& } |
| 488 |
.Ve |
| 489 |
.SH HOOKS |
| 490 |
.IX Header "HOOKS" |
| 491 |
There are 2 types of hooks, init hooks, and release hooks. As the names |
| 492 |
suggest, these hooks are triggered when contexts are created or released. |
| 493 |
.SS "INIT HOOKS" |
| 494 |
.IX Subsection "INIT HOOKS" |
| 495 |
These are called whenever a context is initialized. That means when a new |
| 496 |
instance is created. These hooks are \fBNOT\fR called every time something |
| 497 |
requests a context, just when a new one is created. |
| 498 |
.PP |
| 499 |
\fIGLOBAL\fR |
| 500 |
.IX Subsection "GLOBAL" |
| 501 |
.PP |
| 502 |
This is how you add a global init callback. Global callbacks happen for every |
| 503 |
context for any hub or stack. |
| 504 |
.PP |
| 505 |
.Vb 4 |
| 506 |
\& Test2::API::test2_add_callback_context_init(sub { |
| 507 |
\& my $ctx = shift; |
| 508 |
\& ... |
| 509 |
\& }); |
| 510 |
.Ve |
| 511 |
.PP |
| 512 |
\fIPER HUB\fR |
| 513 |
.IX Subsection "PER HUB" |
| 514 |
.PP |
| 515 |
This is how you add an init callback for all contexts created for a given hub. |
| 516 |
These callbacks will not run for other hubs. |
| 517 |
.PP |
| 518 |
.Vb 4 |
| 519 |
\& $hub\->add_context_init(sub { |
| 520 |
\& my $ctx = shift; |
| 521 |
\& ... |
| 522 |
\& }); |
| 523 |
.Ve |
| 524 |
.PP |
| 525 |
\fIPER CONTEXT\fR |
| 526 |
.IX Subsection "PER CONTEXT" |
| 527 |
.PP |
| 528 |
This is how you specify an init hook that will only run if your call to |
| 529 |
\&\f(CWcontext()\fR generates a new context. The callback will be ignored if |
| 530 |
\&\f(CWcontext()\fR is returning an existing context. |
| 531 |
.PP |
| 532 |
.Vb 4 |
| 533 |
\& my $ctx = context(on_init => sub { |
| 534 |
\& my $ctx = shift; |
| 535 |
\& ... |
| 536 |
\& }); |
| 537 |
.Ve |
| 538 |
.SS "RELEASE HOOKS" |
| 539 |
.IX Subsection "RELEASE HOOKS" |
| 540 |
These are called whenever a context is released. That means when the last |
| 541 |
reference to the instance is about to be destroyed. These hooks are \fBNOT\fR |
| 542 |
called every time \f(CW\*(C`$ctx\->release\*(C'\fR is called. |
| 543 |
.PP |
| 544 |
\fIGLOBAL\fR |
| 545 |
.IX Subsection "GLOBAL" |
| 546 |
.PP |
| 547 |
This is how you add a global release callback. Global callbacks happen for every |
| 548 |
context for any hub or stack. |
| 549 |
.PP |
| 550 |
.Vb 4 |
| 551 |
\& Test2::API::test2_add_callback_context_release(sub { |
| 552 |
\& my $ctx = shift; |
| 553 |
\& ... |
| 554 |
\& }); |
| 555 |
.Ve |
| 556 |
.PP |
| 557 |
\fIPER HUB\fR |
| 558 |
.IX Subsection "PER HUB" |
| 559 |
.PP |
| 560 |
This is how you add a release callback for all contexts created for a given |
| 561 |
hub. These callbacks will not run for other hubs. |
| 562 |
.PP |
| 563 |
.Vb 4 |
| 564 |
\& $hub\->add_context_release(sub { |
| 565 |
\& my $ctx = shift; |
| 566 |
\& ... |
| 567 |
\& }); |
| 568 |
.Ve |
| 569 |
.PP |
| 570 |
\fIPER CONTEXT\fR |
| 571 |
.IX Subsection "PER CONTEXT" |
| 572 |
.PP |
| 573 |
This is how you add release callbacks directly to a context. The callback will |
| 574 |
\&\fBALWAYS\fR be added to the context that gets returned, it does not matter if a |
| 575 |
new one is generated, or if an existing one is returned. |
| 576 |
.PP |
| 577 |
.Vb 4 |
| 578 |
\& my $ctx = context(on_release => sub { |
| 579 |
\& my $ctx = shift; |
| 580 |
\& ... |
| 581 |
\& }); |
| 582 |
.Ve |
| 583 |
.SH "THIRD PARTY META-DATA" |
| 584 |
.IX Header "THIRD PARTY META-DATA" |
| 585 |
This object consumes Test2::Util::ExternalMeta which provides a consistent |
| 586 |
way for you to attach meta-data to instances of this class. This is useful for |
| 587 |
tools, plugins, and other extensions. |
| 588 |
.SH SOURCE |
| 589 |
.IX Header "SOURCE" |
| 590 |
The source code repository for Test2 can be found at |
| 591 |
<https://github.com/Test\-More/test\-more/>. |
| 592 |
.SH MAINTAINERS |
| 593 |
.IX Header "MAINTAINERS" |
| 594 |
.IP "Chad Granum <[email protected]>" 4 |
| 595 |
.IX Item "Chad Granum <[email protected]>" |
| 596 |
.SH AUTHORS |
| 597 |
.IX Header "AUTHORS" |
| 598 |
.PD 0 |
| 599 |
.IP "Chad Granum <[email protected]>" 4 |
| 600 |
.IX Item "Chad Granum <[email protected]>" |
| 601 |
.IP "Kent Fredric <[email protected]>" 4 |
| 602 |
.IX Item "Kent Fredric <[email protected]>" |
| 603 |
.PD |
| 604 |
.SH COPYRIGHT |
| 605 |
.IX Header "COPYRIGHT" |
| 606 |
Copyright 2020 Chad Granum <[email protected]>. |
| 607 |
.PP |
| 608 |
This program is free software; you can redistribute it and/or |
| 609 |
modify it under the same terms as Perl itself. |
| 610 |
.PP |
| 611 |
See <https://dev.perl.org/licenses/> |