1Test2::Tools::Compare(3U)ser Contributed Perl DocumentatiToenst2::Tools::Compare(3)
2
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 # Hash for demonstration purposes
19 my $some_hash = {a => 1, b => 2, c => 3};
20 # 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 # 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 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 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 DF E DNE FDNE U L
52 event fail_events
53 exact_ref
54 };
55 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 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 is(
86 $some_hash,
87 {a => 1, b => 2, c => 3},
88 "The hash we got matches our expectations"
89 );
90 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 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 This works for both deep and shallow structures. For instance you
108 can use this to compare two strings:
109 is('foo', 'foo', "strings match");
111 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 Note: Non-reference values will be compared as strings using "eq",
120 so that means '2.0' and '2' will match.
121 $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 $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 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 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 This works for both deep and shallow structures. For instance you
154 can use this to compare two strings:
155 like('foo bar', qr/^foo/, "string matches the pattern");
157 $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 QUICK CHECKS
165 Note: None of these are exported by default. You need to request them.
166 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 Example:
172 is($foo, T(), '$foo has a true value');
174 $check = T()
176 This verifies that the value in the corresponding $got structure is
177 true, any true value will do.
178 is($foo, T(), '$foo has a true value');
180 is(
182 { a => 'xxx' },
183 { a => T() },
184 "The 'a' key is true"
185 );
186 $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 is($foo, F(), '$foo has a false value');
192 is(
194 { a => 0 },
195 { a => F() },
196 "The 'a' key is false"
197 );
198 It is important to note that a nonexistent value does not count as
200 false. This check will generate a failing test result:
201 is(
203 { a => 1 },
204 { a => 1, b => F() },
205 "The 'b' key is false"
206 );
207 This will produce the following output:
209 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 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 If you want to check for false and/or DNE use the "FDNE()" check.
225 $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 This will pass:
231 is('foo', D(), 'foo is defined');
233 This will fail:
235 is(undef, D(), 'foo is defined');
237 $check = U()
239 This is to verify that the value in the $got structure is
240 undefined.
241 This will pass:
243 is(undef, U(), 'not defined');
245 This will fail:
247 is('foo', U(), 'not defined');
249 $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 This will pass:
255 is(0, DF(), 'foo is defined but false');
257 These will fail:
259 is(undef, DF(), 'foo is defined but false');
261 is(1, DF(), 'foo is defined but false');
262 $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 These pass:
269 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 These will fail:
274 is(['a', 'b'], ['a', 'b', E()], "Third item exists");
276 is({a => 1}, {a => 1, b => E()}, "'b' key exists");
277 $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 These pass:
284 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 These will fail:
289 is(['a', 'b', 'c'], ['a', 'b', DNE()], "No third item");
291 is({a => 1, b => 2}, {a => 1, b => DNE()}, "No 'b' key");
292 $check = FDNE()
294 This is a combination of "F()" and "DNE()". This will pass for a
295 false value, or a nonexistent value.
296 $check = L()
298 This is to verify that the value in the $got structure is defined
299 and has length. Any value other than "undef" or the empty string
300 will pass (including references).
301 These will pass:
303 is('foo', L(), 'value is defined and has length');
305 is([], L(), 'value is defined and has length');
306 These will fail:
308 is(undef, L(), 'value is defined and has length');
310 is('', L(), 'value is defined and has length');
311 VALUE SPECIFICATIONS
313 Note: None of these are exported by default. You need to request them.
314 $check = string "..."
316 Verify that the value matches the given string using the "eq"
317 operator.
318 $check = !string "..."
320 Verify that the value does not match the given string using the
321 "ne" operator.
322 $check = number ...;
324 Verify that the value matches the given number using the "=="
325 operator.
326 $check = !number ...;
328 Verify that the value does not match the given number using the
329 "!=" operator.
330 $check = float ...;
332 Verify that the value is approximately equal to the given number.
333 If a 'precision' parameter is specified, both operands will be
335 rounded to 'precision' number of fractional decimal digits and
336 compared with "eq".
337 is($near_val, float($val, precision => 4), "Near 4 decimal digits");
339 Otherwise, the check will be made within a range of +/-
341 'tolerance', with a default 'tolerance' of 1e-08.
342 is( $near_val, float($val, tolerance => 0.01), "Almost there...");
344 See also "within" and "rounded".
346 $check = !float ...;
348 Verify that the value is not approximately equal to the given
349 number.
350 If a 'precision' parameter is specified, both operands will be
352 rounded to 'precision' number of fractional decimal digits and
353 compared with "eq".
354 Otherwise, the check will be made within a range of +/-
356 'tolerance', with a default 'tolerance' of 1e-08.
357 See also "!within" and "!rounded".
359 $check = within($num, $tolerance);
361 Verify that the value approximately matches the given number,
362 within a range of +/- $tolerance. Compared using the "=="
363 operator.
364 $tolerance is optional and defaults to 1e-08.
366 $check = !within($num, $tolerance);
368 Verify that the value does not approximately match the given number
369 within a range of +/- $tolerance. Compared using the "!="
370 operator.
371 $tolerance is optional and defaults to 1e-08.
373 $check = rounded($num, $precision);
375 Verify that the value approximately matches the given number, when
376 both are rounded to $precision number of fractional digits.
377 Compared using the "eq" operator.
378 $check = !rounded($num, $precision);
380 Verify that the value does not approximately match the given
381 number, when both are rounded to $precision number of fractional
382 digits. Compared using the "ne" operator.
383 $check = bool ...;
385 Verify the value has the same boolean value as the given argument
386 (XNOR).
387 $check = !bool ...;
389 Verify the value has a different boolean value from the given
390 argument (XOR).
391 $check = check_isa ...;
393 Verify the value is an instance of the given class name.
394 $check = !check_isa ...;
396 Verify the value is not an instance of the given class name.
397 $check = match qr/.../
399 $check = !mismatch qr/.../
400 Verify that the value matches the regex pattern. This form of
401 pattern check will NOT stringify references being checked.
402 Note: "!mismatch()" is documented for completion, please do not use
404 it.
405 $check = !match qr/.../
407 $check = mismatch qr/.../
408 Verify that the value does not match the regex pattern. This form
409 of pattern check will NOT stringify references being checked.
410 Note: "mismatch()" was created before overloading of "!" for
412 "match()" was a thing.
413 $check = validator(sub{ ... })
415 $check = validator($NAME => sub{ ... })
416 $check = validator($OP, $NAME, sub{ ... })
417 The coderef is the only required argument. The coderef should check
418 that the value is what you expect and return a boolean true or
419 false. Optionally, you can specify a name and operator that are
420 used in diagnostics. They are also provided to the sub itself as
421 named parameters.
422 Check the value using this sub. The sub gets the value in $_, and
424 it receives the value and several other items as named parameters.
425 my $check = validator(sub {
427 my %params = @_;
428 # These both work:
430 my $got = $_;
431 my $got = $params{got};
432 # Check if a value exists at all
434 my $exists = $params{exists}
435 # What $OP (if any) did we specify when creating the validator
437 my $operator = $params{operator};
438 # What name (if any) did we specify when creating the validator
440 my $name = $params{name};
441 ...
443 return $bool;
445 }
446 $check = exact_ref($ref)
448 Check that the value is exactly the same reference as the one
449 provided.
450 SET BUILDERS
452 Note: None of these are exported by default. You need to request them.
453 my $check = check_set($check1, $check2, ...)
455 Check that the value matches ALL of the specified checks.
456 my $check = in_set($check1, $check2, ...)
458 Check that the value matches ONE OR MORE of the specified checks.
459 not_in_set($check1, $check2, ...)
461 Check that the value DOES NOT match ANY of the specified checks.
462 check $thing
464 Check that the value matches the specified thing.
465 HASH BUILDER
467 Note: None of these are exported by default. You need to request them.
468 $check = hash {
470 field foo => 1;
471 field bar => 2;
472 # Ensure the 'baz' keys does not even exist in the hash.
474 field baz => DNE();
475 # Ensure the key exists, but is set to undef
477 field bat => undef;
478 # Any check can be used
480 field boo => $check;
481 # Set checks that apply to all keys or values. Can be done multiple
483 # times, and each call can define multiple checks, all will be run.
484 all_vals match qr/a/, match qr/b/; # All values must have an 'a' and a 'b'
485 all_keys match qr/x/; # All keys must have an 'x'
486 ...
488 end(); # optional, enforces that no other keys are present.
490 };
491 $check = hash { ... }
493 This is used to define a hash check.
494 field $NAME => $VAL
496 field $NAME => $CHECK
497 Specify a field check. This will check the hash key specified by
498 $NAME and ensure it matches the value in $VAL. You can put any
499 valid check in $VAL, such as the result of another call to "array {
500 ... }", "DNE()", etc.
501 Note: This function can only be used inside a hash builder sub, and
503 must be called in void context.
504 all_keys($CHECK1, $CHECK2, ...)
506 Add checks that apply to all keys. You can put this anywhere in the
507 hash block, and can call it any number of times with any number of
508 arguments.
509 all_vals($CHECK1, $CHECK2, ...)
511 all_values($CHECK1, $CHECK2, ...)
512 Add checks that apply to all values. You can put this anywhere in
513 the hash block, and can call it any number of times with any number
514 of arguments.
515 end()
517 Enforce that no keys are found in the hash other than those
518 specified. This is essentially the "use strict" of a hash check.
519 This can be used anywhere in the hash builder, though typically it
520 is placed at the end.
521 etc()
523 Ignore any extra keys found in the hash. This is the opposite of
524 "end()". This can be used anywhere in the hash builder, though
525 typically it is placed at the end.
526 DNE()
528 This is a handy check that can be used with "field()" to ensure
529 that a field (D)oes (N)ot (E)xist.
530 field foo => DNE();
532 ARRAY BUILDER
534 Note: None of these are exported by default. You need to request them.
535 $check = array {
537 # Uses the next index, in this case index 0;
538 item 'a';
539 # Gets index 1 automatically
541 item 'b';
542 # Specify the index
544 item 2 => 'c';
545 # We skipped index 3, which means we don't care what it is.
547 item 4 => 'e';
548 # Gets index 5.
550 item 'f';
551 # Remove any REMAINING items that contain 0-9.
553 filter_items { grep {!m/[0-9]/} @_ };
554 # Set checks that apply to all items. Can be done multiple times, and
556 # each call can define multiple checks, all will be run.
557 all_items match qr/a/, match qr/b/;
558 all_items match qr/x/;
559 # Of the remaining items (after the filter is applied) the next one
561 # (which is now index 6) should be 'g'.
562 item 6 => 'g';
563 item 7 => DNE; # Ensure index 7 does not exist.
565 end(); # Ensure no other indexes exist.
567 };
568 $check = array { ... }
570 item $VAL
571 item $CHECK
572 item $IDX, $VAL
573 item $IDX, $CHECK
574 Add an expected item to the array. If $IDX is not specified it will
575 automatically calculate it based on the last item added. You can
576 skip indexes, which means you do not want them to be checked.
577 You can provide any value to check in $VAL, or you can provide any
579 valid check object.
580 Note: Items MUST be added in order.
582 Note: This function can only be used inside an array, bag or subset
584 builder sub, and must be called in void context.
585 filter_items { my @remaining = @_; ...; return @filtered }
587 This function adds a filter, all items remaining in the array from
588 the point the filter is reached will be passed into the filter sub
589 as arguments, the sub should return only the items that should be
590 checked.
591 Note: This function can only be used inside an array builder sub,
593 and must be called in void context.
594 all_items($CHECK1, $CHECK2, ...)
596 Add checks that apply to all items. You can put this anywhere in
597 the array block, and can call it any number of times with any
598 number of arguments.
599 end()
601 Enforce that there are no indexes after the last one specified.
602 This will not force checking of skipped indexes.
603 etc()
605 Ignore any extra items found in the array. This is the opposite of
606 "end()". This can be used anywhere in the array builder, though
607 typically it is placed at the end.
608 DNE()
610 This is a handy check that can be used with "item()" to ensure that
611 an index (D)oes (N)ot (E)xist.
612 item 5 => DNE();
614 BAG BUILDER
616 Note: None of these are exported by default. You need to request them.
617 $check = bag {
619 item 'a';
620 item 'b';
621 end(); # Ensure no other elements exist.
623 };
624 A bag is like an array, but we don't care about the order of the items.
626 In the example, $check would match both "['a','b']" and "['b','a']".
627 $check = bag { ... }
629 item $VAL
630 item $CHECK
631 Add an expected item to the bag.
632 You can provide any value to check in $VAL, or you can provide any
634 valid check object.
635 Note: This function can only be used inside an array, bag or subset
637 builder sub, and must be called in void context.
638 all_items($CHECK1, $CHECK2, ...)
640 Add checks that apply to all items. You can put this anywhere in
641 the bag block, and can call it any number of times with any number
642 of arguments.
643 end()
645 Enforce that there are no more items after the last one specified.
646 etc()
648 Ignore any extra items found in the array. This is the opposite of
649 "end()". This can be used anywhere in the bag builder, though
650 typically it is placed at the end.
651 ORDERED SUBSET BUILDER
653 Note: None of these are exported by default. You need to request them.
654 $check = subset {
656 item 'a';
657 item 'b';
658 item 'c';
659 # Doesn't matter if the array has 'd', the check will skip past any
661 # unknown items until it finds the next one in our subset.
662 item 'e';
664 item 'f';
665 };
666 $check = subset { ... }
668 item $VAL
669 item $CHECK
670 Add an expected item to the subset.
671 You can provide any value to check in $VAL, or you can provide any
673 valid check object.
674 Note: Items MUST be added in order.
676 Note: This function can only be used inside an array, bag or subset
678 builder sub, and must be called in void context.
679 META BUILDER
681 Note: None of these are exported by default. You need to request them.
682 my $check = meta {
684 prop blessed => 'My::Module'; # Ensure value is blessed as our package
685 prop reftype => 'HASH'; # Ensure value is a blessed hash
686 prop isa => 'My::Base'; # Ensure value is an instance of our class
687 prop size => 4; # Check the number of hash keys
688 prop this => ...; # Check the item itself
689 };
690 meta { ... }
692 meta_check { ... }
693 Build a meta check. If you are using Moose then the "meta()"
694 function would conflict with the one exported by Moose, in such
695 cases "meta_check()" is available. Neither is exported by default.
696 prop $NAME => $VAL
698 prop $NAME => $CHECK
699 Check the property specified by $name against the value or check.
700 Valid properties are:
702 'blessed'
704 What package (if any) the thing is blessed as.
705 'reftype'
707 Reference type (if any) the thing is.
708 'isa'
710 What class the thing is an instance of.
711 'this'
713 The thing itself.
714 'size'
716 For array references this returns the number of elements. For
717 hashes this returns the number of keys. For everything else
718 this returns undef.
719 OBJECT BUILDER
721 Note: None of these are exported by default. You need to request them.
722 my $check = object {
724 call foo => 1; # Call the 'foo' method, check the result.
725 # Call the specified sub-ref as a method on the object, check the
727 # result. This is useful for wrapping methods that return multiple
728 # values.
729 call sub { [ shift->get_list ] } => [...];
730 # This can be used to ensure a method does not exist.
732 call nope => DNE();
733 # Check the hash key 'foo' of the underlying reference, this only works
735 # on blessed hashes.
736 field foo => 1;
737 # Check the value of index 4 on the underlying reference, this only
739 # works on blessed arrays.
740 item 4 => 'foo';
741 # Check the meta-property 'blessed' of the object.
743 prop blessed => 'My::Module';
744 # Check if the object is an instance of the specified class.
746 prop isa => 'My::Base';
747 # Ensure only the specified hash keys or array indexes are present in
749 # the underlying hash. Has no effect on meta-property checks or method
750 # checks.
751 end();
752 };
753 $check = object { ... }
755 Specify an object check for use in comparisons.
756 call $METHOD_NAME => $RESULT
758 call $METHOD_NAME => $CHECK
759 call [$METHOD_NAME, @METHOD_ARGS] => $RESULT
760 call [$METHOD_NAME, @METHOD_ARGS] => $CHECK
761 call sub { ... }, $RESULT
762 call sub { ... }, $CHECK
763 Call the specified method (or coderef) and verify the result. If
764 you pass an arrayref, the first element must be the method name,
765 the others are the arguments it will be called with.
766 The coderef form is useful if you need to do something more
768 complex.
769 my $ref = sub {
771 local $SOME::GLOBAL::THING = 3;
772 return [shift->get_values_for('thing')];
773 };
774 call $ref => ...;
776 call_list $METHOD_NAME => $RESULT
778 call_list $METHOD_NAME => $CHECK
779 call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT
780 call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK
781 call_list sub { ... }, $RESULT
782 call_list sub { ... }, $CHECK
783 Same as "call", but the method is invoked in list context, and the
784 result is always an arrayref.
785 call_list get_items => [ ... ];
787 call_hash $METHOD_NAME => $RESULT
789 call_hash $METHOD_NAME => $CHECK
790 call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT
791 call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK
792 call_hash sub { ... }, $RESULT
793 call_hash sub { ... }, $CHECK
794 Same as "call", but the method is invoked in list context, and the
795 result is always a hashref. This will warn if the method returns an
796 odd number of values.
797 call_hash get_items => { ... };
799 field $NAME => $VAL
801 Works just like it does for hash checks.
802 item $VAL
804 item $IDX, $VAL
805 Works just like it does for array checks.
806 prop $NAME => $VAL
808 prop $NAME => $CHECK
809 Check the property specified by $name against the value or check.
810 Valid properties are:
812 'blessed'
814 What package (if any) the thing is blessed as.
815 'reftype'
817 Reference type (if any) the thing is.
818 'isa'
820 What class the thing is an instance of.
821 'this'
823 The thing itself.
824 'size'
826 For array references this returns the number of elements. For
827 hashes this returns the number of keys. For everything else
828 this returns undef.
829 DNE()
831 Can be used with "item", or "field" to ensure the hash field or
832 array index does not exist. Can also be used with "call" to ensure
833 a method does not exist.
834 end()
836 Turn on strict array/hash checking, ensuring that no extra
837 keys/indexes are present.
838 etc()
840 Ignore any extra items found in the hash/array. This is the
841 opposite of "end()". This can be used anywhere in the builder,
842 though typically it is placed at the end.
843 EVENT BUILDERS
845 Note: None of these are exported by default. You need to request them.
846 Check that we got an event of a specified type:
848 my $check = event 'Ok';
850 Check for details about the event:
852 my $check = event Ok => sub {
854 # Check for a failure
855 call pass => 0;
856 # Effective pass after TODO/SKIP are accounted for.
858 call effective_pass => 1;
859 # Check the diagnostics
861 call diag => [ match qr/Failed test foo/ ];
862 # Check the file the event reports to
864 prop file => 'foo.t';
865 # Check the line number the event reports o
867 prop line => '42';
868 # You can check the todo/skip values as well:
870 prop skip => 'broken';
871 prop todo => 'fixme';
872 # Thread-id and process-id where event was generated
874 prop tid => 123;
875 prop pid => 123;
876 };
877 You can also provide a fully qualified event package with the '+'
879 prefix:
880 my $check = event '+My::Event' => sub { ... }
882 You can also provide a hashref instead of a sub to directly check hash
884 values of the event:
885 my $check = event Ok => { pass => 1, ... };
887 USE IN OTHER BUILDERS
889 You can use these all in other builders, simply use them in void
891 context to have their value(s) appended to the build.
892 my $check = array {
894 event Ok => { ... };
895 event Note => { ... };
896 fail_events Ok => { pass => 0 };
898 # Get a Diag for free.
899 };
900 SPECIFICS
902 $check = event $TYPE;
904 $check = event $TYPE => sub { ... };
905 $check = event $TYPE => { ... };
906 This works just like an object builder. In addition to supporting
907 everything the object check supports, you also have to specify the
908 event type, and many extra meta-properties are available.
909 Extra properties are:
911 'file'
913 File name to which the event reports (for use in diagnostics).
914 'line'
916 Line number to which the event reports (for use in
917 diagnostics).
918 'package'
920 Package to which the event reports (for use in diagnostics).
921 'subname'
923 Sub that was called to generate the event (example: "ok()").
924 'skip'
926 Set to the skip value if the result was generated by skipping
927 tests.
928 'todo'
930 Set to the todo value if TODO was set when the event was
931 generated.
932 'trace'
934 The "at file foo.t line 42" string that will be used in
935 diagnostics.
936 'tid'
938 Thread ID in which the event was generated.
939 'pid'
941 Process ID in which the event was generated.
942 NOTE: Event checks have an implicit "etc()" added. This means you
944 need to use "end()" if you want to fail on unexpected hash keys or
945 array indexes. This implicit "etc()" extends to all forms,
946 including builder, hashref, and no argument.
947 @checks = fail_events $TYPE;
949 @checks = fail_events $TYPE => sub { ... };
950 @checks = fail_events $TYPE => { ... };
951 Just like "event()" documented above. The difference is that this
952 produces two events, the one you specify, and a "Diag" after it.
953 There are no extra checks in the Diag.
954 Use this to validate a simple failure where you do not want to be
956 bothered with the default diagnostics. It only adds a single Diag
957 check, so if your failure has custom diagnostics you will need to
958 add checks for them.
959
961 The source code repository for Test2-Suite can be found at
962 https://github.com/Test-More/Test2-Suite/.
963
965 Chad Granum <exodist@cpan.org>
966
968 Chad Granum <exodist@cpan.org>
969
971 Copyright 2018 Chad Granum <exodist@cpan.org>.
972 This program is free software; you can redistribute it and/or modify it
974 under the same terms as Perl itself.
975 See http://dev.perl.org/licenses/
977perl v5.36.0 2022-07-22 Test2::Tools::Compare(3)