| 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 "Test::Builder 3perl" |
| 58 |
.TH Test::Builder 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 |
Test::Builder \- Backend for building test libraries |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 2 |
| 68 |
\& package My::Test::Module; |
| 69 |
\& use base \*(AqTest::Builder::Module\*(Aq; |
| 70 |
\& |
| 71 |
\& my $CLASS = _\|_PACKAGE_\|_; |
| 72 |
\& |
| 73 |
\& sub ok { |
| 74 |
\& my($test, $name) = @_; |
| 75 |
\& my $tb = $CLASS\->builder; |
| 76 |
\& |
| 77 |
\& $tb\->ok($test, $name); |
| 78 |
\& } |
| 79 |
.Ve |
| 80 |
.SH DESCRIPTION |
| 81 |
.IX Header "DESCRIPTION" |
| 82 |
Test::Simple and Test::More have proven to be popular testing modules, |
| 83 |
but they're not always flexible enough. Test::Builder provides a |
| 84 |
building block upon which to write your own test libraries \fIwhich can |
| 85 |
work together\fR. |
| 86 |
.SS Construction |
| 87 |
.IX Subsection "Construction" |
| 88 |
.IP \fBnew\fR 4 |
| 89 |
.IX Item "new" |
| 90 |
.Vb 1 |
| 91 |
\& my $Test = Test::Builder\->new; |
| 92 |
.Ve |
| 93 |
.Sp |
| 94 |
Returns a Test::Builder object representing the current state of the |
| 95 |
test. |
| 96 |
.Sp |
| 97 |
Since you only run one test per program \f(CW\*(C`new\*(C'\fR always returns the same |
| 98 |
Test::Builder object. No matter how many times you call \f(CWnew()\fR, you're |
| 99 |
getting the same object. This is called a singleton. This is done so that |
| 100 |
multiple modules share such global information as the test counter and |
| 101 |
where test output is going. |
| 102 |
.Sp |
| 103 |
If you want a completely new Test::Builder object different from the |
| 104 |
singleton, use \f(CW\*(C`create\*(C'\fR. |
| 105 |
.IP \fBcreate\fR 4 |
| 106 |
.IX Item "create" |
| 107 |
.Vb 1 |
| 108 |
\& my $Test = Test::Builder\->create; |
| 109 |
.Ve |
| 110 |
.Sp |
| 111 |
Ok, so there can be more than one Test::Builder object and this is how |
| 112 |
you get it. You might use this instead of \f(CWnew()\fR if you're testing |
| 113 |
a Test::Builder based module, but otherwise you probably want \f(CW\*(C`new\*(C'\fR. |
| 114 |
.Sp |
| 115 |
\&\fBNOTE\fR: the implementation is not complete. \f(CW\*(C`level\*(C'\fR, for example, is still |
| 116 |
shared by \fBall\fR Test::Builder objects, even ones created using this method. |
| 117 |
Also, the method name may change in the future. |
| 118 |
.IP \fBsubtest\fR 4 |
| 119 |
.IX Item "subtest" |
| 120 |
.Vb 1 |
| 121 |
\& $builder\->subtest($name, \e&subtests, @args); |
| 122 |
.Ve |
| 123 |
.Sp |
| 124 |
See documentation of \f(CW\*(C`subtest\*(C'\fR in Test::More. |
| 125 |
.Sp |
| 126 |
\&\f(CW\*(C`subtest\*(C'\fR also, and optionally, accepts arguments which will be passed to the |
| 127 |
subtests reference. |
| 128 |
.IP \fBname\fR 4 |
| 129 |
.IX Item "name" |
| 130 |
.Vb 1 |
| 131 |
\& diag $builder\->name; |
| 132 |
.Ve |
| 133 |
.Sp |
| 134 |
Returns the name of the current builder. Top level builders default to \f(CW$0\fR |
| 135 |
(the name of the executable). Child builders are named via the \f(CW\*(C`child\*(C'\fR |
| 136 |
method. If no name is supplied, will be named "Child of \f(CW$parent\fR\->name". |
| 137 |
.IP \fBreset\fR 4 |
| 138 |
.IX Item "reset" |
| 139 |
.Vb 1 |
| 140 |
\& $Test\->reset; |
| 141 |
.Ve |
| 142 |
.Sp |
| 143 |
Reinitializes the Test::Builder singleton to its original state. |
| 144 |
Mostly useful for tests run in persistent environments where the same |
| 145 |
test might be run multiple times in the same process. |
| 146 |
.SS "Setting up tests" |
| 147 |
.IX Subsection "Setting up tests" |
| 148 |
These methods are for setting up tests and declaring how many there |
| 149 |
are. You usually only want to call one of these methods. |
| 150 |
.IP \fBplan\fR 4 |
| 151 |
.IX Item "plan" |
| 152 |
.Vb 3 |
| 153 |
\& $Test\->plan(\*(Aqno_plan\*(Aq); |
| 154 |
\& $Test\->plan( skip_all => $reason ); |
| 155 |
\& $Test\->plan( tests => $num_tests ); |
| 156 |
.Ve |
| 157 |
.Sp |
| 158 |
A convenient way to set up your tests. Call this and Test::Builder |
| 159 |
will print the appropriate headers and take the appropriate actions. |
| 160 |
.Sp |
| 161 |
If you call \f(CWplan()\fR, don't call any of the other methods below. |
| 162 |
.IP \fBexpected_tests\fR 4 |
| 163 |
.IX Item "expected_tests" |
| 164 |
.Vb 2 |
| 165 |
\& my $max = $Test\->expected_tests; |
| 166 |
\& $Test\->expected_tests($max); |
| 167 |
.Ve |
| 168 |
.Sp |
| 169 |
Gets/sets the number of tests we expect this test to run and prints out |
| 170 |
the appropriate headers. |
| 171 |
.IP \fBno_plan\fR 4 |
| 172 |
.IX Item "no_plan" |
| 173 |
.Vb 1 |
| 174 |
\& $Test\->no_plan; |
| 175 |
.Ve |
| 176 |
.Sp |
| 177 |
Declares that this test will run an indeterminate number of tests. |
| 178 |
.IP \fBdone_testing\fR 4 |
| 179 |
.IX Item "done_testing" |
| 180 |
.Vb 2 |
| 181 |
\& $Test\->done_testing(); |
| 182 |
\& $Test\->done_testing($num_tests); |
| 183 |
.Ve |
| 184 |
.Sp |
| 185 |
Declares that you are done testing, no more tests will be run after this point. |
| 186 |
.Sp |
| 187 |
If a plan has not yet been output, it will do so. |
| 188 |
.Sp |
| 189 |
\&\f(CW$num_tests\fR is the number of tests you planned to run. If a numbered |
| 190 |
plan was already declared, and if this contradicts, a failing test |
| 191 |
will be run to reflect the planning mistake. If \f(CW\*(C`no_plan\*(C'\fR was declared, |
| 192 |
this will override. |
| 193 |
.Sp |
| 194 |
If \f(CWdone_testing()\fR is called twice, the second call will issue a |
| 195 |
failing test. |
| 196 |
.Sp |
| 197 |
If \f(CW$num_tests\fR is omitted, the number of tests run will be used, like |
| 198 |
no_plan. |
| 199 |
.Sp |
| 200 |
\&\f(CWdone_testing()\fR is, in effect, used when you'd want to use \f(CW\*(C`no_plan\*(C'\fR, but |
| 201 |
safer. You'd use it like so: |
| 202 |
.Sp |
| 203 |
.Vb 2 |
| 204 |
\& $Test\->ok($a == $b); |
| 205 |
\& $Test\->done_testing(); |
| 206 |
.Ve |
| 207 |
.Sp |
| 208 |
Or to plan a variable number of tests: |
| 209 |
.Sp |
| 210 |
.Vb 4 |
| 211 |
\& for my $test (@tests) { |
| 212 |
\& $Test\->ok($test); |
| 213 |
\& } |
| 214 |
\& $Test\->done_testing(scalar @tests); |
| 215 |
.Ve |
| 216 |
.IP \fBhas_plan\fR 4 |
| 217 |
.IX Item "has_plan" |
| 218 |
.Vb 1 |
| 219 |
\& $plan = $Test\->has_plan |
| 220 |
.Ve |
| 221 |
.Sp |
| 222 |
Find out whether a plan has been defined. \f(CW$plan\fR is either \f(CW\*(C`undef\*(C'\fR (no plan |
| 223 |
has been set), \f(CW\*(C`no_plan\*(C'\fR (indeterminate # of tests) or an integer (the number |
| 224 |
of expected tests). |
| 225 |
.IP \fBskip_all\fR 4 |
| 226 |
.IX Item "skip_all" |
| 227 |
.Vb 2 |
| 228 |
\& $Test\->skip_all; |
| 229 |
\& $Test\->skip_all($reason); |
| 230 |
.Ve |
| 231 |
.Sp |
| 232 |
Skips all the tests, using the given \f(CW$reason\fR. Exits immediately with 0. |
| 233 |
.IP \fBexported_to\fR 4 |
| 234 |
.IX Item "exported_to" |
| 235 |
.Vb 2 |
| 236 |
\& my $pack = $Test\->exported_to; |
| 237 |
\& $Test\->exported_to($pack); |
| 238 |
.Ve |
| 239 |
.Sp |
| 240 |
Tells Test::Builder what package you exported your functions to. |
| 241 |
.Sp |
| 242 |
This method isn't terribly useful since modules which share the same |
| 243 |
Test::Builder object might get exported to different packages and only |
| 244 |
the last one will be honored. |
| 245 |
.SS "Running tests" |
| 246 |
.IX Subsection "Running tests" |
| 247 |
These actually run the tests, analogous to the functions in Test::More. |
| 248 |
.PP |
| 249 |
They all return true if the test passed, false if the test failed. |
| 250 |
.PP |
| 251 |
\&\f(CW$name\fR is always optional. |
| 252 |
.IP \fBok\fR 4 |
| 253 |
.IX Item "ok" |
| 254 |
.Vb 1 |
| 255 |
\& $Test\->ok($test, $name); |
| 256 |
.Ve |
| 257 |
.Sp |
| 258 |
Your basic test. Pass if \f(CW$test\fR is true, fail if \f(CW$test\fR is false. Just |
| 259 |
like Test::Simple's \f(CWok()\fR. |
| 260 |
.IP \fBis_eq\fR 4 |
| 261 |
.IX Item "is_eq" |
| 262 |
.Vb 1 |
| 263 |
\& $Test\->is_eq($got, $expected, $name); |
| 264 |
.Ve |
| 265 |
.Sp |
| 266 |
Like Test::More's \f(CWis()\fR. Checks if \f(CW\*(C`$got eq $expected\*(C'\fR. This is the |
| 267 |
string version. |
| 268 |
.Sp |
| 269 |
\&\f(CW\*(C`undef\*(C'\fR only ever matches another \f(CW\*(C`undef\*(C'\fR. |
| 270 |
.IP \fBis_num\fR 4 |
| 271 |
.IX Item "is_num" |
| 272 |
.Vb 1 |
| 273 |
\& $Test\->is_num($got, $expected, $name); |
| 274 |
.Ve |
| 275 |
.Sp |
| 276 |
Like Test::More's \f(CWis()\fR. Checks if \f(CW\*(C`$got == $expected\*(C'\fR. This is the |
| 277 |
numeric version. |
| 278 |
.Sp |
| 279 |
\&\f(CW\*(C`undef\*(C'\fR only ever matches another \f(CW\*(C`undef\*(C'\fR. |
| 280 |
.IP \fBisnt_eq\fR 4 |
| 281 |
.IX Item "isnt_eq" |
| 282 |
.Vb 1 |
| 283 |
\& $Test\->isnt_eq($got, $dont_expect, $name); |
| 284 |
.Ve |
| 285 |
.Sp |
| 286 |
Like Test::More's \f(CWisnt()\fR. Checks if \f(CW\*(C`$got ne $dont_expect\*(C'\fR. This is |
| 287 |
the string version. |
| 288 |
.IP \fBisnt_num\fR 4 |
| 289 |
.IX Item "isnt_num" |
| 290 |
.Vb 1 |
| 291 |
\& $Test\->isnt_num($got, $dont_expect, $name); |
| 292 |
.Ve |
| 293 |
.Sp |
| 294 |
Like Test::More's \f(CWisnt()\fR. Checks if \f(CW\*(C`$got ne $dont_expect\*(C'\fR. This is |
| 295 |
the numeric version. |
| 296 |
.IP \fBlike\fR 4 |
| 297 |
.IX Item "like" |
| 298 |
.Vb 2 |
| 299 |
\& $Test\->like($thing, qr/$regex/, $name); |
| 300 |
\& $Test\->like($thing, \*(Aq/$regex/\*(Aq, $name); |
| 301 |
.Ve |
| 302 |
.Sp |
| 303 |
Like Test::More's \f(CWlike()\fR. Checks if \f(CW$thing\fR matches the given \f(CW$regex\fR. |
| 304 |
.IP \fBunlike\fR 4 |
| 305 |
.IX Item "unlike" |
| 306 |
.Vb 2 |
| 307 |
\& $Test\->unlike($thing, qr/$regex/, $name); |
| 308 |
\& $Test\->unlike($thing, \*(Aq/$regex/\*(Aq, $name); |
| 309 |
.Ve |
| 310 |
.Sp |
| 311 |
Like Test::More's \f(CWunlike()\fR. Checks if \f(CW$thing\fR \fBdoes not match\fR the |
| 312 |
given \f(CW$regex\fR. |
| 313 |
.IP \fBcmp_ok\fR 4 |
| 314 |
.IX Item "cmp_ok" |
| 315 |
.Vb 1 |
| 316 |
\& $Test\->cmp_ok($thing, $type, $that, $name); |
| 317 |
.Ve |
| 318 |
.Sp |
| 319 |
Works just like Test::More's \f(CWcmp_ok()\fR. |
| 320 |
.Sp |
| 321 |
.Vb 1 |
| 322 |
\& $Test\->cmp_ok($big_num, \*(Aq!=\*(Aq, $other_big_num); |
| 323 |
.Ve |
| 324 |
.SS "Other Testing Methods" |
| 325 |
.IX Subsection "Other Testing Methods" |
| 326 |
These are methods which are used in the course of writing a test but are not themselves tests. |
| 327 |
.IP \fBBAIL_OUT\fR 4 |
| 328 |
.IX Item "BAIL_OUT" |
| 329 |
.Vb 1 |
| 330 |
\& $Test\->BAIL_OUT($reason); |
| 331 |
.Ve |
| 332 |
.Sp |
| 333 |
Indicates to the Test::Harness that things are going so badly all |
| 334 |
testing should terminate. This includes running any additional test |
| 335 |
scripts. |
| 336 |
.Sp |
| 337 |
It will exit with 255. |
| 338 |
.IP \fBskip\fR 4 |
| 339 |
.IX Item "skip" |
| 340 |
.Vb 2 |
| 341 |
\& $Test\->skip; |
| 342 |
\& $Test\->skip($why); |
| 343 |
.Ve |
| 344 |
.Sp |
| 345 |
Skips the current test, reporting \f(CW$why\fR. |
| 346 |
.IP \fBtodo_skip\fR 4 |
| 347 |
.IX Item "todo_skip" |
| 348 |
.Vb 2 |
| 349 |
\& $Test\->todo_skip; |
| 350 |
\& $Test\->todo_skip($why); |
| 351 |
.Ve |
| 352 |
.Sp |
| 353 |
Like \f(CWskip()\fR, only it will declare the test as failing and TODO. Similar |
| 354 |
to |
| 355 |
.Sp |
| 356 |
.Vb 1 |
| 357 |
\& print "not ok $tnum # TODO $why\en"; |
| 358 |
.Ve |
| 359 |
.SS "Test building utility methods" |
| 360 |
.IX Subsection "Test building utility methods" |
| 361 |
These methods are useful when writing your own test methods. |
| 362 |
.IP \fBmaybe_regex\fR 4 |
| 363 |
.IX Item "maybe_regex" |
| 364 |
.Vb 2 |
| 365 |
\& $Test\->maybe_regex(qr/$regex/); |
| 366 |
\& $Test\->maybe_regex(\*(Aq/$regex/\*(Aq); |
| 367 |
.Ve |
| 368 |
.Sp |
| 369 |
This method used to be useful back when Test::Builder worked on Perls |
| 370 |
before 5.6 which didn't have qr//. Now its pretty useless. |
| 371 |
.Sp |
| 372 |
Convenience method for building testing functions that take regular |
| 373 |
expressions as arguments. |
| 374 |
.Sp |
| 375 |
Takes a quoted regular expression produced by \f(CW\*(C`qr//\*(C'\fR, or a string |
| 376 |
representing a regular expression. |
| 377 |
.Sp |
| 378 |
Returns a Perl value which may be used instead of the corresponding |
| 379 |
regular expression, or \f(CW\*(C`undef\*(C'\fR if its argument is not recognized. |
| 380 |
.Sp |
| 381 |
For example, a version of \f(CWlike()\fR, sans the useful diagnostic messages, |
| 382 |
could be written as: |
| 383 |
.Sp |
| 384 |
.Vb 7 |
| 385 |
\& sub laconic_like { |
| 386 |
\& my ($self, $thing, $regex, $name) = @_; |
| 387 |
\& my $usable_regex = $self\->maybe_regex($regex); |
| 388 |
\& die "expecting regex, found \*(Aq$regex\*(Aq\en" |
| 389 |
\& unless $usable_regex; |
| 390 |
\& $self\->ok($thing =~ m/$usable_regex/, $name); |
| 391 |
\& } |
| 392 |
.Ve |
| 393 |
.IP \fBis_fh\fR 4 |
| 394 |
.IX Item "is_fh" |
| 395 |
.Vb 1 |
| 396 |
\& my $is_fh = $Test\->is_fh($thing); |
| 397 |
.Ve |
| 398 |
.Sp |
| 399 |
Determines if the given \f(CW$thing\fR can be used as a filehandle. |
| 400 |
.SS "Test style" |
| 401 |
.IX Subsection "Test style" |
| 402 |
.IP \fBlevel\fR 4 |
| 403 |
.IX Item "level" |
| 404 |
.Vb 1 |
| 405 |
\& $Test\->level($how_high); |
| 406 |
.Ve |
| 407 |
.Sp |
| 408 |
How far up the call stack should \f(CW$Test\fR look when reporting where the |
| 409 |
test failed. |
| 410 |
.Sp |
| 411 |
Defaults to 1. |
| 412 |
.Sp |
| 413 |
Setting \f(CW$Test::Builder::Level\fR overrides. This is typically useful |
| 414 |
localized: |
| 415 |
.Sp |
| 416 |
.Vb 2 |
| 417 |
\& sub my_ok { |
| 418 |
\& my $test = shift; |
| 419 |
\& |
| 420 |
\& local $Test::Builder::Level = $Test::Builder::Level + 1; |
| 421 |
\& $TB\->ok($test); |
| 422 |
\& } |
| 423 |
.Ve |
| 424 |
.Sp |
| 425 |
To be polite to other functions wrapping your own you usually want to increment \f(CW$Level\fR rather than set it to a constant. |
| 426 |
.IP \fBuse_numbers\fR 4 |
| 427 |
.IX Item "use_numbers" |
| 428 |
.Vb 1 |
| 429 |
\& $Test\->use_numbers($on_or_off); |
| 430 |
.Ve |
| 431 |
.Sp |
| 432 |
Whether or not the test should output numbers. That is, this if true: |
| 433 |
.Sp |
| 434 |
.Vb 3 |
| 435 |
\& ok 1 |
| 436 |
\& ok 2 |
| 437 |
\& ok 3 |
| 438 |
.Ve |
| 439 |
.Sp |
| 440 |
or this if false |
| 441 |
.Sp |
| 442 |
.Vb 3 |
| 443 |
\& ok |
| 444 |
\& ok |
| 445 |
\& ok |
| 446 |
.Ve |
| 447 |
.Sp |
| 448 |
Most useful when you can't depend on the test output order, such as |
| 449 |
when threads or forking is involved. |
| 450 |
.Sp |
| 451 |
Defaults to on. |
| 452 |
.IP \fBno_diag\fR 4 |
| 453 |
.IX Item "no_diag" |
| 454 |
.Vb 1 |
| 455 |
\& $Test\->no_diag($no_diag); |
| 456 |
.Ve |
| 457 |
.Sp |
| 458 |
If set true no diagnostics will be printed. This includes calls to |
| 459 |
\&\f(CWdiag()\fR. |
| 460 |
.IP \fBno_ending\fR 4 |
| 461 |
.IX Item "no_ending" |
| 462 |
.Vb 1 |
| 463 |
\& $Test\->no_ending($no_ending); |
| 464 |
.Ve |
| 465 |
.Sp |
| 466 |
Normally, Test::Builder does some extra diagnostics when the test |
| 467 |
ends. It also changes the exit code as described below. |
| 468 |
.Sp |
| 469 |
If this is true, none of that will be done. |
| 470 |
.IP \fBno_header\fR 4 |
| 471 |
.IX Item "no_header" |
| 472 |
.Vb 1 |
| 473 |
\& $Test\->no_header($no_header); |
| 474 |
.Ve |
| 475 |
.Sp |
| 476 |
If set to true, no "1..N" header will be printed. |
| 477 |
.SS Output |
| 478 |
.IX Subsection "Output" |
| 479 |
Controlling where the test output goes. |
| 480 |
.PP |
| 481 |
It's ok for your test to change where STDOUT and STDERR point to, |
| 482 |
Test::Builder's default output settings will not be affected. |
| 483 |
.IP \fBdiag\fR 4 |
| 484 |
.IX Item "diag" |
| 485 |
.Vb 1 |
| 486 |
\& $Test\->diag(@msgs); |
| 487 |
.Ve |
| 488 |
.Sp |
| 489 |
Prints out the given \f(CW@msgs\fR. Like \f(CW\*(C`print\*(C'\fR, arguments are simply |
| 490 |
appended together. |
| 491 |
.Sp |
| 492 |
Normally, it uses the \f(CWfailure_output()\fR handle, but if this is for a |
| 493 |
TODO test, the \f(CWtodo_output()\fR handle is used. |
| 494 |
.Sp |
| 495 |
Output will be indented and marked with a # so as not to interfere |
| 496 |
with test output. A newline will be put on the end if there isn't one |
| 497 |
already. |
| 498 |
.Sp |
| 499 |
We encourage using this rather than calling print directly. |
| 500 |
.Sp |
| 501 |
Returns false. Why? Because \f(CWdiag()\fR is often used in conjunction with |
| 502 |
a failing test (\f(CW\*(C`ok() || diag()\*(C'\fR) it "passes through" the failure. |
| 503 |
.Sp |
| 504 |
.Vb 1 |
| 505 |
\& return ok(...) || diag(...); |
| 506 |
.Ve |
| 507 |
.IP \fBnote\fR 4 |
| 508 |
.IX Item "note" |
| 509 |
.Vb 1 |
| 510 |
\& $Test\->note(@msgs); |
| 511 |
.Ve |
| 512 |
.Sp |
| 513 |
Like \f(CWdiag()\fR, but it prints to the \f(CWoutput()\fR handle so it will not |
| 514 |
normally be seen by the user except in verbose mode. |
| 515 |
.IP \fBexplain\fR 4 |
| 516 |
.IX Item "explain" |
| 517 |
.Vb 1 |
| 518 |
\& my @dump = $Test\->explain(@msgs); |
| 519 |
.Ve |
| 520 |
.Sp |
| 521 |
Will dump the contents of any references in a human readable format. |
| 522 |
Handy for things like... |
| 523 |
.Sp |
| 524 |
.Vb 1 |
| 525 |
\& is_deeply($have, $want) || diag explain $have; |
| 526 |
.Ve |
| 527 |
.Sp |
| 528 |
or |
| 529 |
.Sp |
| 530 |
.Vb 1 |
| 531 |
\& is_deeply($have, $want) || note explain $have; |
| 532 |
.Ve |
| 533 |
.IP \fBoutput\fR 4 |
| 534 |
.IX Item "output" |
| 535 |
.PD 0 |
| 536 |
.IP \fBfailure_output\fR 4 |
| 537 |
.IX Item "failure_output" |
| 538 |
.IP \fBtodo_output\fR 4 |
| 539 |
.IX Item "todo_output" |
| 540 |
.PD |
| 541 |
.Vb 4 |
| 542 |
\& my $filehandle = $Test\->output; |
| 543 |
\& $Test\->output($filehandle); |
| 544 |
\& $Test\->output($filename); |
| 545 |
\& $Test\->output(\e$scalar); |
| 546 |
.Ve |
| 547 |
.Sp |
| 548 |
These methods control where Test::Builder will print its output. |
| 549 |
They take either an open \f(CW$filehandle\fR, a \f(CW$filename\fR to open and write to |
| 550 |
or a \f(CW$scalar\fR reference to append to. It will always return a \f(CW$filehandle\fR. |
| 551 |
.Sp |
| 552 |
\&\fBoutput\fR is where normal "ok/not ok" test output goes. |
| 553 |
.Sp |
| 554 |
Defaults to STDOUT. |
| 555 |
.Sp |
| 556 |
\&\fBfailure_output\fR is where diagnostic output on test failures and |
| 557 |
\&\f(CWdiag()\fR goes. It is normally not read by Test::Harness and instead is |
| 558 |
displayed to the user. |
| 559 |
.Sp |
| 560 |
Defaults to STDERR. |
| 561 |
.Sp |
| 562 |
\&\f(CW\*(C`todo_output\*(C'\fR is used instead of \f(CWfailure_output()\fR for the |
| 563 |
diagnostics of a failing TODO test. These will not be seen by the |
| 564 |
user. |
| 565 |
.Sp |
| 566 |
Defaults to STDOUT. |
| 567 |
.IP reset_outputs 4 |
| 568 |
.IX Item "reset_outputs" |
| 569 |
.Vb 1 |
| 570 |
\& $tb\->reset_outputs; |
| 571 |
.Ve |
| 572 |
.Sp |
| 573 |
Resets all the output filehandles back to their defaults. |
| 574 |
.IP carp 4 |
| 575 |
.IX Item "carp" |
| 576 |
.Vb 1 |
| 577 |
\& $tb\->carp(@message); |
| 578 |
.Ve |
| 579 |
.Sp |
| 580 |
Warns with \f(CW@message\fR but the message will appear to come from the |
| 581 |
point where the original test function was called (\f(CW\*(C`$tb\->caller\*(C'\fR). |
| 582 |
.IP croak 4 |
| 583 |
.IX Item "croak" |
| 584 |
.Vb 1 |
| 585 |
\& $tb\->croak(@message); |
| 586 |
.Ve |
| 587 |
.Sp |
| 588 |
Dies with \f(CW@message\fR but the message will appear to come from the |
| 589 |
point where the original test function was called (\f(CW\*(C`$tb\->caller\*(C'\fR). |
| 590 |
.SS "Test Status and Info" |
| 591 |
.IX Subsection "Test Status and Info" |
| 592 |
.IP \fBno_log_results\fR 4 |
| 593 |
.IX Item "no_log_results" |
| 594 |
This will turn off result long-term storage. Calling this method will make |
| 595 |
\&\f(CW\*(C`details\*(C'\fR and \f(CW\*(C`summary\*(C'\fR useless. You may want to use this if you are running |
| 596 |
enough tests to fill up all available memory. |
| 597 |
.Sp |
| 598 |
.Vb 1 |
| 599 |
\& Test::Builder\->new\->no_log_results(); |
| 600 |
.Ve |
| 601 |
.Sp |
| 602 |
There is no way to turn it back on. |
| 603 |
.IP \fBcurrent_test\fR 4 |
| 604 |
.IX Item "current_test" |
| 605 |
.Vb 2 |
| 606 |
\& my $curr_test = $Test\->current_test; |
| 607 |
\& $Test\->current_test($num); |
| 608 |
.Ve |
| 609 |
.Sp |
| 610 |
Gets/sets the current test number we're on. You usually shouldn't |
| 611 |
have to set this. |
| 612 |
.Sp |
| 613 |
If set forward, the details of the missing tests are filled in as 'unknown'. |
| 614 |
if set backward, the details of the intervening tests are deleted. You |
| 615 |
can erase history if you really want to. |
| 616 |
.IP \fBis_passing\fR 4 |
| 617 |
.IX Item "is_passing" |
| 618 |
.Vb 1 |
| 619 |
\& my $ok = $builder\->is_passing; |
| 620 |
.Ve |
| 621 |
.Sp |
| 622 |
Indicates if the test suite is currently passing. |
| 623 |
.Sp |
| 624 |
More formally, it will be false if anything has happened which makes |
| 625 |
it impossible for the test suite to pass. True otherwise. |
| 626 |
.Sp |
| 627 |
For example, if no tests have run \f(CWis_passing()\fR will be true because |
| 628 |
even though a suite with no tests is a failure you can add a passing |
| 629 |
test to it and start passing. |
| 630 |
.Sp |
| 631 |
Don't think about it too much. |
| 632 |
.IP \fBsummary\fR 4 |
| 633 |
.IX Item "summary" |
| 634 |
.Vb 1 |
| 635 |
\& my @tests = $Test\->summary; |
| 636 |
.Ve |
| 637 |
.Sp |
| 638 |
A simple summary of the tests so far. True for pass, false for fail. |
| 639 |
This is a logical pass/fail, so todos are passes. |
| 640 |
.Sp |
| 641 |
Of course, test #1 is \f(CW$tests\fR[0], etc... |
| 642 |
.IP \fBdetails\fR 4 |
| 643 |
.IX Item "details" |
| 644 |
.Vb 1 |
| 645 |
\& my @tests = $Test\->details; |
| 646 |
.Ve |
| 647 |
.Sp |
| 648 |
Like \f(CWsummary()\fR, but with a lot more detail. |
| 649 |
.Sp |
| 650 |
.Vb 7 |
| 651 |
\& $tests[$test_num \- 1] = |
| 652 |
\& { \*(Aqok\*(Aq => is the test considered a pass? |
| 653 |
\& actual_ok => did it literally say \*(Aqok\*(Aq? |
| 654 |
\& name => name of the test (if any) |
| 655 |
\& type => type of test (if any, see below). |
| 656 |
\& reason => reason for the above (if any) |
| 657 |
\& }; |
| 658 |
.Ve |
| 659 |
.Sp |
| 660 |
\&'ok' is true if Test::Harness will consider the test to be a pass. |
| 661 |
.Sp |
| 662 |
\&'actual_ok' is a reflection of whether or not the test literally |
| 663 |
printed 'ok' or 'not ok'. This is for examining the result of 'todo' |
| 664 |
tests. |
| 665 |
.Sp |
| 666 |
\&'name' is the name of the test. |
| 667 |
.Sp |
| 668 |
\&'type' indicates if it was a special test. Normal tests have a type |
| 669 |
of ''. Type can be one of the following: |
| 670 |
.Sp |
| 671 |
.Vb 4 |
| 672 |
\& skip see skip() |
| 673 |
\& todo see todo() |
| 674 |
\& todo_skip see todo_skip() |
| 675 |
\& unknown see below |
| 676 |
.Ve |
| 677 |
.Sp |
| 678 |
Sometimes the Test::Builder test counter is incremented without it |
| 679 |
printing any test output, for example, when \f(CWcurrent_test()\fR is changed. |
| 680 |
In these cases, Test::Builder doesn't know the result of the test, so |
| 681 |
its type is 'unknown'. These details for these tests are filled in. |
| 682 |
They are considered ok, but the name and actual_ok is left \f(CW\*(C`undef\*(C'\fR. |
| 683 |
.Sp |
| 684 |
For example "not ok 23 \- hole count # TODO insufficient donuts" would |
| 685 |
result in this structure: |
| 686 |
.Sp |
| 687 |
.Vb 7 |
| 688 |
\& $tests[22] = # 23 \- 1, since arrays start from 0. |
| 689 |
\& { ok => 1, # logically, the test passed since its todo |
| 690 |
\& actual_ok => 0, # in absolute terms, it failed |
| 691 |
\& name => \*(Aqhole count\*(Aq, |
| 692 |
\& type => \*(Aqtodo\*(Aq, |
| 693 |
\& reason => \*(Aqinsufficient donuts\*(Aq |
| 694 |
\& }; |
| 695 |
.Ve |
| 696 |
.IP \fBtodo\fR 4 |
| 697 |
.IX Item "todo" |
| 698 |
.Vb 2 |
| 699 |
\& my $todo_reason = $Test\->todo; |
| 700 |
\& my $todo_reason = $Test\->todo($pack); |
| 701 |
.Ve |
| 702 |
.Sp |
| 703 |
If the current tests are considered "TODO" it will return the reason, |
| 704 |
if any. This reason can come from a \f(CW$TODO\fR variable or the last call |
| 705 |
to \f(CWtodo_start()\fR. |
| 706 |
.Sp |
| 707 |
Since a TODO test does not need a reason, this function can return an |
| 708 |
empty string even when inside a TODO block. Use \f(CW\*(C`$Test\->in_todo\*(C'\fR |
| 709 |
to determine if you are currently inside a TODO block. |
| 710 |
.Sp |
| 711 |
\&\f(CWtodo()\fR is about finding the right package to look for \f(CW$TODO\fR in. It's |
| 712 |
pretty good at guessing the right package to look at. It first looks for |
| 713 |
the caller based on \f(CW\*(C`$Level + 1\*(C'\fR, since \f(CWtodo()\fR is usually called inside |
| 714 |
a test function. As a last resort it will use \f(CWexported_to()\fR. |
| 715 |
.Sp |
| 716 |
Sometimes there is some confusion about where \f(CWtodo()\fR should be looking |
| 717 |
for the \f(CW$TODO\fR variable. If you want to be sure, tell it explicitly |
| 718 |
what \f(CW$pack\fR to use. |
| 719 |
.IP \fBfind_TODO\fR 4 |
| 720 |
.IX Item "find_TODO" |
| 721 |
.Vb 2 |
| 722 |
\& my $todo_reason = $Test\->find_TODO(); |
| 723 |
\& my $todo_reason = $Test\->find_TODO($pack); |
| 724 |
.Ve |
| 725 |
.Sp |
| 726 |
Like \f(CWtodo()\fR but only returns the value of \f(CW$TODO\fR ignoring |
| 727 |
\&\f(CWtodo_start()\fR. |
| 728 |
.Sp |
| 729 |
Can also be used to set \f(CW$TODO\fR to a new value while returning the |
| 730 |
old value: |
| 731 |
.Sp |
| 732 |
.Vb 1 |
| 733 |
\& my $old_reason = $Test\->find_TODO($pack, 1, $new_reason); |
| 734 |
.Ve |
| 735 |
.IP \fBin_todo\fR 4 |
| 736 |
.IX Item "in_todo" |
| 737 |
.Vb 1 |
| 738 |
\& my $in_todo = $Test\->in_todo; |
| 739 |
.Ve |
| 740 |
.Sp |
| 741 |
Returns true if the test is currently inside a TODO block. |
| 742 |
.IP \fBtodo_start\fR 4 |
| 743 |
.IX Item "todo_start" |
| 744 |
.Vb 2 |
| 745 |
\& $Test\->todo_start(); |
| 746 |
\& $Test\->todo_start($message); |
| 747 |
.Ve |
| 748 |
.Sp |
| 749 |
This method allows you declare all subsequent tests as TODO tests, up until |
| 750 |
the \f(CW\*(C`todo_end\*(C'\fR method has been called. |
| 751 |
.Sp |
| 752 |
The \f(CW\*(C`TODO:\*(C'\fR and \f(CW$TODO\fR syntax is generally pretty good about figuring out |
| 753 |
whether or not we're in a TODO test. However, often we find that this is not |
| 754 |
possible to determine (such as when we want to use \f(CW$TODO\fR but |
| 755 |
the tests are being executed in other packages which can't be inferred |
| 756 |
beforehand). |
| 757 |
.Sp |
| 758 |
Note that you can use this to nest "todo" tests |
| 759 |
.Sp |
| 760 |
.Vb 6 |
| 761 |
\& $Test\->todo_start(\*(Aqworking on this\*(Aq); |
| 762 |
\& # lots of code |
| 763 |
\& $Test\->todo_start(\*(Aqworking on that\*(Aq); |
| 764 |
\& # more code |
| 765 |
\& $Test\->todo_end; |
| 766 |
\& $Test\->todo_end; |
| 767 |
.Ve |
| 768 |
.Sp |
| 769 |
This is generally not recommended, but large testing systems often have weird |
| 770 |
internal needs. |
| 771 |
.Sp |
| 772 |
We've tried to make this also work with the TODO: syntax, but it's not |
| 773 |
guaranteed and its use is also discouraged: |
| 774 |
.Sp |
| 775 |
.Vb 9 |
| 776 |
\& TODO: { |
| 777 |
\& local $TODO = \*(AqWe have work to do!\*(Aq; |
| 778 |
\& $Test\->todo_start(\*(Aqworking on this\*(Aq); |
| 779 |
\& # lots of code |
| 780 |
\& $Test\->todo_start(\*(Aqworking on that\*(Aq); |
| 781 |
\& # more code |
| 782 |
\& $Test\->todo_end; |
| 783 |
\& $Test\->todo_end; |
| 784 |
\& } |
| 785 |
.Ve |
| 786 |
.Sp |
| 787 |
Pick one style or another of "TODO" to be on the safe side. |
| 788 |
.ie n .IP """todo_end""" 4 |
| 789 |
.el .IP \f(CWtodo_end\fR 4 |
| 790 |
.IX Item "todo_end" |
| 791 |
.Vb 1 |
| 792 |
\& $Test\->todo_end; |
| 793 |
.Ve |
| 794 |
.Sp |
| 795 |
Stops running tests as "TODO" tests. This method is fatal if called without a |
| 796 |
preceding \f(CW\*(C`todo_start\*(C'\fR method call. |
| 797 |
.IP \fBcaller\fR 4 |
| 798 |
.IX Item "caller" |
| 799 |
.Vb 3 |
| 800 |
\& my $package = $Test\->caller; |
| 801 |
\& my($pack, $file, $line) = $Test\->caller; |
| 802 |
\& my($pack, $file, $line) = $Test\->caller($height); |
| 803 |
.Ve |
| 804 |
.Sp |
| 805 |
Like the normal \f(CWcaller()\fR, except it reports according to your \f(CWlevel()\fR. |
| 806 |
.Sp |
| 807 |
\&\f(CW$height\fR will be added to the \f(CWlevel()\fR. |
| 808 |
.Sp |
| 809 |
If \f(CWcaller()\fR winds up off the top of the stack it report the highest context. |
| 810 |
.SH "EXIT CODES" |
| 811 |
.IX Header "EXIT CODES" |
| 812 |
If all your tests passed, Test::Builder will exit with zero (which is |
| 813 |
normal). If anything failed it will exit with how many failed. If |
| 814 |
you run less (or more) tests than you planned, the missing (or extras) |
| 815 |
will be considered failures. If no tests were ever run Test::Builder |
| 816 |
will throw a warning and exit with 255. If the test died, even after |
| 817 |
having successfully completed all its tests, it will still be |
| 818 |
considered a failure and will exit with 255. |
| 819 |
.PP |
| 820 |
So the exit codes are... |
| 821 |
.PP |
| 822 |
.Vb 3 |
| 823 |
\& 0 all tests successful |
| 824 |
\& 255 test died or all passed but wrong # of tests run |
| 825 |
\& any other number how many failed (including missing or extras) |
| 826 |
.Ve |
| 827 |
.PP |
| 828 |
If you fail more than 254 tests, it will be reported as 254. |
| 829 |
.SH THREADS |
| 830 |
.IX Header "THREADS" |
| 831 |
In perl 5.8.1 and later, Test::Builder is thread-safe. The test number is |
| 832 |
shared by all threads. This means if one thread sets the test number using |
| 833 |
\&\f(CWcurrent_test()\fR they will all be effected. |
| 834 |
.PP |
| 835 |
While versions earlier than 5.8.1 had threads they contain too many |
| 836 |
bugs to support. |
| 837 |
.PP |
| 838 |
Test::Builder is only thread-aware if threads.pm is loaded \fIbefore\fR |
| 839 |
Test::Builder. |
| 840 |
.PP |
| 841 |
You can directly disable thread support with one of the following: |
| 842 |
.PP |
| 843 |
.Vb 1 |
| 844 |
\& $ENV{T2_NO_IPC} = 1 |
| 845 |
.Ve |
| 846 |
.PP |
| 847 |
or |
| 848 |
.PP |
| 849 |
.Vb 1 |
| 850 |
\& no Test2::IPC; |
| 851 |
.Ve |
| 852 |
.PP |
| 853 |
or |
| 854 |
.PP |
| 855 |
.Vb 1 |
| 856 |
\& Test2::API::test2_ipc_disable() |
| 857 |
.Ve |
| 858 |
.SH MEMORY |
| 859 |
.IX Header "MEMORY" |
| 860 |
An informative hash, accessible via \f(CWdetails()\fR, is stored for each |
| 861 |
test you perform. So memory usage will scale linearly with each test |
| 862 |
run. Although this is not a problem for most test suites, it can |
| 863 |
become an issue if you do large (hundred thousands to million) |
| 864 |
combinatorics tests in the same run. |
| 865 |
.PP |
| 866 |
In such cases, you are advised to either split the test file into smaller |
| 867 |
ones, or use a reverse approach, doing "normal" (code) compares and |
| 868 |
triggering \f(CWfail()\fR should anything go unexpected. |
| 869 |
.PP |
| 870 |
Future versions of Test::Builder will have a way to turn history off. |
| 871 |
.SH EXAMPLES |
| 872 |
.IX Header "EXAMPLES" |
| 873 |
CPAN can provide the best examples. Test::Simple, Test::More, |
| 874 |
Test::Exception and Test::Differences all use Test::Builder. |
| 875 |
.SH "SEE ALSO" |
| 876 |
.IX Header "SEE ALSO" |
| 877 |
.SS INTERNALS |
| 878 |
.IX Subsection "INTERNALS" |
| 879 |
Test2, Test2::API |
| 880 |
.SS LEGACY |
| 881 |
.IX Subsection "LEGACY" |
| 882 |
Test::Simple, Test::More |
| 883 |
.SS EXTERNAL |
| 884 |
.IX Subsection "EXTERNAL" |
| 885 |
Test::Harness |
| 886 |
.SH AUTHORS |
| 887 |
.IX Header "AUTHORS" |
| 888 |
Original code by chromatic, maintained by Michael G Schwern |
| 889 |
<[email protected]> |
| 890 |
.SH MAINTAINERS |
| 891 |
.IX Header "MAINTAINERS" |
| 892 |
.IP "Chad Granum <[email protected]>" 4 |
| 893 |
.IX Item "Chad Granum <[email protected]>" |
| 894 |
.SH COPYRIGHT |
| 895 |
.IX Header "COPYRIGHT" |
| 896 |
Copyright 2002\-2008 by chromatic <[email protected]> and |
| 897 |
Michael G Schwern <[email protected]>. |
| 898 |
.PP |
| 899 |
This program is free software; you can redistribute it and/or |
| 900 |
modify it under the same terms as Perl itself. |
| 901 |
.PP |
| 902 |
See <https://dev.perl.org/licenses/> |