blib/lib/Test/More.pm

filter: Statementstmt 95.3% 345 / 362 Branchbran 91.7% 167 / 182 Conditioncond 85.0% 57 / 67 MC/DCmcdc 82.5% 33 / 40 Subroutinesub 98.0% 51 / 52 Podpod 96.3% 26 / 27 totaltotal 93.0% 679 / 730 CC 131 SCAR 21.2
CC
131
Cov
93%
_deep_check
24.1
isa_ok
14.0
_format_stack
12.0
CRAP 8.4
« blib/lib/Test2/Plugin/ExitSummary.pm ↑ Summary blib/lib/Test2/Util/HashBase.pm »
1 package Test::More;
2  
3 131 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 131 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 131 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 #---- perlcritic exemptions. ----#
8  
9 # We use a lot of subroutine prototypes
10 ## no critic (Subroutines::ProhibitSubroutinePrototypes)
11  
12 # Can't use Carp because it might cause C<use_ok()> to accidentally succeed
13 # even though the module being used forgot to use Carp. Yes, this
14 # actually happened.
15 10 ▶sub _carp {
Subroutine _carp: called CC=1 SCAR=0.0
16 9 my( $file, $line ) = ( caller(1) )[ 1, 2 ];
17 9 return warn @_, " at $file line $line\n";
18 }
19  
20 130 our $VERSION = '1.302226';
21  
22 131 ▶use Test::Builder::Module;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 130 our @ISA = qw(Test::Builder::Module);
24 130 our @EXPORT = qw(ok use_ok require_ok
25 is isnt like unlike is_deeply
26 cmp_ok
27 skip todo todo_skip
28 pass fail
29 eq_array eq_hash eq_set
30 $TODO
31 plan
32 done_testing
33 can_ok isa_ok new_ok
34 diag note explain
35 subtest
36 BAIL_OUT
37 );
38  
39 =head1 NAME
40  
41 Test::More - yet another framework for writing test scripts
42  
43 =head1 SYNOPSIS
44  
45 use Test::More tests => 23;
46 # or
47 use Test::More skip_all => $reason;
48 # or
49 use Test::More; # see done_testing()
50  
51 require_ok( 'Some::Module' );
52  
53 # Various ways to say "ok"
54 ok($got eq $expected, $test_name);
55  
56 is ($got, $expected, $test_name);
57 isnt($got, $expected, $test_name);
58  
59 # Rather than print STDERR "# here's what went wrong\n"
60 diag("here's what went wrong");
61  
62 like ($got, qr/expected/, $test_name);
63 unlike($got, qr/expected/, $test_name);
64  
65 cmp_ok($got, '==', $expected, $test_name);
66  
67 is_deeply($got_complex_structure, $expected_complex_structure, $test_name);
68  
69 SKIP: {
70 skip $why, $how_many unless $have_some_feature;
71  
72 ok( foo(), $test_name );
73 is( foo(42), 23, $test_name );
74 };
75  
76 TODO: {
77 local $TODO = $why;
78  
79 ok( foo(), $test_name );
80 is( foo(42), 23, $test_name );
81 };
82  
83 can_ok($module, @methods);
84 isa_ok($object, $class);
85  
86 pass($test_name);
87 fail($test_name);
88  
89 BAIL_OUT($why);
90  
91 # UNIMPLEMENTED!!!
92 my @status = Test::More::status;
93  
94  
95 =head1 DESCRIPTION
96  
97 B<STOP!> If you're just getting started writing tests, have a look at
98 L<Test2::Suite> first.
99  
100 This is a drop in replacement for Test::Simple which you can switch to once you
101 get the hang of basic testing.
102  
103 The purpose of this module is to provide a wide range of testing
104 utilities. Various ways to say "ok" with better diagnostics,
105 facilities to skip tests, test future features and compare complicated
106 data structures. While you can do almost anything with a simple
107 C<ok()> function, it doesn't provide good diagnostic output.
108  
109  
110 =head2 I love it when a plan comes together
111  
112 Before anything else, you need a testing plan. This basically declares
113 how many tests your script is going to run to protect against premature
114 failure.
115  
116 The preferred way to do this is to declare a plan when you C<use Test::More>.
117  
118 use Test::More tests => 23;
119  
120 There are cases when you will not know beforehand how many tests your
121 script is going to run. In this case, you can declare your tests at
122 the end.
123  
124 use Test::More;
125  
126 ... run your tests ...
127  
128 done_testing( $number_of_tests_run );
129  
130 B<NOTE> C<done_testing()> should never be called in an C<END { ... }> block.
131  
132 Sometimes you really don't know how many tests were run, or it's too
133 difficult to calculate. In which case you can leave off
134 $number_of_tests_run.
135  
136 In some cases, you'll want to completely skip an entire testing script.
137  
138 use Test::More skip_all => $skip_reason;
139  
140 Your script will declare a skip with the reason why you skipped and
141 exit immediately with a zero (success). See L<Test::Harness> for
142 details.
143  
144 If you want to control what functions Test::More will export, you
145 have to use the 'import' option. For example, to import everything
146 but 'fail', you'd do:
147  
148 use Test::More tests => 23, import => ['!fail'];
149  
150 Alternatively, you can use the C<plan()> function. Useful for when you
151 have to calculate the number of tests.
152  
153 use Test::More;
154 plan tests => keys %Stuff * 3;
155  
156 or for deciding between running the tests at all:
157  
158 use Test::More;
159 if( $^O eq 'MacOS' ) {
160 plan skip_all => 'Test irrelevant on MacOS';
161 }
162 else {
163 plan tests => 42;
164 }
165  
166 =cut
167  
168 85 ▶sub plan {
Subroutine plan: called CC=1 SCAR=0.0
Pod documented
169 85 my $tb = Test::More->builder;
170  
171 85 return $tb->plan(@_);
172 }
173  
174 # This implements "use Test::More 'no_diag'" but the behavior is
175 # deprecated.
176 111 ▶sub import_extra {
Subroutine import_extra: called CC=11 SCAR=24.2
Pod documented
177 111 my $class = shift;
178 111 my $list = shift;
179  
180 111 my @other;
181 111 my $idx = 0;
182 111 my $import;
183 111 ▶ while( $idx <= $#{$list} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($idx <= $#{$list;}) 103 111 214
184 102 my $item = $list->[$idx];
185  
186 102 ▶ if( defined $item and $item eq 'no_diag' ) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $item and $item eq 'no_diag') { } 2 101 103
elsif (defined $item and $item eq 'import') { } 4 98 102
Condition66%2/3
defined $item and $item eq "no_diag"
!ll&&!rl&&r
01011
MC/DC50%1/2
defined $item and $item eq "no_diag"
defined $item $item eq "no_diag"
Truth table66%2/3
A and B
A= defined $itemB= $item eq "no_diag"
ABresult
0X0
100
111
187 1 $class->builder->no_diag(1);
188 }
189 ▶ elsif( defined $item and $item eq 'import' ) {
Condition66%2/3
defined $item and $item eq "import"
!ll&&!rl&&r
0983
MC/DC50%1/2
defined $item and $item eq "import"
defined $item $item eq "import"
Truth table66%2/3
A and B
A= defined $itemB= $item eq "import"
ABresult
0X0
100
111
190 3 ▶ if ($import) {
Branch: 1 branch
BranchTrueFalseTotal
if ($import) { } 1 3 4
191 0 push @$import, @{$list->[ ++$idx ]};
192 }
193 else {
194 3 $import = $list->[ ++$idx ];
195 3 push @other, $item, $import;
196 }
197 }
198 else {
199 98 push @other, $item;
200 }
201  
202 102 $idx++;
203 }
204  
205 111 @$list = @other;
206  
207 111 ▶ if ($class eq __PACKAGE__ && (!$import || grep $_ eq '$TODO', @$import)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($class eq __PACKAGE__ and !$import || grep(($_ eq "\$TODO"), @$import)) 109 3 112
Condition66%4/6
$class eq __PACKAGE__ and !$import || grep(($_ eq "\$TODO"), @$import)
!ll&&!rl&&r
03108
not $import or grep(($_ eq "\$TODO"), @$import)
l!l&&r!l&&!r
10803
MC/DC33%1/3
$class eq __PACKAGE__ and !$import || grep(($_ eq "\$TODO"), @$import)
$class eq __PACKAGE__ not $import grep(($_ eq "\$TODO"), @$import)
Truth table50%2/4
A and not(B) or C
A= $class eq __PACKAGE__B= not $importC= grep(($_ eq "\$TODO"), @$import)
ABCresult
0XX0
1000
11X1
1011
208 108 my $to = $class->builder->exported_to;
209 130 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
210 108 *{"$to\::TODO"} = \our $TODO;
211 108 ▶ if ($import) {
Branch: 1 branch
BranchTrueFalseTotal
if ($import) { } 1 108 109
212 0 @$import = grep $_ ne '$TODO', @$import;
213 }
214 else {
215 108 push @$list, import => [grep $_ ne '$TODO', @EXPORT];
216 }
217 }
218  
219 111 return;
220 }
221  
222 =over 4
223  
224 =item B<done_testing>
225  
226 done_testing();
227 done_testing($number_of_tests);
228  
229 If you don't know how many tests you're going to run, you can issue
230 the plan when you're done running tests.
231  
232 $number_of_tests is the same as C<plan()>, it's the number of tests you
233 expected to run. You can omit this, in which case the number of tests
234 you ran doesn't matter, just the fact that your tests ran to
235 conclusion.
236  
237 This is safer than and replaces the "no_plan" plan.
238  
239 B<Note:> You must never put C<done_testing()> inside an C<END { ... }> block.
240 The plan is there to ensure your test does not exit before testing has
241 completed. If you use an END block you completely bypass this protection.
242  
243 =back
244  
245 =cut
246  
247 45 ▶sub done_testing {
Subroutine done_testing: called CC=1 SCAR=0.0
Pod documented
248 45 my $tb = Test::More->builder;
249 45 $tb->done_testing(@_);
250 }
251  
252 =head2 Test names
253  
254 By convention, each test is assigned a number in order. This is
255 largely done automatically for you. However, it's often very useful to
256 assign a name to each test. Which would you rather see:
257  
258 ok 4
259 not ok 5
260 ok 6
261  
262 or
263  
264 ok 4 - basic multi-variable
265 not ok 5 - simple exponential
266 ok 6 - force == mass * acceleration
267  
268 The later gives you some idea of what failed. It also makes it easier
269 to find the test in your script, simply search for "simple
270 exponential".
271  
272 All test functions take a name argument. It's optional, but highly
273 suggested that you use it.
274  
275 =head2 I'm ok, you're not ok.
276  
277 The basic purpose of this module is to print out either "ok #" or "not
278 ok #" depending on if a given test succeeded or failed. Everything
279 else is just gravy.
280  
281 All of the following print "ok" or "not ok" depending on if the test
282 succeeded or failed. They all also return true or false,
283 respectively.
284  
285 =over 4
286  
287 =item B<ok>
288  
289 ok($got eq $expected, $test_name);
290  
291 This simply evaluates any expression (C<$got eq $expected> is just a
292 simple example) and uses that to determine if the test succeeded or
293 failed. A true expression passes, a false one fails. Very simple.
294  
295 For example:
296  
297 ok( $exp{9} == 81, 'simple exponential' );
298 ok( Film->can('db_Main'), 'set_db()' );
299 ok( $p->tests == 4, 'saw tests' );
300 ok( !grep(!defined $_, @items), 'all items defined' );
301  
302 (Mnemonic: "This is ok.")
303  
304 $test_name is a very short description of the test that will be printed
305 out. It makes it very easy to find a test in your script when it fails
306 and gives others an idea of your intentions. $test_name is optional,
307 but we B<very> strongly encourage its use.
308  
309 Should an C<ok()> fail, it will produce some diagnostics:
310  
311 not ok 18 - sufficient mucus
312 # Failed test 'sufficient mucus'
313 # in foo.t at line 42.
314  
315 This is the same as L<Test::Simple>'s C<ok()> routine.
316  
317 =cut
318  
319 459 ▶sub ok ($;$) {
Subroutine ok: called CC=1 SCAR=0.0
Pod documented
320 459 my( $test, $name ) = @_;
321 459 my $tb = Test::More->builder;
322  
323 459 return $tb->ok( $test, $name );
324 }
325  
326 =item B<is>
327  
328 =item B<isnt>
329  
330 is ( $got, $expected, $test_name );
331 isnt( $got, $expected, $test_name );
332  
333 Similar to C<ok()>, C<is()> and C<isnt()> compare their two arguments
334 with C<eq> and C<ne> respectively and use the result of that to
335 determine if the test succeeded or failed. So these:
336  
337 # Is the ultimate answer 42?
338 is( ultimate_answer(), 42, "Meaning of Life" );
339  
340 # $foo isn't empty
341 isnt( $foo, '', "Got some foo" );
342  
343 are similar to these:
344  
345 ok( ultimate_answer() eq 42, "Meaning of Life" );
346 ok( $foo ne '', "Got some foo" );
347  
348 C<undef> will only ever match C<undef>. So you can test a value
349 against C<undef> like this:
350  
351 is($not_defined, undef, "undefined as expected");
352  
353 (Mnemonic: "This is that." "This isn't that.")
354  
355 So why use these? They produce better diagnostics on failure. C<ok()>
356 cannot know what you are testing for (beyond the name), but C<is()> and
357 C<isnt()> know what the test was and why it failed. For example this
358 test:
359  
360 my $foo = 'waffle'; my $bar = 'yarblokos';
361 is( $foo, $bar, 'Is foo the same as bar?' );
362  
363 Will produce something like this:
364  
365 not ok 17 - Is foo the same as bar?
366 # Failed test 'Is foo the same as bar?'
367 # in foo.t at line 139.
368 # got: 'waffle'
369 # expected: 'yarblokos'
370  
371 So you can figure out what went wrong without rerunning the test.
372  
373 You are encouraged to use C<is()> and C<isnt()> over C<ok()> where possible,
374 however do not be tempted to use them to find out if something is
375 true or false!
376  
377 # XXX BAD!
378 is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );
379  
380 This does not check if C<exists $brooklyn{tree}> is true, it checks if
381 it returns 1. Very different. Similar caveats exist for false and 0.
382 In these cases, use C<ok()>.
383  
384 ok( exists $brooklyn{tree}, 'A tree grows in Brooklyn' );
385  
386 A simple call to C<isnt()> usually does not provide a strong test but there
387 are cases when you cannot say much more about a value than that it is
388 different from some other value:
389  
390 new_ok $obj, "Foo";
391  
392 my $clone = $obj->clone;
393 isa_ok $obj, "Foo", "Foo->clone";
394  
395 isnt $obj, $clone, "clone() produces a different object";
396  
397 Historically we supported an C<isn't()> function as an alias of
398 C<isnt()>, however in Perl 5.37.9 support for the use of apostrophe as
399 a package separator was deprecated and by Perl 5.42.0 support for it
400 will have been removed completely. Accordingly use of C<isn't()> is also
401 deprecated, and will produce warnings when used unless 'deprecated'
402 warnings are specifically disabled in the scope where it is used. You
403 are strongly advised to migrate to using C<isnt()> instead.
404  
405 =cut
406  
407 181 ▶sub is ($$;$) {
Subroutine is: called CC=1 SCAR=0.0
Pod documented
408 181 my $tb = Test::More->builder;
409  
410 181 return $tb->is_eq(@_);
411 }
412  
413 12 ▶sub isnt ($$;$) {
Subroutine isnt: called CC=1 SCAR=0.0
Pod documented
414 12 my $tb = Test::More->builder;
415  
416 12 return $tb->isnt_eq(@_);
417 }
418  
419 # Historically it was possible to use apostrophes as a package
420 # separator. make this available as isn't() for perl's that support it.
421 # However in 5.37.9 the apostrophe as a package separator was
422 # deprecated, so warn users of isn't() that they should use isnt()
423 # instead. We assume that if they are calling isn::t() they are doing so
424 # via isn't() as we have no way to be sure that they aren't spelling it
425 # with a double colon. We only trigger the warning if deprecation
426 # warnings are enabled, so the user can silence the warning if they
427 # wish.
428 3 ▶sub isn::t {
Subroutine t: called CC=2 SCAR=6.9
429 3 local ($@, $!, $?);
430 3 ▶ if (warnings::enabled("deprecated")) {
Branch: 1 branch
BranchTrueFalseTotal
if (warnings::enabled("deprecated")) 3 1 4
431 2 _carp
432 "Use of apostrophe as package separator was deprecated in Perl 5.37.9,\n",
433 "and will be removed in Perl 5.42.0. You should change code that uses\n",
434 "Test::More::isn't() to use Test::More::isnt() as a replacement";
435 }
436 3 goto &isnt;
437 }
438  
439 =item B<like>
440  
441 like( $got, qr/expected/, $test_name );
442  
443 Similar to C<ok()>, C<like()> matches $got against the regex C<qr/expected/>.
444  
445 So this:
446  
447 like($got, qr/expected/, 'this is like that');
448  
449 is similar to:
450  
451 ok( $got =~ m/expected/, 'this is like that');
452  
453 (Mnemonic "This is like that".)
454  
455 The second argument is a regular expression. It may be given as a
456 regex reference (i.e. C<qr//>) or (for better compatibility with older
457 perls) as a string that looks like a regex (alternative delimiters are
458 currently not supported):
459  
460 like( $got, '/expected/', 'this is like that' );
461  
462 Regex options may be placed on the end (C<'/expected/i'>).
463  
464 Its advantages over C<ok()> are similar to that of C<is()> and C<isnt()>. Better
465 diagnostics on failure.
466  
467 =cut
468  
469 22 ▶sub like ($$;$) {
Subroutine like: called CC=1 SCAR=0.0
Pod documented
470 22 my $tb = Test::More->builder;
471  
472 22 return $tb->like(@_);
473 }
474  
475 =item B<unlike>
476  
477 unlike( $got, qr/expected/, $test_name );
478  
479 Works exactly as C<like()>, only it checks if $got B<does not> match the
480 given pattern.
481  
482 =cut
483  
484 5 ▶sub unlike ($$;$) {
Subroutine unlike: called CC=1 SCAR=0.0
Pod documented
485 5 my $tb = Test::More->builder;
486  
487 5 return $tb->unlike(@_);
488 }
489  
490 =item B<cmp_ok>
491  
492 cmp_ok( $got, $op, $expected, $test_name );
493  
494 Halfway between C<ok()> and C<is()> lies C<cmp_ok()>. This allows you
495 to compare two arguments using any binary perl operator. The test
496 passes if the comparison is true and fails otherwise.
497  
498 # ok( $got eq $expected );
499 cmp_ok( $got, 'eq', $expected, 'this eq that' );
500  
501 # ok( $got == $expected );
502 cmp_ok( $got, '==', $expected, 'this == that' );
503  
504 # ok( $got && $expected );
505 cmp_ok( $got, '&&', $expected, 'this && that' );
506 ...etc...
507  
508 Its advantage over C<ok()> is when the test fails you'll know what $got
509 and $expected were:
510  
511 not ok 1
512 # Failed test in foo.t at line 12.
513 # '23'
514 # &&
515 # undef
516  
517 It's also useful in those cases where you are comparing numbers and
518 C<is()>'s use of C<eq> will interfere:
519  
520 cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
521  
522 It's especially useful when comparing greater-than or smaller-than
523 relation between values:
524  
525 cmp_ok( $some_value, '<=', $upper_limit );
526  
527  
528 =cut
529  
530 36 ▶sub cmp_ok($$$;$) {
Subroutine cmp_ok: called CC=1 SCAR=0.0
Pod documented
531 36 my $tb = Test::More->builder;
532  
533 36 return $tb->cmp_ok(@_);
534 }
535  
536 =item B<can_ok>
537  
538 can_ok($module, @methods);
539 can_ok($object, @methods);
540  
541 Checks to make sure the $module or $object can do these @methods
542 (works with functions, too).
543  
544 can_ok('Foo', qw(this that whatever));
545  
546 is almost exactly like saying:
547  
548 ok( Foo->can('this') &&
549 Foo->can('that') &&
550 Foo->can('whatever')
551 );
552  
553 only without all the typing and with a better interface. Handy for
554 quickly testing an interface.
555  
556 No matter how many @methods you check, a single C<can_ok()> call counts
557 as one test. If you desire otherwise, use:
558  
559 foreach my $meth (@methods) {
560 can_ok('Foo', $meth);
561 }
562  
563 =cut
564  
565 13 ▶sub can_ok ($@) {
Subroutine can_ok: called CC=7 SCAR=19.5
Pod documented
566 13 my( $proto, @methods ) = @_;
567 13 ▶ my $class = ref $proto || $proto;
Condition100%3/3
ref $proto || $proto
l!l&&r!l&&!r
571
MC/DC100%2/2
ref $proto || $proto
ref $proto $proto
Truth table100%3/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
568 13 my $tb = Test::More->builder;
569  
570 13 ▶ unless($class) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($class) 2 12 14
571 1 my $ok = $tb->ok( 0, "->can(...)" );
572 1 $tb->diag(' can_ok() called with empty class or reference');
573 1 return $ok;
574 }
575  
576 12 ▶ unless(@methods) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@methods) 2 11 13
577 1 my $ok = $tb->ok( 0, "$class->can(...)" );
578 1 $tb->diag(' can_ok() called with no methods');
579 1 return $ok;
580 }
581  
582 11 my @nok;
583 11 foreach my $method (@methods) {
584 41 ▶ $tb->_try( sub { $proto->can($method) } ) or push @nok, $method;
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
$tb->_try(sub { $proto->can($method); } ) or push @nok, $method 37 4 41
585 }
586  
587 11 ▶ my $name = (@methods == 1) ? "$class->can('$methods[0]')" :
Branch: 1 branch
BranchTrueFalseTotal
@methods == 1 ? : 6 5 11
588 "$class->can(...)" ;
589  
590 11 my $ok = $tb->ok( !@nok, $name );
591  
592 11 $tb->diag( map " $class->can('$_') failed\n", @nok );
593  
594 11 return $ok;
595 }
596  
597 =item B<isa_ok>
598  
599 isa_ok($object, $class, $object_name);
600 isa_ok($subclass, $class, $object_name);
601 isa_ok($ref, $type, $ref_name);
602  
603 Checks to see if the given C<< $object->isa($class) >>. Also checks to make
604 sure the object was defined in the first place. Handy for this sort
605 of thing:
606  
607 my $obj = Some::Module->new;
608 isa_ok( $obj, 'Some::Module' );
609  
610 where you'd otherwise have to write
611  
612 my $obj = Some::Module->new;
613 ok( defined $obj && $obj->isa('Some::Module') );
614  
615 to safeguard against your test script blowing up.
616  
617 You can also test a class, to make sure that it has the right ancestor:
618  
619 isa_ok( 'Vole', 'Rodent' );
620  
621 It works on references, too:
622  
623 isa_ok( $array_ref, 'ARRAY' );
624  
625 The diagnostics of this test normally just refer to 'the object'. If
626 you'd like them to be more specific, you can supply an $object_name
627 (for example 'Test customer').
628  
629 =cut
630  
631 33 ▶sub isa_ok ($$;$) {
Subroutine isa_ok: called CC=14 SCAR=26.4
Pod documented
632 33 my( $thing, $class, $thing_name ) = @_;
633 33 my $tb = Test::More->builder;
634  
635 33 my $whatami;
636 33 ▶ if( !defined $thing ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $thing) { } 2 31 33
elsif (ref $thing) { } 27 4 31
637 2 $whatami = 'undef';
638 }
639 elsif( ref $thing ) {
640 27 $whatami = 'reference';
641  
642 27 local($@,$!);
643 27 require Scalar::Util;
644 27 ▶ if( Scalar::Util::blessed($thing) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($thing)) 23 4 27
645 23 $whatami = 'object';
646 }
647 }
648 else {
649 4 $whatami = 'class';
650 }
651  
652 # We can't use UNIVERSAL::isa because we want to honor isa() overrides
653 33 ▶ my( $rslt, $error ) = $tb->_try( sub { $thing->isa($class) } );
Subroutine __ANON__: called CC=1 SCAR=0.0
654  
655 33 ▶ if($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 6 27 33
656 6 ▶ die <<WHOA unless $error =~ /^Can't (locate|call) method "isa"/;
Branch: 1 branch
BranchTrueFalseTotal
unless $error =~ /^Can't (locate|call) method "isa"/ 0 6 6
657 WHOA! I tried to call ->isa on your $whatami and got some weird error.
658 Here's the error.
659 $error
660 WHOA
661 }
662  
663 # Special case for isa_ok( [], "ARRAY" ) and like
664 33 ▶ if( $whatami eq 'reference' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($whatami eq "reference") 4 29 33
665 4 $rslt = UNIVERSAL::isa($thing, $class);
666 }
667  
668 33 my($diag, $name);
669 33 ▶ if( defined $thing_name ) {
Branch: 5 branches
BranchTrueFalseTotal
if (defined $thing_name) { } 4 29 33
elsif ($whatami eq 'object') { } 21 8 29
elsif ($whatami eq 'reference') { } 4 4 8
elsif ($whatami eq 'undef') { } 1 3 4
elsif ($whatami eq 'class') { } 3 0 3
670 4 $name = "'$thing_name' isa '$class'";
671 4 ▶ $diag = defined $thing ? "'$thing_name' isn't a '$class'" : "'$thing_name' isn't defined";
Branch: 1 branch
BranchTrueFalseTotal
defined $thing ? : 3 1 4
672 }
673 elsif( $whatami eq 'object' ) {
674 21 my $my_class = ref $thing;
675 21 $thing_name = qq[An object of class '$my_class'];
676 21 $name = "$thing_name isa '$class'";
677 21 $diag = "The object of class '$my_class' isn't a '$class'";
678 }
679 elsif( $whatami eq 'reference' ) {
680 4 my $type = ref $thing;
681 4 $thing_name = qq[A reference of type '$type'];
682 4 $name = "$thing_name isa '$class'";
683 4 $diag = "The reference of type '$type' isn't a '$class'";
684 }
685 elsif( $whatami eq 'undef' ) {
686 1 $thing_name = 'undef';
687 1 $name = "$thing_name isa '$class'";
688 1 $diag = "$thing_name isn't defined";
689 }
690 elsif( $whatami eq 'class' ) {
691 3 $thing_name = qq[The class (or class-like) '$thing'];
692 3 $name = "$thing_name isa '$class'";
693 3 $diag = "$thing_name isn't a '$class'";
694 }
695 else {
696 0 die;
697 }
698  
699 33 my $ok;
700 33 ▶ if($rslt) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rslt) { } 23 10 33
701 23 $ok = $tb->ok( 1, $name );
702 }
703 else {
704 10 $ok = $tb->ok( 0, $name );
705 10 $tb->diag(" $diag\n");
706 }
707  
708 33 return $ok;
709 }
710  
711 =item B<new_ok>
712  
713 my $obj = new_ok( $class );
714 my $obj = new_ok( $class => \@args );
715 my $obj = new_ok( $class => \@args, $object_name );
716  
717 A convenience function which combines creating an object and calling
718 C<isa_ok()> on that object.
719  
720 It is basically equivalent to:
721  
722 my $obj = $class->new(@args);
723 isa_ok $obj, $class, $object_name;
724  
725 If @args is not given, an empty list will be used.
726  
727 This function only works on C<new()> and it assumes C<new()> will return
728 just a single object which isa C<$class>.
729  
730 =cut
731  
732 11 ▶sub new_ok {
Subroutine new_ok: called CC=5 SCAR=16.1
Pod documented
733 11 my $tb = Test::More->builder;
734 11 ▶ $tb->croak("new_ok() must be given at least a class") unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 1 10 11
735  
736 10 my( $class, $args, $object_name ) = @_;
737  
738 10 ▶ $args ||= [];
Condition100%2/2
$args ||= []
l!l
37
MC/DC100%1/1
$args ||= []
$args
Truth table100%2/2
A
A= $args
Aresult
11
00
739  
740 10 my $obj;
741 10 ▶ my( $success, $error ) = $tb->_try( sub { $obj = $class->new(@$args); 1 } );
Subroutine __ANON__: called CC=1 SCAR=0.0
742 10 ▶ if($success) {
Branch: 1 branch
BranchTrueFalseTotal
if ($success) { } 8 2 10
743 8 local $Test::Builder::Level = $Test::Builder::Level + 1;
744 8 isa_ok $obj, $class, $object_name;
745 }
746 else {
747 2 ▶ $class = 'undef' if !defined $class;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $class 1 1 2
748 2 $tb->ok( 0, "$class->new() died" );
749 2 $tb->diag(" Error was: $error");
750 }
751  
752 10 return $obj;
753 }
754  
755 =item B<subtest>
756  
757 subtest $name => \&code, @args;
758  
759 C<subtest()> runs the &code as its own little test with its own plan and
760 its own result. The main test counts this as a single test using the
761 result of the whole subtest to determine if its ok or not ok.
762  
763 For example...
764  
765 use Test::More tests => 3;
766
767 pass("First test");
768  
769 subtest 'An example subtest' => sub {
770 plan tests => 2;
771  
772 pass("This is a subtest");
773 pass("So is this");
774 };
775  
776 pass("Third test");
777  
778 This would produce.
779  
780 1..3
781 ok 1 - First test
782 # Subtest: An example subtest
783 1..2
784 ok 1 - This is a subtest
785 ok 2 - So is this
786 ok 2 - An example subtest
787 ok 3 - Third test
788  
789 A subtest may call C<skip_all>. No tests will be run, but the subtest is
790 considered a skip.
791  
792 subtest 'skippy' => sub {
793 plan skip_all => 'cuz I said so';
794 pass('this test will never be run');
795 };
796  
797 Returns true if the subtest passed, false otherwise.
798  
799 If the code dies, the subtest fails and the exception is reported inside it.
800 The exception is then rethrown, so it still reaches your test file and ends it
801 the way any other uncaught exception would.
802  
803 Due to how subtests work, you may omit a plan if you desire. This adds an
804 implicit C<done_testing()> to the end of your subtest. The following two
805 subtests are equivalent:
806  
807 subtest 'subtest with implicit done_testing()', sub {
808 ok 1, 'subtests with an implicit done testing should work';
809 ok 1, '... and support more than one test';
810 ok 1, '... no matter how many tests are run';
811 };
812  
813 subtest 'subtest with explicit done_testing()', sub {
814 ok 1, 'subtests with an explicit done testing should work';
815 ok 1, '... and support more than one test';
816 ok 1, '... no matter how many tests are run';
817 done_testing();
818 };
819  
820 Extra arguments given to C<subtest> are passed to the callback. For example:
821  
822 sub my_subtest {
823 my $range = shift;
824 ...
825 }
826  
827 for my $range (1, 10, 100, 1000) {
828 subtest "testing range $range", \&my_subtest, $range;
829 }
830  
831 =cut
832  
833 42 ▶sub subtest {
Subroutine subtest: called CC=1 SCAR=0.0
Pod documented
834 42 my $tb = Test::More->builder;
835 42 return $tb->subtest(@_);
836 }
837  
838 =item B<pass>
839  
840 =item B<fail>
841  
842 pass($test_name);
843 fail($test_name);
844  
845 Sometimes you just want to say that the tests have passed. Usually
846 the case is you've got some complicated condition that is difficult to
847 wedge into an C<ok()>. In this case, you can simply use C<pass()> (to
848 declare the test ok) or fail (for not ok). They are synonyms for
849 C<ok(1)> and C<ok(0)>.
850  
851 Use these very, very, very sparingly.
852  
853 =cut
854  
855 45 ▶sub pass (;$) {
Subroutine pass: called CC=1 SCAR=0.0
Pod documented
856 45 my $tb = Test::More->builder;
857  
858 45 return $tb->ok( 1, @_ );
859 }
860  
861 33 ▶sub fail (;$) {
Subroutine fail: called CC=1 SCAR=0.0
Pod documented
862 33 my $tb = Test::More->builder;
863  
864 33 return $tb->ok( 0, @_ );
865 }
866  
867 =back
868  
869  
870 =head2 Module tests
871  
872 Sometimes you want to test if a module, or a list of modules, can
873 successfully load. For example, you'll often want a first test which
874 simply loads all the modules in the distribution to make sure they
875 work before going on to do more complicated testing.
876  
877 For such purposes we have C<use_ok> and C<require_ok>.
878  
879 =over 4
880  
881 =item B<require_ok>
882  
883 require_ok($module);
884 require_ok($file);
885  
886 Tries to C<require> the given $module or $file. If it loads
887 successfully, the test will pass. Otherwise it fails and displays the
888 load error.
889  
890 C<require_ok> will guess whether the input is a module name or a
891 filename.
892  
893 No exception will be thrown if the load fails.
894  
895 # require Some::Module
896 require_ok "Some::Module";
897  
898 # require "Some/File.pl";
899 require_ok "Some/File.pl";
900  
901 # stop testing if any of your modules will not load
902 for my $module (@module) {
903 require_ok $module or BAIL_OUT "Can't load $module";
904 }
905  
906 =cut
907  
908 9 ▶sub require_ok ($) {
Subroutine require_ok: called CC=3 SCAR=11.0
Pod documented
909 9 my($module) = shift;
910 9 my $tb = Test::More->builder;
911  
912 9 my $pack = caller;
913  
914 # Try to determine if we've been given a module name or file.
915 # Module names must be barewords, files not.
916 9 ▶ $module = qq['$module'] unless _is_module_name($module);
Branch: 1 branch
BranchTrueFalseTotal
unless _is_module_name($module) 1 8 9
917  
918 9 my $code = <<REQUIRE;
919 package $pack;
920 require $module;
921 1;
922 REQUIRE
923  
924 9 my( $eval_result, $eval_error ) = _eval($code);
925 9 my $ok = $tb->ok( $eval_result, "require $module;" );
926  
927 9 ▶ unless($ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 2 7 9
928 2 chomp $eval_error;
929 2 $tb->diag(<<DIAGNOSTIC);
930 Tried to require '$module'.
931 Error: $eval_error
932 DIAGNOSTIC
933  
934 }
935  
936 9 return $ok;
937 }
938  
939 13 ▶sub _is_module_name {
Subroutine _is_module_name: called CC=2 SCAR=6.9
940 13 my $module = shift;
941  
942 # Module names start with a letter.
943 # End with an alphanumeric.
944 # The rest is an alphanumeric or ::
945 13 $module =~ s/\b::\b//g;
946  
947 13 ▶ return $module =~ /^[a-zA-Z]\w*$/ ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$module =~ /^[a-zA-Z]\w*$/ ? : 9 4 13
948 }
949  
950  
951 =item B<use_ok>
952  
953 BEGIN { use_ok($module); }
954 BEGIN { use_ok($module, @imports); }
955  
956 Like C<require_ok>, but it will C<use> the $module in question and
957 only loads modules, not files.
958  
959 If you just want to test a module can be loaded, use C<require_ok>.
960  
961 If you just want to load a module in a test, we recommend simply using
962 C<use> directly. It will cause the test to stop.
963  
964 It's recommended that you run C<use_ok()> inside a BEGIN block so its
965 functions are exported at compile-time and prototypes are properly
966 honored.
967  
968 If @imports are given, they are passed through to the use. So this:
969  
970 BEGIN { use_ok('Some::Module', qw(foo bar)) }
971  
972 is like doing this:
973  
974 use Some::Module qw(foo bar);
975  
976 Version numbers can be checked like so:
977  
978 # Just like "use Some::Module 1.02"
979 BEGIN { use_ok('Some::Module', 1.02) }
980  
981 Don't try to do this:
982  
983 BEGIN {
984 use_ok('Some::Module');
985  
986 ...some code that depends on the use...
987 ...happening at compile time...
988 }
989  
990 because the notion of "compile-time" is relative. Instead, you want:
991  
992 BEGIN { use_ok('Some::Module') }
993 BEGIN { ...some code that depends on the use... }
994  
995 If you want the equivalent of C<use Foo ()>, use a module but not
996 import anything, use C<require_ok>.
997  
998 BEGIN { require_ok "Foo" }
999  
1000 =cut
1001  
1002 36 ▶sub use_ok ($;@) {
Subroutine use_ok: called CC=4 SCAR=13.9
Pod documented
1003 36 my( $module, @imports ) = @_;
1004  
1005 36 my $tb = Test::More->builder;
1006  
1007 36 my %caller;
1008 36 @caller{qw/pack file line sub args want eval req strict warn/} = caller(0);
1009  
1010 36 my ($pack, $filename, $line, $warn) = @caller{qw/pack file line warn/};
1011 36 $filename =~ y/\n\r/_/; # so it doesn't run off the "#line $line $f" line
1012  
1013 36 my $code;
1014 36 ▶ if( @imports == 1 and $imports[0] =~ /^\d+(?:\.\d+)?$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@imports == 1 and $imports[0] =~ /^\d+(?:\.\d+)?$/) { } 3 33 36
Condition100%3/3
@imports == 1 and $imports[0] =~ /^\d+(?:\.\d+)?$/
!ll&&!rl&&r
3123
MC/DC100%2/2
@imports == 1 and $imports[0] =~ /^\d+(?:\.\d+)?$/
@imports == 1 $imports[0] =~ /^\d+(?:\.\d+)?$/
Truth table100%3/3
A and B
A= @imports == 1B= $imports[0] =~ /^\d+(?:\.\d+)?$/
ABresult
0X0
100
111
1015 # probably a version check. Perl needs to see the bare number
1016 # for it to work with non-Exporter based modules.
1017 3 $code = <<USE;
1018 package $pack;
1019 BEGIN { \${^WARNING_BITS} = \$args[-1] if defined \$args[-1] }
1020 #line $line $filename
1021 use $module $imports[0];
1022 1;
1023 USE
1024 }
1025 else {
1026 33 $code = <<USE;
1027 package $pack;
1028 BEGIN { \${^WARNING_BITS} = \$args[-1] if defined \$args[-1] }
1029 #line $line $filename
1030 use $module \@{\$args[0]};
1031 1;
1032 USE
1033 }
1034  
1035 36 my ($eval_result, $eval_error) = _eval($code, \@imports, $warn);
1036 36 my $ok = $tb->ok( $eval_result, "use $module;" );
1037  
1038 36 ▶ unless($ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 2 34 36
1039 2 chomp $eval_error;
1040 2 $@ =~ s{^BEGIN failed--compilation aborted at .*$}
1041 {BEGIN failed--compilation aborted at $filename line $line.}m;
1042 2 $tb->diag(<<DIAGNOSTIC);
1043 Tried to use '$module'.
1044 Error: $eval_error
1045 DIAGNOSTIC
1046  
1047 }
1048  
1049 36 return $ok;
1050 }
1051  
1052 45 ▶sub _eval {
Subroutine _eval: called CC=3 SCAR=11.0
1053 45 my( $code, @args ) = @_;
1054  
1055 # Work around oddities surrounding resetting of $@ by immediately
1056 # storing it.
1057 45 my( $sigdie, $eval_result, $eval_error );
1058 {
1059 45 local( $@, $!, $SIG{__DIE__} ); # isolate eval
1060 45 ▶ $eval_result = eval $code; ## no critic (BuiltinFunctions::ProhibitStringyEval)
Subroutine BEGIN: called CC=2 SCAR=6.9
Subroutine BEGIN: called CC=2 SCAR=6.9
Branch: 2 branches
BranchTrueFalseTotal
if defined $args[-1] 23 1 24
if defined $args[-1] 2 1 3
1061 45 $eval_error = $@;
1062 45 ▶ $sigdie = $SIG{__DIE__} || undef;
Condition100%2/2
$SIG{'__DIE__'} || undef
l!l
144
MC/DC100%1/1
$SIG{'__DIE__'} || undef
$SIG{'__DIE__'}
Truth table100%2/2
A
A= $SIG{'__DIE__'}
Aresult
11
00
1063 }
1064 # make sure that $code got a chance to set $SIG{__DIE__}
1065 45 ▶ $SIG{__DIE__} = $sigdie if defined $sigdie;
Branch: 1 branch
BranchTrueFalseTotal
if defined $sigdie 1 44 45
1066  
1067 45 return( $eval_result, $eval_error );
1068 }
1069  
1070  
1071 =back
1072  
1073  
1074 =head2 Complex data structures
1075  
1076 Not everything is a simple eq check or regex. There are times you
1077 need to see if two data structures are equivalent. For these
1078 instances Test::More provides a handful of useful functions.
1079  
1080 B<NOTE> I'm not quite sure what will happen with filehandles.
1081  
1082 =over 4
1083  
1084 =item B<is_deeply>
1085  
1086 is_deeply( $got, $expected, $test_name );
1087  
1088 Similar to C<is()>, except that if $got and $expected are references, it
1089 does a deep comparison walking each data structure to see if they are
1090 equivalent. If the two structures are different, it will display the
1091 place where they start differing.
1092  
1093 C<is_deeply()> compares the dereferenced values of references, the
1094 references themselves (except for their type) are ignored. This means
1095 aspects such as blessing and ties are not considered "different".
1096  
1097 C<is_deeply()> currently has very limited handling of function reference
1098 and globs. It merely checks if they have the same referent. This may
1099 improve in the future.
1100  
1101 L<Test::Differences> and L<Test::Deep> provide more in-depth functionality
1102 along these lines.
1103  
1104 B<NOTE> is_deeply() has limitations when it comes to comparing strings and
1105 refs:
1106  
1107 my $path = path('.');
1108 my $hash = {};
1109 is_deeply( $path, "$path" ); # ok
1110 is_deeply( $hash, "$hash" ); # fail
1111  
1112 This happens because is_deeply will unoverload all arguments unconditionally.
1113 It is probably best not to use is_deeply with overloading. For legacy reasons
1114 this is not likely to ever be fixed. If you would like a much better tool for
1115 this you should see L<Test2::Suite> Specifically L<Test2::Tools::Compare> has
1116 an C<is()> function that works like C<is_deeply> with many improvements.
1117  
1118 =cut
1119  
1120 130 our( @Data_Stack, %Refs_Seen );
1121 130 my $DNE = bless [], 'Does::Not::Exist';
1122  
1123 461 ▶sub _dne {
Subroutine _dne: called CC=1 SCAR=0.0
1124 461 return ref $_[0] eq ref $DNE;
1125 }
1126  
1127 ## no critic (Subroutines::RequireArgUnpacking)
1128 91 ▶sub is_deeply {
Subroutine is_deeply: called CC=8 SCAR=20.8
Pod documented
1129 91 my $tb = Test::More->builder;
1130  
1131 91 ▶ unless( @_ == 2 or @_ == 3 ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@_ == 2 or @_ == 3) 3 88 91
Condition100%3/3
@_ == 2 or @_ == 3
l!l&&r!l&&!r
38503
MC/DC100%2/2
@_ == 2 or @_ == 3
@_ == 2 @_ == 3
Truth table100%3/3
A or B
A= @_ == 2B= @_ == 3
ABresult
1X1
011
000
1132 3 my $msg = <<'WARNING';
1133 is_deeply() takes two or three args, you gave %d.
1134 This usually means you passed an array or hash instead
1135 of a reference to it
1136 WARNING
1137 3 chop $msg; # clip off newline so carp() will put in line/file
1138  
1139 3 _carp sprintf $msg, scalar @_;
1140  
1141 3 return $tb->ok(0);
1142 }
1143  
1144 88 my( $got, $expected, $name ) = @_;
1145  
1146 88 $tb->_unoverload_str( \$expected, \$got );
1147  
1148 88 my $ok;
1149 88 ▶ if( !ref $got and !ref $expected ) { # neither is a reference
Branch: 2 branches
BranchTrueFalseTotal
if (not ref $got || ref $expected) { } 6 82 88
elsif (not ref $got xor not ref $expected) { } 4 78 82
Condition100%3/3
ref $got || ref $expected
l!l&&r!l&&!r
8026
MC/DC100%2/2
ref $got || ref $expected
ref $got ref $expected
Truth table100%3/3
A || B
A= ref $gotB= ref $expected
ABresult
1X1
011
000
1150 6 $ok = $tb->is_eq( $got, $expected, $name );
1151 }
1152 ▶ elsif( !ref $got xor !ref $expected ) { # one's a reference, one isn't
Condition75%3/4
not ref $got xor not ref $expected
l&&rl&&!r!l&&r!l&&!r
02278
MC/DC100%2/2
not ref $got xor not ref $expected
not ref $got not ref $expected
Truth table75%3/4
not(A) xor not(B)
A= not ref $gotB= not ref $expected
ABresult
110
101
011
000
1153 4 $ok = $tb->ok( 0, $name );
1154 4 $tb->diag( _format_stack({ vals => [ $got, $expected ] }) );
1155 }
1156 else { # both references
1157 78 local @Data_Stack = ();
1158 78 ▶ if( _deep_check( $got, $expected ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (_deep_check($got, $expected)) { } 45 33 78
1159 45 $ok = $tb->ok( 1, $name );
1160 }
1161 else {
1162 33 $ok = $tb->ok( 0, $name );
1163 33 $tb->diag( _format_stack(@Data_Stack) );
1164 }
1165 }
1166  
1167 88 return $ok;
1168 }
1169  
1170 37 ▶sub _format_stack {
Subroutine _format_stack: called CC=12 SCAR=24.9
1171 37 my(@Stack) = @_;
1172  
1173 37 my $var = '$FOO';
1174 37 my $did_arrow = 0;
1175 37 foreach my $entry (@Stack) {
1176 54 ▶ my $type = $entry->{type} || '';
Condition100%2/2
$entry->{'type'} || ''
l!l
4311
MC/DC100%1/1
$entry->{'type'} || ''
$entry->{'type'}
Truth table100%2/2
A
A= $entry->{'type'}
Aresult
11
00
1177 54 my $idx = $entry->{'idx'};
1178 54 ▶ if( $type eq 'HASH' ) {
Branch: 3 branches
BranchTrueFalseTotal
if ($type eq 'HASH') { } 10 44 54
elsif ($type eq 'ARRAY') { } 17 27 44
elsif ($type eq 'REF') { } 5 22 27
1179 10 ▶ $var .= "->" unless $did_arrow++;
Branch: 1 branch
BranchTrueFalseTotal
unless $did_arrow++ 8 2 10
1180 10 $var .= "{$idx}";
1181 }
1182 elsif( $type eq 'ARRAY' ) {
1183 17 ▶ $var .= "->" unless $did_arrow++;
Branch: 1 branch
BranchTrueFalseTotal
unless $did_arrow++ 17 0 17
1184 17 $var .= "[$idx]";
1185 }
1186 elsif( $type eq 'REF' ) {
1187 5 $var = "\${$var}";
1188 }
1189 }
1190  
1191 37 my @vals = @{ $Stack[-1]{vals} }[ 0, 1 ];
1192 37 my @vars;
1193 37 ( $vars[0] = $var ) =~ s/\$FOO/ \$got/;
1194 37 ( $vars[1] = $var ) =~ s/\$FOO/\$expected/;
1195  
1196 37 my $out = "Structures begin differing at:\n";
1197 37 foreach my $idx ( 0 .. $#vals ) {
1198 74 my $val = $vals[$idx];
1199 74 ▶ $vals[$idx]
Branch: 3 branches
BranchTrueFalseTotal
!defined($val) ? : 9 65 74
_dne($val) ? : 10 55 65
ref $val ? : 24 31 55
1200 = !defined $val ? 'undef'
1201 : _dne($val) ? "Does not exist"
1202 : ref $val ? "$val"
1203 : "'$val'";
1204 }
1205  
1206 37 $out .= "$vars[0] = $vals[0]\n";
1207 37 $out .= "$vars[1] = $vals[1]\n";
1208  
1209 37 $out =~ s/^/ /msg;
1210 37 return $out;
1211 }
1212  
1213 130 my %_types = (
1214 (map +($_ => $_), qw(
1215 Regexp
1216 ARRAY
1217 HASH
1218 SCALAR
1219 REF
1220 GLOB
1221 CODE
1222 )),
1223 'LVALUE' => 'SCALAR',
1224 'REF' => 'SCALAR',
1225 'VSTRING' => 'SCALAR',
1226 );
1227  
1228 568 ▶sub _type {
Subroutine _type: called CC=4 SCAR=13.9
1229 568 my $thing = shift;
1230  
1231 568 ▶ return '' if !ref $thing;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $thing 4 564 568
1232  
1233 564 for my $type (keys %_types) {
1234 2669 ▶ return $_types{$type} if UNIVERSAL::isa( $thing, $type );
Branch: 1 branch
BranchTrueFalseTotal
if UNIVERSAL::isa($thing, $type) 564 2105 2669
1235 }
1236  
1237 0 return '';
1238 }
1239  
1240 =back
1241  
1242  
1243 =head2 Diagnostics
1244  
1245 If you pick the right test function, you'll usually get a good idea of
1246 what went wrong when it failed. But sometimes it doesn't work out
1247 that way. So here we have ways for you to write your own diagnostic
1248 messages which are safer than just C<print STDERR>.
1249  
1250 =over 4
1251  
1252 =item B<diag>
1253  
1254 diag(@diagnostic_message);
1255  
1256 Prints a diagnostic message which is guaranteed not to interfere with
1257 test output. Like C<print> @diagnostic_message is simply concatenated
1258 together.
1259  
1260 Returns false, so as to preserve failure.
1261  
1262 Handy for this sort of thing:
1263  
1264 ok( grep(/foo/, @users), "There's a foo user" ) or
1265 diag("Since there's no foo, check that /etc/bar is set up right");
1266  
1267 which would produce:
1268  
1269 not ok 42 - There's a foo user
1270 # Failed test 'There's a foo user'
1271 # in foo.t at line 52.
1272 # Since there's no foo, check that /etc/bar is set up right.
1273  
1274 You might remember C<ok() or diag()> with the mnemonic C<open() or
1275 die()>.
1276  
1277 B<NOTE> The exact formatting of the diagnostic output is still
1278 changing, but it is guaranteed that whatever you throw at it won't
1279 interfere with the test.
1280  
1281 =item B<note>
1282  
1283 note(@diagnostic_message);
1284  
1285 Like C<diag()>, except the message will not be seen when the test is run
1286 in a harness. It will only be visible in the verbose TAP stream.
1287  
1288 Handy for putting in notes which might be useful for debugging, but
1289 don't indicate a problem.
1290  
1291 note("Tempfile is $tempfile");
1292  
1293 =cut
1294  
1295 5 ▶sub diag {
Subroutine diag: called CC=1 SCAR=0.0
Pod documented
1296 5 return Test::More->builder->diag(@_);
1297 }
1298  
1299 11 ▶sub note {
Subroutine note: called CC=1 SCAR=0.0
Pod documented
1300 11 return Test::More->builder->note(@_);
1301 }
1302  
1303 =item B<explain>
1304  
1305 my @dump = explain @diagnostic_message;
1306  
1307 Will dump the contents of any references in a human readable format.
1308 Usually you want to pass this into C<note> or C<diag>.
1309  
1310 Handy for things like...
1311  
1312 is_deeply($have, $want) || diag explain $have;
1313  
1314 or
1315  
1316 note explain \%args;
1317 Some::Class->method(%args);
1318  
1319 =cut
1320  
1321 5 ▶sub explain {
Subroutine explain: called CC=1 SCAR=0.0
Pod documented
1322 5 return Test::More->builder->explain(@_);
1323 }
1324  
1325 =back
1326  
1327  
1328 =head2 Conditional tests
1329  
1330 Sometimes running a test under certain conditions will cause the
1331 test script to die. A certain function or method isn't implemented
1332 (such as C<fork()> on MacOS), some resource isn't available (like a
1333 net connection) or a module isn't available. In these cases it's
1334 necessary to skip tests, or declare that they are supposed to fail
1335 but will work in the future (a todo test).
1336  
1337 For more details on the mechanics of skip and todo tests see
1338 L<Test::Harness>.
1339  
1340 The way Test::More handles this is with a named block. Basically, a
1341 block of tests which can be skipped over or made todo. It's best if I
1342 just show you...
1343  
1344 =over 4
1345  
1346 =item B<SKIP: BLOCK>
1347  
1348 SKIP: {
1349 skip $why, $how_many if $condition;
1350  
1351 ...normal testing code goes here...
1352 }
1353  
1354 This declares a block of tests that might be skipped, $how_many tests
1355 there are, $why and under what $condition to skip them. An example is
1356 the easiest way to illustrate:
1357  
1358 SKIP: {
1359 eval { require HTML::Lint };
1360  
1361 skip "HTML::Lint not installed", 2 if $@;
1362  
1363 my $lint = new HTML::Lint;
1364 isa_ok( $lint, "HTML::Lint" );
1365  
1366 $lint->parse( $html );
1367 is( $lint->errors, 0, "No errors found in HTML" );
1368 }
1369  
1370 If the user does not have HTML::Lint installed, the whole block of
1371 code I<won't be run at all>. Test::More will output special ok's
1372 which Test::Harness interprets as skipped, but passing, tests.
1373  
1374 It's important that $how_many accurately reflects the number of tests
1375 in the SKIP block so the # of tests run will match up with your plan.
1376 If your plan is C<no_plan> $how_many is optional and will default to 1.
1377  
1378 It's perfectly safe to nest SKIP blocks. Each SKIP block must have
1379 the label C<SKIP>, or Test::More can't work its magic.
1380  
1381 You don't skip tests which are failing because there's a bug in your
1382 program, or for which you don't yet have code written. For that you
1383 use TODO. Read on.
1384  
1385 =cut
1386  
1387 ## no critic (Subroutines::RequireFinalReturn)
1388 10 ▶sub skip {
Subroutine skip: called CC=7 SCAR=19.5
Pod undocumented
1389 10 my( $why, $how_many ) = @_;
1390 10 my $tb = Test::More->builder;
1391  
1392 # If the plan is set, and is static, then skip needs a count. If the plan
1393 # is 'no_plan' we are fine. As well if plan is undefined then we are
1394 # waiting for done_testing.
1395 10 ▶ unless (defined $how_many) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $how_many) 5 5 10
1396 5 my $plan = $tb->has_plan;
1397 5 ▶ _carp "skip() needs to know \$how_many tests are in the block"
Branch: 1 branch
BranchTrueFalseTotal
if $plan and $plan =~ /^\d+$/ 2 3 5
Condition100%3/3
$plan and $plan =~ /^\d+$/
!ll&&!rl&&r
122
MC/DC100%2/2
$plan and $plan =~ /^\d+$/
$plan $plan =~ /^\d+$/
Truth table100%3/3
A and B
A= $planB= $plan =~ /^\d+$/
ABresult
0X0
100
111
1398 if $plan && $plan =~ m/^\d+$/;
1399 5 $how_many = 1;
1400 }
1401  
1402 10 ▶ if( defined $how_many and $how_many =~ /\D/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $how_many and $how_many =~ /\D/) 1 9 10
Condition66%2/3
defined $how_many and $how_many =~ /\D/
!ll&&!rl&&r
091
MC/DC50%1/2
defined $how_many and $how_many =~ /\D/
defined $how_many $how_many =~ /\D/
Truth table66%2/3
A and B
A= defined $how_manyB= $how_many =~ /\D/
ABresult
0X0
100
111
1403 1 _carp
1404 "skip() was passed a non-numeric number of tests. Did you get the arguments backwards?";
1405 1 $how_many = 1;
1406 }
1407  
1408 10 for( 1 .. $how_many ) {
1409 13 $tb->skip($why);
1410 }
1411  
1412 130 ▶ no warnings 'exiting';
Subroutine BEGIN: called CC=1 SCAR=0.0
1413 10 last SKIP;
1414 }
1415  
1416 =item B<TODO: BLOCK>
1417  
1418 TODO: {
1419 local $TODO = $why if $condition;
1420  
1421 ...normal testing code goes here...
1422 }
1423  
1424 Declares a block of tests you expect to fail and $why. Perhaps it's
1425 because you haven't fixed a bug or haven't finished a new feature:
1426  
1427 TODO: {
1428 local $TODO = "URI::Geller not finished";
1429  
1430 my $card = "Eight of clubs";
1431 is( URI::Geller->your_card, $card, 'Is THIS your card?' );
1432  
1433 my $spoon;
1434 URI::Geller->bend_spoon;
1435 is( $spoon, 'bent', "Spoon bending, that's original" );
1436 }
1437  
1438 With a todo block, the tests inside are expected to fail. Test::More
1439 will run the tests normally, but print out special flags indicating
1440 they are "todo". L<Test::Harness> will interpret failures as being ok.
1441 Should anything succeed, it will report it as an unexpected success.
1442 You then know the thing you had todo is done and can remove the
1443 TODO flag.
1444  
1445 The nice part about todo tests, as opposed to simply commenting out a
1446 block of tests, is that it is like having a programmatic todo list. You know
1447 how much work is left to be done, you're aware of what bugs there are,
1448 and you'll know immediately when they're fixed.
1449  
1450 Once a todo test starts succeeding, simply move it outside the block.
1451 When the block is empty, delete it.
1452  
1453 Note that, if you leave $TODO unset or undef, Test::More reports failures
1454 as normal. This can be useful to mark the tests as expected to fail only
1455 in certain conditions, e.g.:
1456  
1457 TODO: {
1458 local $TODO = "$^O doesn't work yet. :(" if !_os_is_supported($^O);
1459  
1460 ...
1461 }
1462  
1463 =item B<todo_skip>
1464  
1465 TODO: {
1466 todo_skip $why, $how_many if $condition;
1467  
1468 ...normal testing code...
1469 }
1470  
1471 With todo tests, it's best to have the tests actually run. That way
1472 you'll know when they start passing. Sometimes this isn't possible.
1473 Often a failing test will cause the whole program to die or hang, even
1474 inside an C<eval BLOCK> with and using C<alarm>. In these extreme
1475 cases you have no choice but to skip over the broken tests entirely.
1476  
1477 The syntax and behavior is similar to a C<SKIP: BLOCK> except the
1478 tests will be marked as failing but todo. L<Test::Harness> will
1479 interpret them as passing.
1480  
1481 =cut
1482  
1483 3 ▶sub todo_skip {
Subroutine todo_skip: called CC=4 SCAR=13.9
Pod documented
1484 3 my( $why, $how_many ) = @_;
1485 3 my $tb = Test::More->builder;
1486  
1487 3 ▶ unless( defined $how_many ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $how_many) 2 1 3
1488 # $how_many can only be avoided when no_plan is in use.
1489 2 ▶ _carp "todo_skip() needs to know \$how_many tests are in the block"
Branch: 1 branch
BranchTrueFalseTotal
unless $tb->has_plan eq "no_plan" 1 1 2
1490 unless $tb->has_plan eq 'no_plan';
1491 2 $how_many = 1;
1492 }
1493  
1494 3 for( 1 .. $how_many ) {
1495 4 $tb->todo_skip($why);
1496 }
1497  
1498 130 ▶ no warnings 'exiting';
Subroutine BEGIN: called CC=1 SCAR=0.0
1499 3 last TODO;
1500 }
1501  
1502 =item When do I use SKIP vs. TODO?
1503  
1504 B<If it's something the user might not be able to do>, use SKIP.
1505 This includes optional modules that aren't installed, running under
1506 an OS that doesn't have some feature (like C<fork()> or symlinks), or maybe
1507 you need an Internet connection and one isn't available.
1508  
1509 B<If it's something the programmer hasn't done yet>, use TODO. This
1510 is for any code you haven't written yet, or bugs you have yet to fix,
1511 but want to put tests in your testing script (always a good idea).
1512  
1513  
1514 =back
1515  
1516  
1517 =head2 Test control
1518  
1519 =over 4
1520  
1521 =item B<BAIL_OUT>
1522  
1523 BAIL_OUT($reason);
1524  
1525 Indicates to the harness that things are going so badly all testing
1526 should terminate. This includes the running of any additional test scripts.
1527  
1528 This is typically used when testing cannot continue such as a critical
1529 module failing to compile or a necessary external utility not being
1530 available such as a database connection failing.
1531  
1532 The test will exit with 255.
1533  
1534 For even better control look at L<Test::Most>.
1535  
1536 =cut
1537  
1538 2 ▶sub BAIL_OUT {
Subroutine BAIL_OUT: called CC=1 SCAR=0.0
Pod documented
1539 2 my $reason = shift;
1540 2 my $tb = Test::More->builder;
1541  
1542 2 $tb->BAIL_OUT($reason);
1543 }
1544  
1545 =back
1546  
1547  
1548 =head2 Discouraged comparison functions
1549  
1550 The use of the following functions is discouraged as they are not
1551 actually testing functions and produce no diagnostics to help figure
1552 out what went wrong. They were written before C<is_deeply()> existed
1553 because I couldn't figure out how to display a useful diff of two
1554 arbitrary data structures.
1555  
1556 These functions are usually used inside an C<ok()>.
1557  
1558 ok( eq_array(\@got, \@expected) );
1559  
1560 C<is_deeply()> can do that better and with diagnostics.
1561  
1562 is_deeply( \@got, \@expected );
1563  
1564 They may be deprecated in future versions.
1565  
1566 =over 4
1567  
1568 =item B<eq_array>
1569  
1570 my $is_eq = eq_array(\@got, \@expected);
1571  
1572 Checks if two arrays are equivalent. This is a deep check, so
1573 multi-level structures are handled correctly.
1574  
1575 =cut
1576  
1577 #'#
1578 16 ▶sub eq_array {
Subroutine eq_array: called CC=1 SCAR=0.0
Pod documented
1579 16 local @Data_Stack = ();
1580 16 _deep_check(@_);
1581 }
1582  
1583 74 ▶sub _eq_array {
Subroutine _eq_array: called CC=10 SCAR=23.2
1584 74 my( $a1, $a2 ) = @_;
1585  
1586 74 ▶ if( grep _type($_) ne 'ARRAY', $a1, $a2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep((_type($_) ne "ARRAY"), $a1, $a2)) 0 74 74
1587 0 warn "eq_array passed a non-array ref";
1588 0 return 0;
1589 }
1590  
1591 74 ▶ return 1 if $a1 eq $a2;
Branch: 1 branch
BranchTrueFalseTotal
if $a1 eq $a2 0 74 74
1592  
1593 74 my $ok = 1;
1594 74 ▶ my $max = $#$a1 > $#$a2 ? $#$a1 : $#$a2;
Branch: 1 branch
BranchTrueFalseTotal
$a1->$#* > $a2->$#* ? : 4 70 74
1595 74 for( 0 .. $max ) {
1596 166 ▶ my $e1 = $_ > $#$a1 ? $DNE : $a1->[$_];
Branch: 1 branch
BranchTrueFalseTotal
$_ > $a1->$#* ? : 2 164 166
1597 166 ▶ my $e2 = $_ > $#$a2 ? $DNE : $a2->[$_];
Branch: 1 branch
BranchTrueFalseTotal
$_ > $a2->$#* ? : 4 162 166
1598  
1599 166 ▶ next if _equal_nonrefs($e1, $e2);
Branch: 1 branch
BranchTrueFalseTotal
if _equal_nonrefs($e1, $e2) 100 66 166
1600  
1601 66 push @Data_Stack, { type => 'ARRAY', idx => $_, vals => [ $e1, $e2 ] };
1602 66 $ok = _deep_check( $e1, $e2 );
1603 66 ▶ pop @Data_Stack if $ok;
Branch: 1 branch
BranchTrueFalseTotal
if $ok 43 23 66
1604  
1605 66 ▶ last unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 23 43 66
1606 }
1607  
1608 74 return $ok;
1609 }
1610  
1611 274 ▶sub _equal_nonrefs {
Subroutine _equal_nonrefs: called CC=7 SCAR=19.5
1612 274 my( $e1, $e2 ) = @_;
1613  
1614 274 ▶ return if ref $e1 or ref $e2;
Branch: 1 branch
BranchTrueFalseTotal
if ref $e1 or ref $e2 77 197 274
Condition100%3/3
ref $e1 or ref $e2
l!l&&r!l&&!r
716197
MC/DC100%2/2
ref $e1 or ref $e2
ref $e1 ref $e2
Truth table100%3/3
A or B
A= ref $e1B= ref $e2
ABresult
1X1
011
000
1615  
1616 197 ▶ if ( defined $e1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $e1) { } 183 14 197
1617 183 ▶ return 1 if defined $e2 and $e1 eq $e2;
Branch: 1 branch
BranchTrueFalseTotal
if defined $e2 and $e1 eq $e2 171 12 183
Condition100%3/3
defined $e2 and $e1 eq $e2
!ll&&!rl&&r
48171
MC/DC100%2/2
defined $e2 and $e1 eq $e2
defined $e2 $e1 eq $e2
Truth table100%3/3
A and B
A= defined $e2B= $e1 eq $e2
ABresult
0X0
100
111
1618 }
1619 else {
1620 14 ▶ return 1 if !defined $e2;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $e2 11 3 14
1621 }
1622  
1623 15 return;
1624 }
1625  
1626 208 ▶sub _deep_check {
Subroutine _deep_check: called CC=22 SCAR=31.8
1627 208 my( $e1, $e2 ) = @_;
1628 208 my $tb = Test::More->builder;
1629  
1630 208 my $ok = 0;
1631  
1632 # Effectively turn %Refs_Seen into a stack. This avoids picking up
1633 # the same referenced used twice (such as [\$a, \$a]) to be considered
1634 # circular.
1635 208 local %Refs_Seen = %Refs_Seen;
1636  
1637 {
1638 208 $tb->_unoverload_str( \$e1, \$e2 );
1639  
1640 # Either they're both references or both not.
1641 208 ▶ my $same_ref = !( !ref $e1 xor !ref $e2 );
Condition100%4/4
!ref($e1) ^^ !ref($e2)
l&&rl&&!r!l&&r!l&&!r
2566171
MC/DC100%2/2
!ref($e1) ^^ !ref($e2)
!ref($e1) !ref($e2)
Truth table100%4/4
not(A) ^^ not(B)
A= !ref($e1)B= !ref($e2)
ABresult
110
101
011
000
1642 208 ▶ my $not_ref = ( !ref $e1 and !ref $e2 );
Condition100%3/3
ref $e1 || ref $e2
l!l&&r!l&&!r
177625
MC/DC100%2/2
ref $e1 || ref $e2
ref $e1 ref $e2
Truth table100%3/3
A || B
A= ref $e1B= ref $e2
ABresult
1X1
011
000
1643  
1644 208 ▶ if( defined $e1 xor defined $e2 ) {
Branch: 5 branches
BranchTrueFalseTotal
if (defined $e1 xor defined $e2) { } 10 198 208
elsif (not defined $e1 || defined $e2) { } 0 198 198
elsif (_dne($e1) xor _dne($e2)) { } 7 191 198
elsif ($same_ref and $e1 eq $e2) { } 17 174 191
elsif ($not_ref) { } 12 162 174
Condition75%3/4
defined $e1 xor defined $e2
l&&rl&&!r!l&&r!l&&!r
198460
MC/DC100%2/2
defined $e1 xor defined $e2
defined $e1 defined $e2
Truth table75%3/4
A xor B
A= defined $e1B= defined $e2
ABresult
110
101
011
000
1645 10 $ok = 0;
1646 }
1647 ▶ elsif( !defined $e1 and !defined $e2 ) {
Condition33%1/3
defined $e1 || defined $e2
l!l&&r!l&&!r
19800
MC/DC0%0/2
defined $e1 || defined $e2
defined $e1 defined $e2
Truth table33%1/3
A || B
A= defined $e1B= defined $e2
ABresult
1X1
011
000
1648 # Shortcut if they're both undefined.
1649 0 $ok = 1;
1650 }
1651 ▶ elsif( _dne($e1) xor _dne($e2) ) {
Condition75%3/4
_dne($e1) xor _dne($e2)
l&&rl&&!r!l&&r!l&&!r
052191
MC/DC100%2/2
_dne($e1) xor _dne($e2)
_dne($e1) _dne($e2)
Truth table75%3/4
A xor B
A= _dne($e1)B= _dne($e2)
ABresult
110
101
011
000
1652 7 $ok = 0;
1653 }
1654 ▶ elsif( $same_ref and( $e1 eq $e2 ) ) {
Condition100%3/3
$same_ref and $e1 eq $e2
!ll&&!rl&&r
417017
MC/DC100%2/2
$same_ref and $e1 eq $e2
$same_ref $e1 eq $e2
Truth table100%3/3
A and B
A= $same_refB= $e1 eq $e2
ABresult
0X0
100
111
1655 17 $ok = 1;
1656 }
1657 elsif($not_ref) {
1658 12 push @Data_Stack, { type => '', vals => [ $e1, $e2 ] };
1659 12 $ok = 0;
1660 }
1661 else {
1662 162 ▶ if( $Refs_Seen{$e1} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Test::More::Refs_Seen{$e1}) { } 7 155 162
1663 7 return $Refs_Seen{$e1} eq $e2;
1664 }
1665 else {
1666 155 $Refs_Seen{$e1} = "$e2";
1667 }
1668  
1669 155 my $type = _type($e1);
1670 155 ▶ $type = 'DIFFERENT' unless _type($e2) eq $type;
Branch: 1 branch
BranchTrueFalseTotal
unless _type($e2) eq $type 8 147 155
1671  
1672 155 ▶ if( $type eq 'DIFFERENT' ) {
Branch: 6 branches
BranchTrueFalseTotal
if ($type eq 'DIFFERENT') { } 8 147 155
elsif ($type eq 'ARRAY') { } 74 73 147
elsif ($type eq 'HASH') { } 55 18 73
elsif ($type eq 'REF') { } 0 18 18
elsif ($type eq 'SCALAR') { } 15 3 18
elsif ($type) { } 3 0 3
1673 8 push @Data_Stack, { type => $type, vals => [ $e1, $e2 ] };
1674 8 $ok = 0;
1675 }
1676 elsif( $type eq 'ARRAY' ) {
1677 74 $ok = _eq_array( $e1, $e2 );
1678 }
1679 elsif( $type eq 'HASH' ) {
1680 55 $ok = _eq_hash( $e1, $e2 );
1681 }
1682 elsif( $type eq 'REF' ) {
1683 0 push @Data_Stack, { type => $type, vals => [ $e1, $e2 ] };
1684 0 $ok = _deep_check( $$e1, $$e2 );
1685 0 ▶ pop @Data_Stack if $ok;
Branch: 1 branch
BranchTrueFalseTotal
if $ok 0 0 0
1686 }
1687 elsif( $type eq 'SCALAR' ) {
1688 15 push @Data_Stack, { type => 'REF', vals => [ $e1, $e2 ] };
1689 15 $ok = _deep_check( $$e1, $$e2 );
1690 15 ▶ pop @Data_Stack if $ok;
Branch: 1 branch
BranchTrueFalseTotal
if $ok 9 6 15
1691 }
1692 elsif($type) {
1693 3 push @Data_Stack, { type => $type, vals => [ $e1, $e2 ] };
1694 3 $ok = 0;
1695 }
1696 else {
1697 0 _whoa( 1, "No type in _deep_check" );
1698 }
1699 }
1700 }
1701  
1702 201 return $ok;
1703 }
1704  
1705 0 ▶sub _whoa {
Subroutine _whoa: not called CC=2 SCAR=17.9
1706 0 my( $check, $desc ) = @_;
1707 0 ▶ if($check) {
Branch: 1 branch
BranchTrueFalseTotal
if ($check) 0 0 0
1708 0 die <<"WHOA";
1709 WHOA! $desc
1710 This should never happen! Please contact the author immediately!
1711 WHOA
1712 }
1713 }
1714  
1715 =item B<eq_hash>
1716  
1717 my $is_eq = eq_hash(\%got, \%expected);
1718  
1719 Determines if the two hashes contain the same keys and values. This
1720 is a deep check.
1721  
1722 =cut
1723  
1724 7 ▶sub eq_hash {
Subroutine eq_hash: called CC=1 SCAR=0.0
Pod documented
1725 7 local @Data_Stack = ();
1726 7 return _deep_check(@_);
1727 }
1728  
1729 55 ▶sub _eq_hash {
Subroutine _eq_hash: called CC=10 SCAR=23.2
1730 55 my( $a1, $a2 ) = @_;
1731  
1732 55 ▶ if( grep _type($_) ne 'HASH', $a1, $a2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep((_type($_) ne "HASH"), $a1, $a2)) 0 55 55
1733 0 warn "eq_hash passed a non-hash ref";
1734 0 return 0;
1735 }
1736  
1737 55 ▶ return 1 if $a1 eq $a2;
Branch: 1 branch
BranchTrueFalseTotal
if $a1 eq $a2 0 55 55
1738  
1739 55 my $ok = 1;
1740 55 ▶ my $bigger = keys %$a1 > keys %$a2 ? $a1 : $a2;
Branch: 1 branch
BranchTrueFalseTotal
keys %$a1 > keys %$a2 ? : 1 54 55
1741 55 foreach my $k ( keys %$bigger ) {
1742 108 ▶ my $e1 = exists $a1->{$k} ? $a1->{$k} : $DNE;
Branch: 1 branch
BranchTrueFalseTotal
exists $a1->{$k} ? : 105 3 108
1743 108 ▶ my $e2 = exists $a2->{$k} ? $a2->{$k} : $DNE;
Branch: 1 branch
BranchTrueFalseTotal
exists $a2->{$k} ? : 107 1 108
1744  
1745 108 ▶ next if _equal_nonrefs($e1, $e2);
Branch: 1 branch
BranchTrueFalseTotal
if _equal_nonrefs($e1, $e2) 82 26 108
1746  
1747 26 push @Data_Stack, { type => 'HASH', idx => $k, vals => [ $e1, $e2 ] };
1748 26 $ok = _deep_check( $e1, $e2 );
1749 26 ▶ pop @Data_Stack if $ok;
Branch: 1 branch
BranchTrueFalseTotal
if $ok 12 14 26
1750  
1751 26 ▶ last unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 14 12 26
1752 }
1753  
1754 55 return $ok;
1755 }
1756  
1757 =item B<eq_set>
1758  
1759 my $is_eq = eq_set(\@got, \@expected);
1760  
1761 Similar to C<eq_array()>, except the order of the elements is B<not>
1762 important. This is a deep check, but the irrelevancy of order only
1763 applies to the top level.
1764  
1765 ok( eq_set(\@got, \@expected) );
1766  
1767 Is better written:
1768  
1769 is_deeply( [sort @got], [sort @expected] );
1770  
1771 B<NOTE> By historical accident, this is not a true set comparison.
1772 While the order of elements does not matter, duplicate elements do.
1773  
1774 B<NOTE> C<eq_set()> does not know how to deal with references at the top
1775 level. The following is an example of a comparison which might not work:
1776  
1777 eq_set([\1, \2], [\2, \1]);
1778  
1779 L<Test::Deep> contains much better set comparison functions.
1780  
1781 =cut
1782  
1783 9 ▶sub eq_set {
Subroutine eq_set: called CC=2 SCAR=7.0
Pod documented
1784 9 my( $a1, $a2 ) = @_;
1785 9 ▶ return 0 unless @$a1 == @$a2;
Branch: 1 branch
BranchTrueFalseTotal
unless @$a1 == @$a2 0 9 9
1786  
1787 130 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
1788  
1789 # It really doesn't matter how we sort them, as long as both arrays are
1790 # sorted with the same algorithm.
1791 #
1792 # Ensure that references are not accidentally treated the same as a
1793 # string containing the reference.
1794 #
1795 # Have to inline the sort routine due to a threading/sort bug.
1796 # See [rt.cpan.org 6782]
1797 #
1798 # I don't know how references would be sorted so we just don't sort
1799 # them. This means eq_set doesn't really work with refs.
1800 9 return eq_array(
1801 [ grep( ref, @$a1 ), sort( grep( !ref, @$a1 ) ) ],
1802 [ grep( ref, @$a2 ), sort( grep( !ref, @$a2 ) ) ],
1803 );
1804 }
1805  
1806 =back
1807  
1808  
1809 =head2 Extending and Embedding Test::More
1810  
1811 Sometimes the Test::More interface isn't quite enough. Fortunately,
1812 Test::More is built on top of L<Test::Builder> which provides a single,
1813 unified backend for any test library to use. This means two test
1814 libraries which both use L<Test::Builder> B<can> be used together in the
1815 same program.
1816  
1817 If you simply want to do a little tweaking of how the tests behave,
1818 you can access the underlying L<Test::Builder> object like so:
1819  
1820 =over 4
1821  
1822 =item B<builder>
1823  
1824 my $test_builder = Test::More->builder;
1825  
1826 Returns the L<Test::Builder> object underlying Test::More for you to play
1827 with.
1828  
1829  
1830 =back
1831  
1832  
1833 =head1 EXIT CODES
1834  
1835 If all your tests passed, L<Test::Builder> will exit with zero (which is
1836 normal). If anything failed it will exit with how many failed. If
1837 you run less (or more) tests than you planned, the missing (or extras)
1838 will be considered failures. If no tests were ever run L<Test::Builder>
1839 will throw a warning and exit with 255. If the test died, even after
1840 having successfully completed all its tests, it will still be
1841 considered a failure and will exit with 255.
1842  
1843 So the exit codes are...
1844  
1845 0 all tests successful
1846 255 test died or all passed but wrong # of tests run
1847 any other number how many failed (including missing or extras)
1848  
1849 If you fail more than 254 tests, it will be reported as 254.
1850  
1851 B<NOTE> This behavior may go away in future versions.
1852  
1853  
1854 =head1 COMPATIBILITY
1855  
1856 Test::More works with Perls as old as 5.8.1.
1857  
1858 Thread support is not very reliable before 5.10.1, but that's
1859 because threads are not very reliable before 5.10.1.
1860  
1861 Although Test::More has been a core module in versions of Perl since 5.6.2, Test::More has evolved since then, and not all of the features you're used to will be present in the shipped version of Test::More. If you are writing a module, don't forget to indicate in your package metadata the minimum version of Test::More that you require. For instance, if you want to use C<done_testing()> but want your test script to run on Perl 5.10.0, you will need to explicitly require Test::More > 0.88.
1862  
1863 Key feature milestones include:
1864  
1865 =over 4
1866  
1867 =item subtests
1868  
1869 Subtests were released in Test::More 0.94, which came with Perl 5.12.0. Subtests did not implicitly call C<done_testing()> until 0.96; the first Perl with that fix was Perl 5.14.0 with 0.98.
1870  
1871 =item C<done_testing()>
1872  
1873 This was released in Test::More 0.88 and first shipped with Perl in 5.10.1 as part of Test::More 0.92.
1874  
1875 =item C<cmp_ok()>
1876  
1877 Although C<cmp_ok()> was introduced in 0.40, 0.86 fixed an important bug to make it safe for overloaded objects; the fixed first shipped with Perl in 5.10.1 as part of Test::More 0.92.
1878  
1879 =item C<new_ok()> C<note()> and C<explain()>
1880  
1881 These were was released in Test::More 0.82, and first shipped with Perl in 5.10.1 as part of Test::More 0.92.
1882  
1883 =back
1884  
1885 There is a full version history in the Changes file, and the Test::More versions included as core can be found using L<Module::CoreList>:
1886  
1887 $ corelist -a Test::More
1888  
1889  
1890 =head1 CAVEATS and NOTES
1891  
1892 =over 4
1893  
1894 =item UTF-8 / "Wide character in print"
1895  
1896 If you use UTF-8 or other non-ASCII characters with Test::More you
1897 might get a "Wide character in print" warning. Using
1898 C<< binmode STDOUT, ":utf8" >> will not fix it.
1899 L<Test::Builder> (which powers
1900 Test::More) duplicates STDOUT and STDERR. So any changes to them,
1901 including changing their output disciplines, will not be seen by
1902 Test::More.
1903  
1904 One work around is to apply encodings to STDOUT and STDERR as early
1905 as possible and before Test::More (or any other Test module) loads.
1906  
1907 use open ':std', ':encoding(UTF-8)';
1908 use Test::More;
1909  
1910 A more direct work around is to change the filehandles used by
1911 L<Test::Builder>.
1912  
1913 my $builder = Test::More->builder;
1914 binmode $builder->output, ":encoding(UTF-8)";
1915 binmode $builder->failure_output, ":encoding(UTF-8)";
1916 binmode $builder->todo_output, ":encoding(UTF-8)";
1917  
1918  
1919 =item Overloaded objects
1920  
1921 String overloaded objects are compared B<as strings> (or in C<cmp_ok()>'s
1922 case, strings or numbers as appropriate to the comparison op). This
1923 prevents Test::More from piercing an object's interface allowing
1924 better blackbox testing. So if a function starts returning overloaded
1925 objects instead of bare strings your tests won't notice the
1926 difference. This is good.
1927  
1928 However, it does mean that functions like C<is_deeply()> cannot be used to
1929 test the internals of string overloaded objects. In this case I would
1930 suggest L<Test::Deep> which contains more flexible testing functions for
1931 complex data structures.
1932  
1933  
1934 =item Threads
1935  
1936 Test::More will only be aware of threads if C<use threads> has been done
1937 I<before> Test::More is loaded. This is ok:
1938  
1939 use threads;
1940 use Test::More;
1941  
1942 This may cause problems:
1943  
1944 use Test::More
1945 use threads;
1946  
1947 5.8.1 and above are supported. Anything below that has too many bugs.
1948  
1949 =back
1950  
1951  
1952 =head1 HISTORY
1953  
1954 This is a case of convergent evolution with Joshua Pritikin's L<Test>
1955 module. I was largely unaware of its existence when I'd first
1956 written my own C<ok()> routines. This module exists because I can't
1957 figure out how to easily wedge test names into Test's interface (along
1958 with a few other problems).
1959  
1960 The goal here is to have a testing utility that's simple to learn,
1961 quick to use and difficult to trip yourself up with while still
1962 providing more flexibility than the existing Test.pm. As such, the
1963 names of the most common routines are kept tiny, special cases and
1964 magic side-effects are kept to a minimum. WYSIWYG.
1965  
1966  
1967 =head1 SEE ALSO
1968  
1969 =head2
1970  
1971 =head2 ALTERNATIVES
1972  
1973 L<Test2::Suite> is the most recent and modern set of tools for testing.
1974  
1975 L<Test::Simple> if all this confuses you and you just want to write
1976 some tests. You can upgrade to Test::More later (it's forward
1977 compatible).
1978  
1979 L<Test::Legacy> tests written with Test.pm, the original testing
1980 module, do not play well with other testing libraries. Test::Legacy
1981 emulates the Test.pm interface and does play well with others.
1982  
1983 =head2 ADDITIONAL LIBRARIES
1984  
1985 L<Test::Differences> for more ways to test complex data structures.
1986 And it plays well with Test::More.
1987  
1988 L<Test::Class> is like xUnit but more perlish.
1989  
1990 L<Test::Deep> gives you more powerful complex data structure testing.
1991  
1992 L<Test::Inline> shows the idea of embedded testing.
1993  
1994 L<Mock::Quick> The ultimate mocking library. Easily spawn objects defined on
1995 the fly. Can also override, block, or reimplement packages as needed.
1996  
1997 L<Test::FixtureBuilder> Quickly define fixture data for unit tests.
1998  
1999 =head2 OTHER COMPONENTS
2000  
2001 L<Test::Harness> is the test runner and output interpreter for Perl.
2002 It's the thing that powers C<make test> and where the C<prove> utility
2003 comes from.
2004  
2005 =head2 BUNDLES
2006  
2007 L<Test::Most> Most commonly needed test functions and features.
2008  
2009 =head1 ENVIRONMENT VARIABLES
2010  
2011 See L<Test2::Env> for a list of meaningful environment variables.
2012  
2013 =head1 AUTHORS
2014  
2015 Michael G Schwern E<lt>schwern@pobox.comE<gt> with much inspiration
2016 from Joshua Pritikin's Test module and lots of help from Barrie
2017 Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and
2018 the perl-qa gang.
2019  
2020 =head1 MAINTAINERS
2021  
2022 =over 4
2023  
2024 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
2025  
2026 =back
2027  
2028  
2029 =head1 BUGS
2030  
2031 See L<https://github.com/Test-More/test-more/issues> to report and view bugs.
2032  
2033  
2034 =head1 SOURCE
2035  
2036 The source code repository for Test::More can be found at
2037 L<https://github.com/Test-More/test-more/>.
2038  
2039  
2040 =head1 COPYRIGHT
2041  
2042 Copyright 2001-2008 by Michael G Schwern E<lt>schwern@pobox.comE<gt>.
2043  
2044 This program is free software; you can redistribute it and/or
2045 modify it under the same terms as Perl itself.
2046  
2047 See L<https://dev.perl.org/licenses/>
2048  
2049 =cut
2050  
2051 130 1;
« blib/lib/Test2/Plugin/ExitSummary.pm ↑ Summary blib/lib/Test2/Util/HashBase.pm »