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 can
10 be used to compare data structures, but goes a step further in that it
11 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 there
162 is a mismatch.
163 The is(), isnt(), like(), and unlike() functions can be made to dump
165 $got using Data::Dumper when tests fail by setting the "T2_AUTO_DUMP"
166 environment variable to "1". (Alternatively, "T2_AUTO_DUMP" can be set
167 to the name of a Perl module providing a compatible Dump() method.) The
168 "T2_AUTO_DEPARSE" environment variable can be used to enable
169 Data::Dumper's deparsing of coderefs.
170 QUICK CHECKS
172 Note: None of these are exported by default. You need to request them.
173 Quick checks are a way to quickly generate a common value
175 specification. These can be used in structures passed into "is" and
176 "like" through the $expect argument.
177 Example:
179 is($foo, T(), '$foo has a true value');
181 $check = T()
183 This verifies that the value in the corresponding $got structure is
184 true, any true value will do.
185 is($foo, T(), '$foo has a true value');
187 is(
189 { a => 'xxx' },
190 { a => T() },
191 "The 'a' key is true"
192 );
193 $check = F()
195 This verifies that the value in the corresponding $got structure is
196 false, any false value will do, but the value must exist.
197 is($foo, F(), '$foo has a false value');
199 is(
201 { a => 0 },
202 { a => F() },
203 "The 'a' key is false"
204 );
205 It is important to note that a nonexistent value does not count as
207 false. This check will generate a failing test result:
208 is(
210 { a => 1 },
211 { a => 1, b => F() },
212 "The 'b' key is false"
213 );
214 This will produce the following output:
216 not ok 1 - The b key is false
218 # Failed test "The 'b' key is false"
219 # at some_file.t line 10.
220 # +------+------------------+-------+---------+
221 # | PATH | GOT | OP | CHECK |
222 # +------+------------------+-------+---------+
223 # | {b} | <DOES NOT EXIST> | FALSE | FALSE() |
224 # +------+------------------+-------+---------+
225 In Perl, you can have behavior that is different for a missing key
227 vs. a false key, so it was decided not to count a completely absent
228 value as false. See the DNE() shortcut below for checking that a
229 field is missing.
230 If you want to check for false and/or DNE use the FDNE() check.
232 $check = D()
234 This is to verify that the value in the $got structure is defined.
235 Any value other than "undef" will pass.
236 This will pass:
238 is('foo', D(), 'foo is defined');
240 This will fail:
242 is(undef, D(), 'foo is defined');
244 $check = U()
246 This is to verify that the value in the $got structure is
247 undefined.
248 This will pass:
250 is(undef, U(), 'not defined');
252 This will fail:
254 is('foo', U(), 'not defined');
256 $check = DF()
258 This is to verify that the value in the $got structure is defined
259 but false. Any false value other than "undef" will pass.
260 This will pass:
262 is(0, DF(), 'foo is defined but false');
264 These will fail:
266 is(undef, DF(), 'foo is defined but false');
268 is(1, DF(), 'foo is defined but false');
269 $check = E()
271 This can be used to check that a value exists. This is useful to
272 check that an array has more values, or to check that a key exists
273 in a hash, even if the value is undefined.
274 These pass:
276 is(['a', 'b', undef], ['a', 'b', E()], "There is a third item in the array");
278 is({a => 1, b => 2}, {a => 1, b => E()}, "The 'b' key exists in the hash");
279 These will fail:
281 is(['a', 'b'], ['a', 'b', E()], "Third item exists");
283 is({a => 1}, {a => 1, b => E()}, "'b' key exists");
284 $check = DNE()
286 This can be used to check that no value exists. This is useful to
287 check the end bound of an array, or to check that a key does not
288 exist in a hash.
289 These pass:
291 is(['a', 'b'], ['a', 'b', DNE()], "There is no third item in the array");
293 is({a => 1}, {a => 1, b => DNE()}, "The 'b' key does not exist in the hash");
294 These will fail:
296 is(['a', 'b', 'c'], ['a', 'b', DNE()], "No third item");
298 is({a => 1, b => 2}, {a => 1, b => DNE()}, "No 'b' key");
299 $check = FDNE()
301 This is a combination of F() and DNE(). This will pass for a false
302 value, or a nonexistent value.
303 $check = L()
305 This is to verify that the value in the $got structure is defined
306 and has length. Any value other than "undef" or the empty string
307 will pass (including references).
308 These will pass:
310 is('foo', L(), 'value is defined and has length');
312 is([], L(), 'value is defined and has length');
313 These will fail:
315 is(undef, L(), 'value is defined and has length');
317 is('', L(), 'value is defined and has length');
318 VALUE SPECIFICATIONS
320 Note: None of these are exported by default. You need to request them.
321 $check = string "..."
323 Verify that the value matches the given string using the "eq"
324 operator.
325 $check = !string "..."
327 Verify that the value does not match the given string using the
328 "ne" operator.
329 $check = number ...;
331 Verify that the value matches the given number using the "=="
332 operator.
333 $check = !number ...;
335 Verify that the value does not match the given number using the
336 "!=" operator.
337 $check = float ...;
339 Verify that the value is approximately equal to the given number.
340 If a 'precision' parameter is specified, both operands will be
342 rounded to 'precision' number of fractional decimal digits and
343 compared with "eq".
344 is($near_val, float($val, precision => 4), "Near 4 decimal digits");
346 Otherwise, the check will be made within a range of +/-
348 'tolerance', with a default 'tolerance' of 1e-08.
349 is( $near_val, float($val, tolerance => 0.01), "Almost there...");
351 See also "within" and "rounded".
353 $check = !float ...;
355 Verify that the value is not approximately equal to the given
356 number.
357 If a 'precision' parameter is specified, both operands will be
359 rounded to 'precision' number of fractional decimal digits and
360 compared with "eq".
361 Otherwise, the check will be made within a range of +/-
363 'tolerance', with a default 'tolerance' of 1e-08.
364 See also "!within" and "!rounded".
366 $check = within($num, $tolerance);
368 Verify that the value approximately matches 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 = !within($num, $tolerance);
375 Verify that the value does not approximately match the given number
376 within a range of +/- $tolerance. Compared using the "!="
377 operator.
378 $tolerance is optional and defaults to 1e-08.
380 $check = rounded($num, $precision);
382 Verify that the value approximately matches the given number, when
383 both are rounded to $precision number of fractional digits.
384 Compared using the "eq" operator.
385 $check = !rounded($num, $precision);
387 Verify that the value does not approximately match the given
388 number, when both are rounded to $precision number of fractional
389 digits. Compared using the "ne" operator.
390 $check = bool ...;
392 Verify the value has the same boolean value as the given argument
393 (XNOR).
394 $check = !bool ...;
396 Verify the value has a different boolean value from the given
397 argument (XOR).
398 $check = check_isa ...;
400 Verify the value is an instance of the given class name.
401 $check = !check_isa ...;
403 Verify the value is not an instance of the given class name.
404 $check = match qr/.../
406 $check = !mismatch qr/.../
407 Verify that the value matches the regex pattern. This form of
408 pattern check will NOT stringify references being checked.
409 Note: "!mismatch()" is documented for completion, please do not use
411 it.
412 $check = !match qr/.../
414 $check = mismatch qr/.../
415 Verify that the value does not match the regex pattern. This form
416 of pattern check will NOT stringify references being checked.
417 Note: mismatch() was created before overloading of "!" for match()
419 was a thing.
420 $check = validator(sub{ ... })
422 $check = validator($NAME => sub{ ... })
423 $check = validator($OP, $NAME, sub{ ... })
424 The coderef is the only required argument. The coderef should check
425 that the value is what you expect and return a boolean true or
426 false. Optionally, you can specify a name and operator that are
427 used in diagnostics. They are also provided to the sub itself as
428 named parameters.
429 Check the value using this sub. The sub gets the value in $_, and
431 it receives the value and several other items as named parameters.
432 my $check = validator(sub {
434 my %params = @_;
435 # These both work:
437 my $got = $_;
438 my $got = $params{got};
439 # Check if a value exists at all
441 my $exists = $params{exists}
442 # What $OP (if any) did we specify when creating the validator
444 my $operator = $params{operator};
445 # What name (if any) did we specify when creating the validator
447 my $name = $params{name};
448 ...
450 return $bool;
452 }
453 $check = exact_ref($ref)
455 Check that the value is exactly the same reference as the one
456 provided.
457 SET BUILDERS
459 Note: None of these are exported by default. You need to request them.
460 my $check = check_set($check1, $check2, ...)
462 Check that the value matches ALL of the specified checks.
463 my $check = in_set($check1, $check2, ...)
465 Check that the value matches ONE OR MORE of the specified checks.
466 not_in_set($check1, $check2, ...)
468 Check that the value DOES NOT match ANY of the specified checks.
469 check $thing
471 Check that the value matches the specified thing.
472 HASH BUILDER
474 Note: None of these are exported by default. You need to request them.
475 $check = hash {
477 field foo => 1;
478 field bar => 2;
479 # Ensure the 'baz' keys does not even exist in the hash.
481 field baz => DNE();
482 # Ensure the key exists, but is set to undef
484 field bat => undef;
485 # Any check can be used
487 field boo => $check;
488 # Set checks that apply to all keys or values. Can be done multiple
490 # times, and each call can define multiple checks, all will be run.
491 all_vals match qr/a/, match qr/b/; # All values must have an 'a' and a 'b'
492 all_keys match qr/x/; # All keys must have an 'x'
493 ...
495 end(); # optional, enforces that no other keys are present.
497 };
498 $check = hash { ... }
500 This is used to define a hash check.
501 field $NAME => $VAL
503 field $NAME => $CHECK
504 Specify a field check. This will check the hash key specified by
505 $NAME and ensure it matches the value in $VAL. You can put any
506 valid check in $VAL, such as the result of another call to "array {
507 ... }", DNE(), etc.
508 Note: This function can only be used inside a hash builder sub, and
510 must be called in void context.
511 all_keys($CHECK1, $CHECK2, ...)
513 Add checks that apply to all keys. You can put this anywhere in the
514 hash block, and can call it any number of times with any number of
515 arguments.
516 all_vals($CHECK1, $CHECK2, ...)
518 all_values($CHECK1, $CHECK2, ...)
519 Add checks that apply to all values. You can put this anywhere in
520 the hash block, and can call it any number of times with any number
521 of arguments.
522 end()
524 Enforce that no keys are found in the hash other than those
525 specified. This is essentially the "use strict" of a hash check.
526 This can be used anywhere in the hash builder, though typically it
527 is placed at the end.
528 etc()
530 Ignore any extra keys found in the hash. This is the opposite of
531 end(). This can be used anywhere in the hash builder, though
532 typically it is placed at the end.
533 DNE()
535 This is a handy check that can be used with field() to ensure that
536 a field (D)oes (N)ot (E)xist.
537 field foo => DNE();
539 ARRAY BUILDER
541 Note: None of these are exported by default. You need to request them.
542 $check = array {
544 # Uses the next index, in this case index 0;
545 item 'a';
546 # Gets index 1 automatically
548 item 'b';
549 # Specify the index
551 item 2 => 'c';
552 # We skipped index 3, which means we don't care what it is.
554 item 4 => 'e';
555 # Gets index 5.
557 item 'f';
558 # Remove any REMAINING items that contain 0-9.
560 filter_items { grep {!m/[0-9]/} @_ };
561 # Set checks that apply to all items. Can be done multiple times, and
563 # each call can define multiple checks, all will be run.
564 all_items match qr/a/, match qr/b/;
565 all_items match qr/x/;
566 # Of the remaining items (after the filter is applied) the next one
568 # (which is now index 6) should be 'g'.
569 item 6 => 'g';
570 item 7 => DNE; # Ensure index 7 does not exist.
572 end(); # Ensure no other indexes exist.
574 };
575 $check = array { ... }
577 item $VAL
578 item $CHECK
579 item $IDX, $VAL
580 item $IDX, $CHECK
581 Add an expected item to the array. If $IDX is not specified it will
582 automatically calculate it based on the last item added. You can
583 skip indexes, which means you do not want them to be checked.
584 You can provide any value to check in $VAL, or you can provide any
586 valid check object.
587 Note: Items MUST be added in order.
589 Note: This function can only be used inside an array, bag or subset
591 builder sub, and must be called in void context.
592 filter_items { my @remaining = @_; ...; return @filtered }
594 This function adds a filter, all items remaining in the array from
595 the point the filter is reached will be passed into the filter sub
596 as arguments, the sub should return only the items that should be
597 checked.
598 Note: This function can only be used inside an array builder sub,
600 and must be called in void context.
601 all_items($CHECK1, $CHECK2, ...)
603 Add checks that apply to all items. You can put this anywhere in
604 the array block, and can call it any number of times with any
605 number of arguments.
606 end()
608 Enforce that there are no indexes after the last one specified.
609 This will not force checking of skipped indexes.
610 etc()
612 Ignore any extra items found in the array. This is the opposite of
613 end(). This can be used anywhere in the array builder, though
614 typically it is placed at the end.
615 DNE()
617 This is a handy check that can be used with item() to ensure that
618 an index (D)oes (N)ot (E)xist.
619 item 5 => DNE();
621 BAG BUILDER
623 Note: None of these are exported by default. You need to request them.
624 $check = bag {
626 item 'a';
627 item 'b';
628 end(); # Ensure no other elements exist.
630 };
631 A bag is like an array, but we don't care about the order of the items.
633 In the example, $check would match both "['a','b']" and "['b','a']".
634 $check = bag { ... }
636 item $VAL
637 item $CHECK
638 Add an expected item to the bag.
639 You can provide any value to check in $VAL, or you can provide any
641 valid check object.
642 Note: This function can only be used inside an array, bag or subset
644 builder sub, and must be called in void context.
645 all_items($CHECK1, $CHECK2, ...)
647 Add checks that apply to all items. You can put this anywhere in
648 the bag block, and can call it any number of times with any number
649 of arguments.
650 end()
652 Enforce that there are no more items after the last one specified.
653 etc()
655 Ignore any extra items found in the array. This is the opposite of
656 end(). This can be used anywhere in the bag builder, though
657 typically it is placed at the end.
658 ORDERED SUBSET BUILDER
660 Note: None of these are exported by default. You need to request them.
661 $check = subset {
663 item 'a';
664 item 'b';
665 item 'c';
666 # Doesn't matter if the array has 'd', the check will skip past any
668 # unknown items until it finds the next one in our subset.
669 item 'e';
671 item 'f';
672 };
673 $check = subset { ... }
675 item $VAL
676 item $CHECK
677 Add an expected item to the subset.
678 You can provide any value to check in $VAL, or you can provide any
680 valid check object.
681 Note: Items MUST be added in order.
683 Note: This function can only be used inside an array, bag or subset
685 builder sub, and must be called in void context.
686 META BUILDER
688 Note: None of these are exported by default. You need to request them.
689 my $check = meta {
691 prop blessed => 'My::Module'; # Ensure value is blessed as our package
692 prop reftype => 'HASH'; # Ensure value is a blessed hash
693 prop isa => 'My::Base'; # Ensure value is an instance of our class
694 prop size => 4; # Check the number of hash keys
695 prop this => ...; # Check the item itself
696 };
697 meta { ... }
699 meta_check { ... }
700 Build a meta check. If you are using Moose then the meta() function
701 would conflict with the one exported by Moose, in such cases
702 meta_check() is available. Neither is exported by default.
703 prop $NAME => $VAL
705 prop $NAME => $CHECK
706 Check the property specified by $name against the value or check.
707 Valid properties are:
709 'blessed'
711 What package (if any) the thing is blessed as.
712 'reftype'
714 Reference type (if any) the thing is.
715 'isa'
717 What class the thing is an instance of.
718 'this'
720 The thing itself.
721 'size'
723 For array references this returns the number of elements. For
724 hashes this returns the number of keys. For everything else
725 this returns undef.
726 OBJECT BUILDER
728 Note: None of these are exported by default. You need to request them.
729 my $check = object {
731 call foo => 1; # Call the 'foo' method, check the result.
732 # Call the specified sub-ref as a method on the object, check the
734 # result. This is useful for wrapping methods that return multiple
735 # values.
736 call sub { [ shift->get_list ] } => [...];
737 # This can be used to ensure a method does not exist.
739 call nope => DNE();
740 # Check the hash key 'foo' of the underlying reference, this only works
742 # on blessed hashes.
743 field foo => 1;
744 # Check the value of index 4 on the underlying reference, this only
746 # works on blessed arrays.
747 item 4 => 'foo';
748 # Check the meta-property 'blessed' of the object.
750 prop blessed => 'My::Module';
751 # Check if the object is an instance of the specified class.
753 prop isa => 'My::Base';
754 # Ensure only the specified hash keys or array indexes are present in
756 # the underlying hash. Has no effect on meta-property checks or method
757 # checks.
758 end();
759 };
760 $check = object { ... }
762 Specify an object check for use in comparisons.
763 call $METHOD_NAME => $RESULT
765 call $METHOD_NAME => $CHECK
766 call [$METHOD_NAME, @METHOD_ARGS] => $RESULT
767 call [$METHOD_NAME, @METHOD_ARGS] => $CHECK
768 call sub { ... }, $RESULT
769 call sub { ... }, $CHECK
770 Call the specified method (or coderef) and verify the result. If
771 you pass an arrayref, the first element must be the method name,
772 the others are the arguments it will be called with.
773 The coderef form is useful if you need to do something more
775 complex.
776 my $ref = sub {
778 local $SOME::GLOBAL::THING = 3;
779 return [shift->get_values_for('thing')];
780 };
781 call $ref => ...;
783 call_list $METHOD_NAME => $RESULT
785 call_list $METHOD_NAME => $CHECK
786 call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT
787 call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK
788 call_list sub { ... }, $RESULT
789 call_list sub { ... }, $CHECK
790 Same as "call", but the method is invoked in list context, and the
791 result is always an arrayref.
792 call_list get_items => [ ... ];
794 call_hash $METHOD_NAME => $RESULT
796 call_hash $METHOD_NAME => $CHECK
797 call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT
798 call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK
799 call_hash sub { ... }, $RESULT
800 call_hash sub { ... }, $CHECK
801 Same as "call", but the method is invoked in list context, and the
802 result is always a hashref. This will warn if the method returns an
803 odd number of values.
804 call_hash get_items => { ... };
806 field $NAME => $VAL
808 Works just like it does for hash checks.
809 item $VAL
811 item $IDX, $VAL
812 Works just like it does for array checks.
813 prop $NAME => $VAL
815 prop $NAME => $CHECK
816 Check the property specified by $name against the value or check.
817 Valid properties are:
819 'blessed'
821 What package (if any) the thing is blessed as.
822 'reftype'
824 Reference type (if any) the thing is.
825 'isa'
827 What class the thing is an instance of.
828 'this'
830 The thing itself.
831 'size'
833 For array references this returns the number of elements. For
834 hashes this returns the number of keys. For everything else
835 this returns undef.
836 DNE()
838 Can be used with "item", or "field" to ensure the hash field or
839 array index does not exist. Can also be used with "call" to ensure
840 a method does not exist.
841 end()
843 Turn on strict array/hash checking, ensuring that no extra
844 keys/indexes are present.
845 etc()
847 Ignore any extra items found in the hash/array. This is the
848 opposite of end(). This can be used anywhere in the builder,
849 though typically it is placed at the end.
850 EVENT BUILDERS
852 Note: None of these are exported by default. You need to request them.
853 Check that we got an event of a specified type:
855 my $check = event 'Ok';
857 Check for details about the event:
859 my $check = event Ok => sub {
861 # Check for a failure
862 call pass => 0;
863 # Effective pass after TODO/SKIP are accounted for.
865 call effective_pass => 1;
866 # Check the diagnostics
868 call diag => [ match qr/Failed test foo/ ];
869 # Check the file the event reports to
871 prop file => 'foo.t';
872 # Check the line number the event reports o
874 prop line => '42';
875 # You can check the todo/skip values as well:
877 prop skip => 'broken';
878 prop todo => 'fixme';
879 # Thread-id and process-id where event was generated
881 prop tid => 123;
882 prop pid => 123;
883 };
884 You can also provide a fully qualified event package with the '+'
886 prefix:
887 my $check = event '+My::Event' => sub { ... }
889 You can also provide a hashref instead of a sub to directly check hash
891 values of the event:
892 my $check = event Ok => { pass => 1, ... };
894 USE IN OTHER BUILDERS
896 You can use these all in other builders, simply use them in void
898 context to have their value(s) appended to the build.
899 my $check = array {
901 event Ok => { ... };
902 event Note => { ... };
903 fail_events Ok => { pass => 0 };
905 # Get a Diag for free.
906 };
907 SPECIFICS
909 $check = event $TYPE;
911 $check = event $TYPE => sub { ... };
912 $check = event $TYPE => { ... };
913 This works just like an object builder. In addition to supporting
914 everything the object check supports, you also have to specify the
915 event type, and many extra meta-properties are available.
916 Extra properties are:
918 'file'
920 File name to which the event reports (for use in diagnostics).
921 'line'
923 Line number to which the event reports (for use in
924 diagnostics).
925 'package'
927 Package to which the event reports (for use in diagnostics).
928 'subname'
930 Sub that was called to generate the event (example: ok()).
931 'skip'
933 Set to the skip value if the result was generated by skipping
934 tests.
935 'todo'
937 Set to the todo value if TODO was set when the event was
938 generated.
939 'trace'
941 The "at file foo.t line 42" string that will be used in
942 diagnostics.
943 'tid'
945 Thread ID in which the event was generated.
946 'pid'
948 Process ID in which the event was generated.
949 NOTE: Event checks have an implicit etc() added. This means you
951 need to use end() if you want to fail on unexpected hash keys or
952 array indexes. This implicit etc() extends to all forms, including
953 builder, hashref, and no argument.
954 @checks = fail_events $TYPE;
956 @checks = fail_events $TYPE => sub { ... };
957 @checks = fail_events $TYPE => { ... };
958 Just like event() documented above. The difference is that this
959 produces two events, the one you specify, and a "Diag" after it.
960 There are no extra checks in the Diag.
961 Use this to validate a simple failure where you do not want to be
963 bothered with the default diagnostics. It only adds a single Diag
964 check, so if your failure has custom diagnostics you will need to
965 add checks for them.
966
968 The source code repository for Test2-Suite can be found at
969 https://github.com/Test-More/Test2-Suite/.
970
972 Chad Granum <exodist@cpan.org>
973
975 Chad Granum <exodist@cpan.org>
976
978 Copyright 2018 Chad Granum <exodist@cpan.org>.
979 This program is free software; you can redistribute it and/or modify it
981 under the same terms as Perl itself.
982 See http://dev.perl.org/licenses/
984perl v5.38.0 2023-07-21 Test2::Tools::Compare(3)