1Test2::Tools::Compare(3U)ser Contributed Perl DocumentatiToenst2::Tools::Compare(3)
2
3
4
6 Test2::Tools::Compare - Tools for comparing deep data structures.
7
9 Test::More had "is_deeply()". This library is the Test2 version that
10 can be used to compare data structures, but goes a step further in that
11 it provides tools for building a data structure specification against
12 which you can verify your data. There are both 'strict' and 'relaxed'
13 versions of the tools.
14
16 use Test2::Tools::Compare;
17
18 # Hash for demonstration purposes
19 my $some_hash = {a => 1, b => 2, c => 3};
20
21 # Strict checking, everything must match
22 is(
23 $some_hash,
24 {a => 1, b => 2, c => 3},
25 "The hash we got matches our expectations"
26 );
27
28 # Relaxed Checking, only fields we care about are checked, and we can use a
29 # regex to approximate a field.
30 like(
31 $some_hash,
32 {a => 1, b => qr/[0-9]+/},
33 "'a' is 1, 'b' is an integer, we don't care about 'c'."
34 );
35
36 ADVANCED
37 Declarative hash, array, and objects builders are available that allow
38 you to generate specifications. These are more verbose than simply
39 providing a hash, but have the advantage that every component you
40 specify has a line number associated. This is helpful for debugging as
41 the failure output will tell you not only which fields was incorrect,
42 but also the line on which you declared the field.
43
44 use Test2::Tools::Compare qw{
45 is like isnt unlike
46 match mismatch validator
47 hash array bag object meta number float rounded within string subset bool
48 in_set not_in_set check_set
49 item field call call_list call_hash prop check all_items all_keys all_vals all_values
50 etc end filter_items
51 T F D DNE FDNE E
52 event fail_events
53 exact_ref
54 };
55
56 is(
57 $some_hash,
58 hash {
59 field a => 1;
60 field b => 2;
61 field c => 3;
62 },
63 "Hash matches spec"
64 );
65
67 $bool = is($got, $expect)
68 $bool = is($got, $expect, $name)
69 $bool = is($got, $expect, $name, @diag)
70 $got is the data structure you want to check. $expect is what you
71 want $got to look like. $name is an optional name for the test.
72 @diag is optional diagnostics messages that will be printed to
73 STDERR in event of failure, they will not be displayed when the
74 comparison is successful. The boolean true/false result of the
75 comparison is returned.
76
77 This is the strict checker. The strict checker requires a perfect
78 match between $got and $expect. All hash fields must be specified,
79 all array items must be present, etc. All
80 non-scalar/hash/array/regex references must be identical (same
81 memory address). Scalar, hash and array references will be
82 traversed and compared. Regex references will be compared to see if
83 they have the same pattern.
84
85 is(
86 $some_hash,
87 {a => 1, b => 2, c => 3},
88 "The hash we got matches our expectations"
89 );
90
91 The only exception to strictness is when it is given an $expect
92 object that was built from a specification, in which case the
93 specification determines the strictness. Strictness only applies to
94 literal values/references that are provided and converted to a
95 specification for you.
96
97 is(
98 $some_hash,
99 hash { # Note: the hash function is not exported by default
100 field a => 1;
101 field b => match(qr/[0-9]+/); # Note: The match function is not exported by default
102 # Don't care about other fields.
103 },
104 "The hash comparison is not strict"
105 );
106
107 This works for both deep and shallow structures. For instance you
108 can use this to compare two strings:
109
110 is('foo', 'foo', "strings match");
111
112 Note: This is not the tool to use if you want to check if two
113 references are the same exact reference, use "ref_is()" from the
114 Test2::Tools::Ref plugin instead. Most of the time this will work
115 as well, however there are problems if your reference contains a
116 cycle and refers back to itself at some point. If this happens, an
117 exception will be thrown to break an otherwise infinite recursion.
118
119 Note: Non-reference values will be compared as strings using "eq",
120 so that means '2.0' and '2' will match.
121
122 $bool = isnt($got, $expect)
123 $bool = isnt($got, $expect, $name)
124 $bool = isnt($got, $expect, $name, @diag)
125 Opposite of "is()". Does all the same checks, but passes when there
126 is a mismatch.
127
128 $bool = like($got, $expect)
129 $bool = like($got, $expect, $name)
130 $bool = like($got, $expect, $name, @diag)
131 $got is the data structure you want to check. $expect is what you
132 want $got to look like. $name is an optional name for the test.
133 @diag is optional diagnostics messages that will be printed to
134 STDERR in event of failure, they will not be displayed when the
135 comparison is successful. The boolean true/false result of the
136 comparison is returned.
137
138 This is the relaxed checker. This will ignore hash keys or array
139 indexes that you do not actually specify in your $expect structure.
140 In addition regex and sub references will be used as validators. If
141 you provide a regex using "qr/.../", the regex itself will be used
142 to validate the corresponding value in the $got structure. The same
143 is true for coderefs, the value is passed in as the first argument
144 (and in $_) and the sub should return a boolean value. In this
145 tool regexes will stringify the thing they are checking.
146
147 like(
148 $some_hash,
149 {a => 1, b => qr/[0-9]+/},
150 "'a' is 1, 'b' is an integer, we don't care about other fields"
151 );
152
153 This works for both deep and shallow structures. For instance you
154 can use this to compare two strings:
155
156 like('foo bar', qr/^foo/, "string matches the pattern");
157
158 $bool = unlike($got, $expect)
159 $bool = unlike($got, $expect, $name)
160 $bool = unlike($got, $expect, $name, @diag)
161 Opposite of "like()". Does all the same checks, but passes when
162 there is a mismatch.
163
164 QUICK CHECKS
165 Note: None of these are exported by default. You need to request them.
166
167 Quick checks are a way to quickly generate a common value
168 specification. These can be used in structures passed into "is" and
169 "like" through the $expect argument.
170
171 Example:
172
173 is($foo, T(), '$foo has a true value');
174
175 $check = T()
176 This verifies that the value in the corresponding $got structure is
177 true, any true value will do.
178
179 is($foo, T(), '$foo has a true value');
180
181 is(
182 { a => 'xxx' },
183 { a => T() },
184 "The 'a' key is true"
185 );
186
187 $check = F()
188 This verifies that the value in the corresponding $got structure is
189 false, any false value will do, but the value must exist.
190
191 is($foo, F(), '$foo has a false value');
192
193 is(
194 { a => 0 },
195 { a => F() },
196 "The 'a' key is false"
197 );
198
199 It is important to note that a nonexistent value does not count as
200 false. This check will generate a failing test result:
201
202 is(
203 { a => 1 },
204 { a => 1, b => F() },
205 "The 'b' key is false"
206 );
207
208 This will produce the following output:
209
210 not ok 1 - The b key is false
211 # Failed test "The 'b' key is false"
212 # at some_file.t line 10.
213 # +------+------------------+-------+---------+
214 # | PATH | GOT | OP | CHECK |
215 # +------+------------------+-------+---------+
216 # | {b} | <DOES NOT EXIST> | FALSE | FALSE() |
217 # +------+------------------+-------+---------+
218
219 In Perl, you can have behavior that is different for a missing key
220 vs. a false key, so it was decided not to count a completely absent
221 value as false. See the "DNE()" shortcut below for checking that a
222 field is missing.
223
224 If you want to check for false and/or DNE use the "FDNE()" check.
225
226 $check = D()
227 This is to verify that the value in the $got structure is defined.
228 Any value other than "undef" will pass.
229
230 This will pass:
231
232 is('foo', D(), 'foo is defined');
233
234 This will fail:
235
236 is(undef, D(), 'foo is defined');
237
238 $check = U()
239 This is to verify that the value in the $got structure is
240 undefined.
241
242 This will pass:
243
244 is(undef, U(), 'not defined');
245
246 This will fail:
247
248 is('foo', U(), 'not defined');
249
250 $check = DF()
251 This is to verify that the value in the $got structure is defined
252 but false. Any false value other than "undef" will pass.
253
254 This will pass:
255
256 is(0, DF(), 'foo is defined but false');
257
258 These will fail:
259
260 is(undef, DF(), 'foo is defined but false');
261 is(1, DF(), 'foo is defined but false');
262
263 $check = E()
264 This can be used to check that a value exists. This is useful to
265 check that an array has more values, or to check that a key exists
266 in a hash, even if the value is undefined.
267
268 These pass:
269
270 is(['a', 'b', undef], ['a', 'b', E()], "There is a third item in the array");
271 is({a => 1, b => 2}, {a => 1, b => E()}, "The 'b' key exists in the hash");
272
273 These will fail:
274
275 is(['a', 'b'], ['a', 'b', E()], "Third item exists");
276 is({a => 1}, {a => 1, b => E()}, "'b' key exists");
277
278 $check = DNE()
279 This can be used to check that no value exists. This is useful to
280 check the end bound of an array, or to check that a key does not
281 exist in a hash.
282
283 These pass:
284
285 is(['a', 'b'], ['a', 'b', DNE()], "There is no third item in the array");
286 is({a => 1}, {a => 1, b => DNE()}, "The 'b' key does not exist in the hash");
287
288 These will fail:
289
290 is(['a', 'b', 'c'], ['a', 'b', DNE()], "No third item");
291 is({a => 1, b => 2}, {a => 1, b => DNE()}, "No 'b' key");
292
293 $check = FDNE()
294 This is a combination of "F()" and "DNE()". This will pass for a
295 false value, or a nonexistent value.
296
297 VALUE SPECIFICATIONS
298 Note: None of these are exported by default. You need to request them.
299
300 $check = string "..."
301 Verify that the value matches the given string using the "eq"
302 operator.
303
304 $check = !string "..."
305 Verify that the value does not match the given string using the
306 "ne" operator.
307
308 $check = number ...;
309 Verify that the value matches the given number using the "=="
310 operator.
311
312 $check = !number ...;
313 Verify that the value does not match the given number using the
314 "!=" operator.
315
316 $check = float ...;
317 Verify that the value is approximately equal to the given number.
318
319 If a 'precision' parameter is specified, both operands will be
320 rounded to 'precision' number of fractional decimal digits and
321 compared with "eq".
322
323 Otherwise, the check will be made within a range of +/-
324 'tolerance', with a default 'tolerance' of 1e-08.
325
326 See also "within" and "rounded".
327
328 $check = !float ...;
329 Verify that the value is not approximately equal to the given
330 number.
331
332 If a 'precision' parameter is specified, both operands will be
333 rounded to 'precision' number of fractional decimal digits and
334 compared with "eq".
335
336 Otherwise, the check will be made within a range of +/-
337 'tolerance', with a default 'tolerance' of 1e-08.
338
339 See also "!within" and "!rounded".
340
341 $check = within($num, $tolerance);
342 Verify that the value approximately matches the given number,
343 within a range of +/- $tolerance. Compared using the "=="
344 operator.
345
346 $tolerance is optional and defaults to 1e-08.
347
348 $check = !within($num, $tolerance);
349 Verify that the value does not approximately match the given number
350 within a range of +/- $tolerance. Compared using the "!="
351 operator.
352
353 $tolerance is optional and defaults to 1e-08.
354
355 $check = rounded($num, $precision);
356 Verify that the value approximately matches the given number, when
357 both are rounded to $precision number of fractional digits.
358 Compared using the "eq" operator.
359
360 $check = !rounded($num, $precision);
361 Verify that the value does not approximately match the given
362 number, when both are rounded to $precision number of fractional
363 digits. Compared using the "ne" operator.
364
365 $check = bool ...;
366 Verify the value has the same boolean value as the given argument
367 (XNOR).
368
369 $check = !bool ...;
370 Verify the value has a different boolean value from the given
371 argument (XOR).
372
373 $check = match qr/.../
374 $check = !mismatch qr/.../
375 Verify that the value matches the regex pattern. This form of
376 pattern check will NOT stringify references being checked.
377
378 Note: "!mismatch()" is documented for completion, please do not use
379 it.
380
381 $check = !match qr/.../
382 $check = mismatch qr/.../
383 Verify that the value does not match the regex pattern. This form
384 of pattern check will NOT stringify references being checked.
385
386 Note: "mismatch()" was created before overloading of "!" for
387 "match()" was a thing.
388
389 $check = validator(sub{ ... })
390 $check = validator($NAME => sub{ ... })
391 $check = validator($OP, $NAME, sub{ ... })
392 The coderef is the only required argument. The coderef should check
393 that the value is what you expect and return a boolean true or
394 false. Optionally, you can specify a name and operator that are
395 used in diagnostics. They are also provided to the sub itself as
396 named parameters.
397
398 Check the value using this sub. The sub gets the value in $_, and
399 it receives the value and several other items as named parameters.
400
401 my $check = validator(sub {
402 my %params = @_;
403
404 # These both work:
405 my $got = $_;
406 my $got = $params{got};
407
408 # Check if a value exists at all
409 my $exists = $params{exists}
410
411 # What $OP (if any) did we specify when creating the validator
412 my $operator = $params{operator};
413
414 # What name (if any) did we specify when creating the validator
415 my $name = $params{name};
416
417 ...
418
419 return $bool;
420 }
421
422 $check = exact_ref($ref)
423 Check that the value is exactly the same reference as the one
424 provided.
425
426 SET BUILDERS
427 Note: None of these are exported by default. You need to request them.
428
429 my $check = check_set($check1, $check2, ...)
430 Check that the value matches ALL of the specified checks.
431
432 my $check = in_set($check1, $check2, ...)
433 Check that the value matches ONE OR MORE of the specified checks.
434
435 not_in_set($check1, $check2, ...)
436 Check that the value DOES NOT match ANY of the specified checks.
437
438 check $thing
439 Check that the value matches the specified thing.
440
441 HASH BUILDER
442 Note: None of these are exported by default. You need to request them.
443
444 $check = hash {
445 field foo => 1;
446 field bar => 2;
447
448 # Ensure the 'baz' keys does not even exist in the hash.
449 field baz => DNE();
450
451 # Ensure the key exists, but is set to undef
452 field bat => undef;
453
454 # Any check can be used
455 field boo => $check;
456
457 # Set checks that apply to all keys or values. Can be done multiple
458 # times, and each call can define multiple checks, all will be run.
459 all_vals match qr/a/, match qr/b/; # All keys must have an 'a' and a 'b'
460 all_keys match qr/x/; # All keys must have an 'x'
461
462 ...
463
464 end(); # optional, enforces that no other keys are present.
465 };
466
467 $check = hash { ... }
468 This is used to define a hash check.
469
470 field $NAME => $VAL
471 field $NAME => $CHECK
472 Specify a field check. This will check the hash key specified by
473 $NAME and ensure it matches the value in $VAL. You can put any
474 valid check in $VAL, such as the result of another call to "array {
475 ... }", "DNE()", etc.
476
477 Note: This function can only be used inside a hash builder sub, and
478 must be called in void context.
479
480 all_keys($CHECK1, $CHECK2, ...)
481 Add checks that apply to all keys. You can put this anywhere in the
482 hash block, and can call it any number of times with any number of
483 arguments.
484
485 all_vals($CHECK1, $CHECK2, ...)
486 all_values($CHECK1, $CHECK2, ...)
487 Add checks that apply to all values. You can put this anywhere in
488 the hash block, and can call it any number of times with any number
489 of arguments.
490
491 end()
492 Enforce that no keys are found in the hash other than those
493 specified. This is essentially the "use strict" of a hash check.
494 This can be used anywhere in the hash builder, though typically it
495 is placed at the end.
496
497 etc()
498 Ignore any extra keys found in the hash. This is the opposite of
499 "end()". This can be used anywhere in the hash builder, though
500 typically it is placed at the end.
501
502 DNE()
503 This is a handy check that can be used with "field()" to ensure
504 that a field (D)oes (N)ot (E)xist.
505
506 field foo => DNE();
507
508 ARRAY BUILDER
509 Note: None of these are exported by default. You need to request them.
510
511 $check = array {
512 # Uses the next index, in this case index 0;
513 item 'a';
514
515 # Gets index 1 automatically
516 item 'b';
517
518 # Specify the index
519 item 2 => 'c';
520
521 # We skipped index 3, which means we don't care what it is.
522 item 4 => 'e';
523
524 # Gets index 5.
525 item 'f';
526
527 # Remove any REMAINING items that contain 0-9.
528 filter_items { grep {!m/[0-9]/} @_ };
529
530 # Set checks that apply to all items. Can be done multiple times, and
531 # each call can define multiple checks, all will be run.
532 all_items match qr/a/, match qr/b/;
533 all_items match qr/x/;
534
535 # Of the remaining items (after the filter is applied) the next one
536 # (which is now index 6) should be 'g'.
537 item 6 => 'g';
538
539 item 7 => DNE; # Ensure index 7 does not exist.
540
541 end(); # Ensure no other indexes exist.
542 };
543
544 $check = array { ... }
545 item $VAL
546 item $CHECK
547 item $IDX, $VAL
548 item $IDX, $CHECK
549 Add an expected item to the array. If $IDX is not specified it will
550 automatically calculate it based on the last item added. You can
551 skip indexes, which means you do not want them to be checked.
552
553 You can provide any value to check in $VAL, or you can provide any
554 valid check object.
555
556 Note: Items MUST be added in order.
557
558 Note: This function can only be used inside an array, bag or subset
559 builder sub, and must be called in void context.
560
561 filter_items { my @remaining = @_; ...; return @filtered }
562 This function adds a filter, all items remaining in the array from
563 the point the filter is reached will be passed into the filter sub
564 as arguments, the sub should return only the items that should be
565 checked.
566
567 Note: This function can only be used inside an array builder sub,
568 and must be called in void context.
569
570 all_items($CHECK1, $CHECK2, ...)
571 Add checks that apply to all items. You can put this anywhere in
572 the array block, and can call it any number of times with any
573 number of arguments.
574
575 end()
576 Enforce that there are no indexes after the last one specified.
577 This will not force checking of skipped indexes.
578
579 etc()
580 Ignore any extra items found in the array. This is the opposite of
581 "end()". This can be used anywhere in the array builder, though
582 typically it is placed at the end.
583
584 DNE()
585 This is a handy check that can be used with "item()" to ensure that
586 an index (D)oes (N)ot (E)xist.
587
588 item 5 => DNE();
589
590 BAG BUILDER
591 Note: None of these are exported by default. You need to request them.
592
593 $check = bag {
594 item 'a';
595 item 'b';
596
597 end(); # Ensure no other elements exist.
598 };
599
600 A bag is like an array, but we don't care about the order of the items.
601 In the example, $check would match both "['a','b']" and "['b','a']".
602
603 $check = bag { ... }
604 item $VAL
605 item $CHECK
606 Add an expected item to the bag.
607
608 You can provide any value to check in $VAL, or you can provide any
609 valid check object.
610
611 Note: This function can only be used inside an array, bag or subset
612 builder sub, and must be called in void context.
613
614 end()
615 Enforce that there are no more items after the last one specified.
616
617 etc()
618 Ignore any extra items found in the array. This is the opposite of
619 "end()". This can be used anywhere in the bag builder, though
620 typically it is placed at the end.
621
622 ORDERED SUBSET BUILDER
623 Note: None of these are exported by default. You need to request them.
624
625 $check = subset {
626 item 'a';
627 item 'b';
628 item 'c';
629
630 # Doesn't matter if the array has 'd', the check will skip past any
631 # unknown items until it finds the next one in our subset.
632
633 item 'e';
634 item 'f';
635 };
636
637 $check = subset { ... }
638 item $VAL
639 item $CHECK
640 Add an expected item to the subset.
641
642 You can provide any value to check in $VAL, or you can provide any
643 valid check object.
644
645 Note: Items MUST be added in order.
646
647 Note: This function can only be used inside an array, bag or subset
648 builder sub, and must be called in void context.
649
650 META BUILDER
651 Note: None of these are exported by default. You need to request them.
652
653 my $check = meta {
654 prop blessed => 'My::Module'; # Ensure value is blessed as our package
655 prop reftype => 'HASH'; # Ensure value is a blessed hash
656 prop size => 4; # Check the number of hash keys
657 prop this => ...; # Check the item itself
658 };
659
660 meta { ... }
661 meta_check { ... }
662 Build a meta check. If you are using Moose then the "meta()"
663 function would conflict with the one exported by Moose, in such
664 cases "meta_check()" is available. Neither is exported by default.
665
666 prop $NAME => $VAL
667 prop $NAME => $CHECK
668 Check the property specified by $name against the value or check.
669
670 Valid properties are:
671
672 'blessed'
673 What package (if any) the thing is blessed as.
674
675 'reftype'
676 Reference type (if any) the thing is.
677
678 'this'
679 The thing itself.
680
681 'size'
682 For array references this returns the number of elements. For
683 hashes this returns the number of keys. For everything else
684 this returns undef.
685
686 OBJECT BUILDER
687 Note: None of these are exported by default. You need to request them.
688
689 my $check = object {
690 call foo => 1; # Call the 'foo' method, check the result.
691
692 # Call the specified sub-ref as a method on the object, check the
693 # result. This is useful for wrapping methods that return multiple
694 # values.
695 call sub { [ shift->get_list ] } => [...];
696
697 # This can be used to ensure a method does not exist.
698 call nope => DNE();
699
700 # Check the hash key 'foo' of the underlying reference, this only works
701 # on blessed hashes.
702 field foo => 1;
703
704 # Check the value of index 4 on the underlying reference, this only
705 # works on blessed arrays.
706 item 4 => 'foo';
707
708 # Check the meta-property 'blessed' of the object.
709 prop blessed => 'My::Module';
710
711 # Ensure only the specified hash keys or array indexes are present in
712 # the underlying hash. Has no effect on meta-property checks or method
713 # checks.
714 end();
715 };
716
717 $check = object { ... }
718 Specify an object check for use in comparisons.
719
720 call $METHOD_NAME => $RESULT
721 call $METHOD_NAME => $CHECK
722 call [$METHOD_NAME, @METHOD_ARGS] => $RESULT
723 call [$METHOD_NAME, @METHOD_ARGS] => $CHECK
724 call sub { ... }, $RESULT
725 call sub { ... }, $CHECK
726 Call the specified method (or coderef) and verify the result. If
727 you pass an arrayref, the first element must be the method name,
728 the others are the arguments it will be called with.
729
730 The coderef form is useful if you need to do something more
731 complex.
732
733 my $ref = sub {
734 local $SOME::GLOBAL::THING = 3;
735 return [shift->get_values_for('thing')];
736 };
737
738 call $ref => ...;
739
740 call_list $METHOD_NAME => $RESULT
741 call_list $METHOD_NAME => $CHECK
742 call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT
743 call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK
744 call_list sub { ... }, $RESULT
745 call_list sub { ... }, $CHECK
746 Same as "call", but the method is invoked in list context, and the
747 result is always an arrayref.
748
749 call_list get_items => [ ... ];
750
751 call_hash $METHOD_NAME => $RESULT
752 call_hash $METHOD_NAME => $CHECK
753 call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT
754 call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK
755 call_hash sub { ... }, $RESULT
756 call_hash sub { ... }, $CHECK
757 Same as "call", but the method is invoked in list context, and the
758 result is always a hashref. This will warn if the method returns an
759 odd number of values.
760
761 call_hash get_items => { ... };
762
763 field $NAME => $VAL
764 Works just like it does for hash checks.
765
766 item $VAL
767 item $IDX, $VAL
768 Works just like it does for array checks.
769
770 prop $NAME => $VAL
771 prop $NAME => $CHECK
772 Check the property specified by $name against the value or check.
773
774 Valid properties are:
775
776 'blessed'
777 What package (if any) the thing is blessed as.
778
779 'reftype'
780 Reference type (if any) the thing is.
781
782 'this'
783 The thing itself.
784
785 'size'
786 For array references this returns the number of elements. For
787 hashes this returns the number of keys. For everything else
788 this returns undef.
789
790 DNE()
791 Can be used with "item", or "field" to ensure the hash field or
792 array index does not exist. Can also be used with "call" to ensure
793 a method does not exist.
794
795 end()
796 Turn on strict array/hash checking, ensuring that no extra
797 keys/indexes are present.
798
799 etc()
800 Ignore any extra items found in the hash/array. This is the
801 opposite of "end()". This can be used anywhere in the builder,
802 though typically it is placed at the end.
803
804 EVENT BUILDERS
805 Note: None of these are exported by default. You need to request them.
806
807 Check that we got an event of a specified type:
808
809 my $check = event 'Ok';
810
811 Check for details about the event:
812
813 my $check = event Ok => sub {
814 # Check for a failure
815 call pass => 0;
816
817 # Effective pass after TODO/SKIP are accounted for.
818 call effective_pass => 1;
819
820 # Check the diagnostics
821 call diag => [ match qr/Failed test foo/ ];
822
823 # Check the file the event reports to
824 prop file => 'foo.t';
825
826 # Check the line number the event reports o
827 prop line => '42';
828
829 # You can check the todo/skip values as well:
830 prop skip => 'broken';
831 prop todo => 'fixme';
832
833 # Thread-id and process-id where event was generated
834 prop tid => 123;
835 prop pid => 123;
836 };
837
838 You can also provide a fully qualified event package with the '+'
839 prefix:
840
841 my $check = event '+My::Event' => sub { ... }
842
843 You can also provide a hashref instead of a sub to directly check hash
844 values of the event:
845
846 my $check = event Ok => { pass => 1, ... };
847
848 USE IN OTHER BUILDERS
849
850 You can use these all in other builders, simply use them in void
851 context to have their value(s) appended to the build.
852
853 my $check = array {
854 event Ok => { ... };
855 event Note => { ... };
856
857 fail_events Ok => { pass => 0 };
858 # Get a Diag for free.
859 };
860
861 SPECIFICS
862
863 $check = event $TYPE;
864 $check = event $TYPE => sub { ... };
865 $check = event $TYPE => { ... };
866 This works just like an object builder. In addition to supporting
867 everything the object check supports, you also have to specify the
868 event type, and many extra meta-properties are available.
869
870 Extra properties are:
871
872 'file'
873 File name to which the event reports (for use in diagnostics).
874
875 'line'
876 Line number to which the event reports (for use in
877 diagnostics).
878
879 'package'
880 Package to which the event reports (for use in diagnostics).
881
882 'subname'
883 Sub that was called to generate the event (example: "ok()").
884
885 'skip'
886 Set to the skip value if the result was generated by skipping
887 tests.
888
889 'todo'
890 Set to the todo value if TODO was set when the event was
891 generated.
892
893 'trace'
894 The "at file foo.t line 42" string that will be used in
895 diagnostics.
896
897 'tid'
898 Thread ID in which the event was generated.
899
900 'pid'
901 Process ID in which the event was generated.
902
903 NOTE: Event checks have an implicit "etc()" added. This means you
904 need to use "end()" if you want to fail on unexpected hash keys or
905 array indexes. This implicit "etc()" extends to all forms,
906 including builder, hashref, and no argument.
907
908 @checks = fail_events $TYPE;
909 @checks = fail_events $TYPE => sub { ... };
910 @checks = fail_events $TYPE => { ... };
911 Just like "event()" documented above. The difference is that this
912 produces two events, the one you specify, and a "Diag" after it.
913 There are no extra checks in the Diag.
914
915 Use this to validate a simple failure where you do not want to be
916 bothered with the default diagnostics. It only adds a single Diag
917 check, so if your failure has custom diagnostics you will need to
918 add checks for them.
919
921 The source code repository for Test2-Suite can be found at
922 https://github.com/Test-More/Test2-Suite/.
923
925 Chad Granum <exodist@cpan.org>
926
928 Chad Granum <exodist@cpan.org>
929
931 Copyright 2018 Chad Granum <exodist@cpan.org>.
932
933 This program is free software; you can redistribute it and/or modify it
934 under the same terms as Perl itself.
935
936 See http://dev.perl.org/licenses/
937
938
939
940perl v5.28.1 2018-12-04 Test2::Tools::Compare(3)