1Test2::Tools::Compare(3U)ser Contributed Perl DocumentatiToenst2::Tools::Compare(3)
2
3
4

NAME

6       Test2::Tools::Compare - Tools for comparing deep data structures.
7

DESCRIPTION

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

SYNOPSIS

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

COMPARISON TOOLS

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             is($near_val, float($val, precision = 4), "Near 4 decimal digits");
324
325           Otherwise, the check will be made within a range of +/-
326           'tolerance', with a default 'tolerance' of 1e-08.
327
328             is( $near_val, float($val, tolerance = 0.01), "Almost there...");
329
330           See also "within" and "rounded".
331
332       $check = !float ...;
333           Verify that the value is not approximately equal to the given
334           number.
335
336           If a 'precision' parameter is specified, both operands will be
337           rounded to 'precision' number of fractional decimal digits and
338           compared with "eq".
339
340           Otherwise, the check will be made within a range of +/-
341           'tolerance', with a default 'tolerance' of 1e-08.
342
343           See also "!within" and "!rounded".
344
345       $check = within($num, $tolerance);
346           Verify that the value approximately matches the given number,
347           within a range of +/- $tolerance.  Compared using the "=="
348           operator.
349
350           $tolerance is optional and defaults to 1e-08.
351
352       $check = !within($num, $tolerance);
353           Verify that the value does not approximately match the given number
354           within a range of +/- $tolerance.  Compared using the "!="
355           operator.
356
357           $tolerance is optional and defaults to 1e-08.
358
359       $check = rounded($num, $precision);
360           Verify that the value approximately matches the given number, when
361           both are rounded to $precision number of fractional digits.
362           Compared using the "eq" operator.
363
364       $check = !rounded($num, $precision);
365           Verify that the value does not approximately match the given
366           number, when both are rounded to $precision number of fractional
367           digits. Compared using the "ne" operator.
368
369       $check = bool ...;
370           Verify the value has the same boolean value as the given argument
371           (XNOR).
372
373       $check = !bool ...;
374           Verify the value has a different boolean value from the given
375           argument (XOR).
376
377       $check = match qr/.../
378       $check = !mismatch qr/.../
379           Verify that the value matches the regex pattern. This form of
380           pattern check will NOT stringify references being checked.
381
382           Note: "!mismatch()" is documented for completion, please do not use
383           it.
384
385       $check = !match qr/.../
386       $check = mismatch qr/.../
387           Verify that the value does not match the regex pattern. This form
388           of pattern check will NOT stringify references being checked.
389
390           Note: "mismatch()" was created before overloading of "!" for
391           "match()" was a thing.
392
393       $check = validator(sub{ ... })
394       $check = validator($NAME => sub{ ... })
395       $check = validator($OP, $NAME, sub{ ... })
396           The coderef is the only required argument. The coderef should check
397           that the value is what you expect and return a boolean true or
398           false. Optionally, you can specify a name and operator that are
399           used in diagnostics. They are also provided to the sub itself as
400           named parameters.
401
402           Check the value using this sub. The sub gets the value in $_, and
403           it receives the value and several other items as named parameters.
404
405               my $check = validator(sub {
406                   my %params = @_;
407
408                   # These both work:
409                   my $got = $_;
410                   my $got = $params{got};
411
412                   # Check if a value exists at all
413                   my $exists = $params{exists}
414
415                   # What $OP (if any) did we specify when creating the validator
416                   my $operator = $params{operator};
417
418                   # What name (if any) did we specify when creating the validator
419                   my $name = $params{name};
420
421                   ...
422
423                   return $bool;
424               }
425
426       $check = exact_ref($ref)
427           Check that the value is exactly the same reference as the one
428           provided.
429
430   SET BUILDERS
431       Note: None of these are exported by default. You need to request them.
432
433       my $check = check_set($check1, $check2, ...)
434           Check that the value matches ALL of the specified checks.
435
436       my $check = in_set($check1, $check2, ...)
437           Check that the value matches ONE OR MORE of the specified checks.
438
439       not_in_set($check1, $check2, ...)
440           Check that the value DOES NOT match ANY of the specified checks.
441
442       check $thing
443           Check that the value matches the specified thing.
444
445   HASH BUILDER
446       Note: None of these are exported by default. You need to request them.
447
448           $check = hash {
449               field foo => 1;
450               field bar => 2;
451
452               # Ensure the 'baz' keys does not even exist in the hash.
453               field baz => DNE();
454
455               # Ensure the key exists, but is set to undef
456               field bat => undef;
457
458               # Any check can be used
459               field boo => $check;
460
461               # Set checks that apply to all keys or values. Can be done multiple
462               # times, and each call can define multiple checks, all will be run.
463               all_vals match qr/a/, match qr/b/;    # All keys must have an 'a' and a 'b'
464               all_keys match qr/x/;                 # All keys must have an 'x'
465
466               ...
467
468               end(); # optional, enforces that no other keys are present.
469           };
470
471       $check = hash { ... }
472           This is used to define a hash check.
473
474       field $NAME => $VAL
475       field $NAME => $CHECK
476           Specify a field check. This will check the hash key specified by
477           $NAME and ensure it matches the value in $VAL. You can put any
478           valid check in $VAL, such as the result of another call to "array {
479           ... }", "DNE()", etc.
480
481           Note: This function can only be used inside a hash builder sub, and
482           must be called in void context.
483
484       all_keys($CHECK1, $CHECK2, ...)
485           Add checks that apply to all keys. You can put this anywhere in the
486           hash block, and can call it any number of times with any number of
487           arguments.
488
489       all_vals($CHECK1, $CHECK2, ...)
490       all_values($CHECK1, $CHECK2, ...)
491           Add checks that apply to all values. You can put this anywhere in
492           the hash block, and can call it any number of times with any number
493           of arguments.
494
495       end()
496           Enforce that no keys are found in the hash other than those
497           specified. This is essentially the "use strict" of a hash check.
498           This can be used anywhere in the hash builder, though typically it
499           is placed at the end.
500
501       etc()
502           Ignore any extra keys found in the hash. This is the opposite of
503           "end()".  This can be used anywhere in the hash builder, though
504           typically it is placed at the end.
505
506       DNE()
507           This is a handy check that can be used with "field()" to ensure
508           that a field (D)oes (N)ot (E)xist.
509
510               field foo => DNE();
511
512   ARRAY BUILDER
513       Note: None of these are exported by default. You need to request them.
514
515           $check = array {
516               # Uses the next index, in this case index 0;
517               item 'a';
518
519               # Gets index 1 automatically
520               item 'b';
521
522               # Specify the index
523               item 2 => 'c';
524
525               # We skipped index 3, which means we don't care what it is.
526               item 4 => 'e';
527
528               # Gets index 5.
529               item 'f';
530
531               # Remove any REMAINING items that contain 0-9.
532               filter_items { grep {!m/[0-9]/} @_ };
533
534               # Set checks that apply to all items. Can be done multiple times, and
535               # each call can define multiple checks, all will be run.
536               all_items match qr/a/, match qr/b/;
537               all_items match qr/x/;
538
539               # Of the remaining items (after the filter is applied) the next one
540               # (which is now index 6) should be 'g'.
541               item 6 => 'g';
542
543               item 7 => DNE; # Ensure index 7 does not exist.
544
545               end(); # Ensure no other indexes exist.
546           };
547
548       $check = array { ... }
549       item $VAL
550       item $CHECK
551       item $IDX, $VAL
552       item $IDX, $CHECK
553           Add an expected item to the array. If $IDX is not specified it will
554           automatically calculate it based on the last item added. You can
555           skip indexes, which means you do not want them to be checked.
556
557           You can provide any value to check in $VAL, or you can provide any
558           valid check object.
559
560           Note: Items MUST be added in order.
561
562           Note: This function can only be used inside an array, bag or subset
563           builder sub, and must be called in void context.
564
565       filter_items { my @remaining = @_; ...; return @filtered }
566           This function adds a filter, all items remaining in the array from
567           the point the filter is reached will be passed into the filter sub
568           as arguments, the sub should return only the items that should be
569           checked.
570
571           Note: This function can only be used inside an array builder sub,
572           and must be called in void context.
573
574       all_items($CHECK1, $CHECK2, ...)
575           Add checks that apply to all items. You can put this anywhere in
576           the array block, and can call it any number of times with any
577           number of arguments.
578
579       end()
580           Enforce that there are no indexes after the last one specified.
581           This will not force checking of skipped indexes.
582
583       etc()
584           Ignore any extra items found in the array. This is the opposite of
585           "end()".  This can be used anywhere in the array builder, though
586           typically it is placed at the end.
587
588       DNE()
589           This is a handy check that can be used with "item()" to ensure that
590           an index (D)oes (N)ot (E)xist.
591
592               item 5 => DNE();
593
594   BAG BUILDER
595       Note: None of these are exported by default. You need to request them.
596
597           $check = bag {
598               item 'a';
599               item 'b';
600
601               end(); # Ensure no other elements exist.
602           };
603
604       A bag is like an array, but we don't care about the order of the items.
605       In the example, $check would match both "['a','b']" and "['b','a']".
606
607       $check = bag { ... }
608       item $VAL
609       item $CHECK
610           Add an expected item to the bag.
611
612           You can provide any value to check in $VAL, or you can provide any
613           valid check object.
614
615           Note: This function can only be used inside an array, bag or subset
616           builder sub, and must be called in void context.
617
618       all_items($CHECK1, $CHECK2, ...)
619           Add checks that apply to all items. You can put this anywhere in
620           the bag block, and can call it any number of times with any number
621           of arguments.
622
623       end()
624           Enforce that there are no more items after the last one specified.
625
626       etc()
627           Ignore any extra items found in the array. This is the opposite of
628           "end()".  This can be used anywhere in the bag builder, though
629           typically it is placed at the end.
630
631   ORDERED SUBSET BUILDER
632       Note: None of these are exported by default. You need to request them.
633
634           $check = subset {
635               item 'a';
636               item 'b';
637               item 'c';
638
639               # Doesn't matter if the array has 'd', the check will skip past any
640               # unknown items until it finds the next one in our subset.
641
642               item 'e';
643               item 'f';
644           };
645
646       $check = subset { ... }
647       item $VAL
648       item $CHECK
649           Add an expected item to the subset.
650
651           You can provide any value to check in $VAL, or you can provide any
652           valid check object.
653
654           Note: Items MUST be added in order.
655
656           Note: This function can only be used inside an array, bag or subset
657           builder sub, and must be called in void context.
658
659   META BUILDER
660       Note: None of these are exported by default. You need to request them.
661
662           my $check = meta {
663               prop blessed => 'My::Module'; # Ensure value is blessed as our package
664               prop reftype => 'HASH';       # Ensure value is a blessed hash
665               prop size    => 4;            # Check the number of hash keys
666               prop this    => ...;          # Check the item itself
667           };
668
669       meta { ... }
670       meta_check { ... }
671           Build a meta check. If you are using Moose then the "meta()"
672           function would conflict with the one exported by Moose, in such
673           cases "meta_check()" is available. Neither is exported by default.
674
675       prop $NAME => $VAL
676       prop $NAME => $CHECK
677           Check the property specified by $name against the value or check.
678
679           Valid properties are:
680
681           'blessed'
682               What package (if any) the thing is blessed as.
683
684           'reftype'
685               Reference type (if any) the thing is.
686
687           'this'
688               The thing itself.
689
690           'size'
691               For array references this returns the number of elements. For
692               hashes this returns the number of keys. For everything else
693               this returns undef.
694
695   OBJECT BUILDER
696       Note: None of these are exported by default. You need to request them.
697
698           my $check = object {
699               call foo => 1; # Call the 'foo' method, check the result.
700
701               # Call the specified sub-ref as a method on the object, check the
702               # result. This is useful for wrapping methods that return multiple
703               # values.
704               call sub { [ shift->get_list ] } => [...];
705
706               # This can be used to ensure a method does not exist.
707               call nope => DNE();
708
709               # Check the hash key 'foo' of the underlying reference, this only works
710               # on blessed hashes.
711               field foo => 1;
712
713               # Check the value of index 4 on the underlying reference, this only
714               # works on blessed arrays.
715               item 4 => 'foo';
716
717               # Check the meta-property 'blessed' of the object.
718               prop blessed => 'My::Module';
719
720               # Ensure only the specified hash keys or array indexes are present in
721               # the underlying hash. Has no effect on meta-property checks or method
722               # checks.
723               end();
724           };
725
726       $check = object { ... }
727           Specify an object check for use in comparisons.
728
729       call $METHOD_NAME => $RESULT
730       call $METHOD_NAME => $CHECK
731       call [$METHOD_NAME, @METHOD_ARGS] => $RESULT
732       call [$METHOD_NAME, @METHOD_ARGS] => $CHECK
733       call sub { ... }, $RESULT
734       call sub { ... }, $CHECK
735           Call the specified method (or coderef) and verify the result. If
736           you pass an arrayref, the first element must be the method name,
737           the others are the arguments it will be called with.
738
739           The coderef form is useful if you need to do something more
740           complex.
741
742               my $ref = sub {
743                 local $SOME::GLOBAL::THING = 3;
744                 return [shift->get_values_for('thing')];
745               };
746
747               call $ref => ...;
748
749       call_list $METHOD_NAME => $RESULT
750       call_list $METHOD_NAME => $CHECK
751       call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT
752       call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK
753       call_list sub { ... }, $RESULT
754       call_list sub { ... }, $CHECK
755           Same as "call", but the method is invoked in list context, and the
756           result is always an arrayref.
757
758               call_list get_items => [ ... ];
759
760       call_hash $METHOD_NAME => $RESULT
761       call_hash $METHOD_NAME => $CHECK
762       call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT
763       call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK
764       call_hash sub { ... }, $RESULT
765       call_hash sub { ... }, $CHECK
766           Same as "call", but the method is invoked in list context, and the
767           result is always a hashref. This will warn if the method returns an
768           odd number of values.
769
770               call_hash get_items => { ... };
771
772       field $NAME => $VAL
773           Works just like it does for hash checks.
774
775       item $VAL
776       item $IDX, $VAL
777           Works just like it does for array checks.
778
779       prop $NAME => $VAL
780       prop $NAME => $CHECK
781           Check the property specified by $name against the value or check.
782
783           Valid properties are:
784
785           'blessed'
786               What package (if any) the thing is blessed as.
787
788           'reftype'
789               Reference type (if any) the thing is.
790
791           'this'
792               The thing itself.
793
794           'size'
795               For array references this returns the number of elements. For
796               hashes this returns the number of keys. For everything else
797               this returns undef.
798
799       DNE()
800           Can be used with "item", or "field" to ensure the hash field or
801           array index does not exist. Can also be used with "call" to ensure
802           a method does not exist.
803
804       end()
805           Turn on strict array/hash checking, ensuring that no extra
806           keys/indexes are present.
807
808       etc()
809           Ignore any extra items found in the hash/array. This is the
810           opposite of "end()".  This can be used anywhere in the builder,
811           though typically it is placed at the end.
812
813   EVENT BUILDERS
814       Note: None of these are exported by default. You need to request them.
815
816       Check that we got an event of a specified type:
817
818           my $check = event 'Ok';
819
820       Check for details about the event:
821
822           my $check = event Ok => sub {
823               # Check for a failure
824               call pass => 0;
825
826               # Effective pass after TODO/SKIP are accounted for.
827               call effective_pass => 1;
828
829               # Check the diagnostics
830               call diag => [ match qr/Failed test foo/ ];
831
832               # Check the file the event reports to
833               prop file => 'foo.t';
834
835               # Check the line number the event reports o
836               prop line => '42';
837
838               # You can check the todo/skip values as well:
839               prop skip => 'broken';
840               prop todo => 'fixme';
841
842               # Thread-id and process-id where event was generated
843               prop tid => 123;
844               prop pid => 123;
845           };
846
847       You can also provide a fully qualified event package with the '+'
848       prefix:
849
850           my $check = event '+My::Event' => sub { ... }
851
852       You can also provide a hashref instead of a sub to directly check hash
853       values of the event:
854
855           my $check = event Ok => { pass => 1, ... };
856
857       USE IN OTHER BUILDERS
858
859       You can use these all in other builders, simply use them in void
860       context to have their value(s) appended to the build.
861
862           my $check = array {
863               event Ok => { ... };
864               event Note => { ... };
865
866               fail_events Ok => { pass => 0 };
867               # Get a Diag for free.
868           };
869
870       SPECIFICS
871
872       $check = event $TYPE;
873       $check = event $TYPE => sub { ... };
874       $check = event $TYPE => { ... };
875           This works just like an object builder. In addition to supporting
876           everything the object check supports, you also have to specify the
877           event type, and many extra meta-properties are available.
878
879           Extra properties are:
880
881           'file'
882               File name to which the event reports (for use in diagnostics).
883
884           'line'
885               Line number to which the event reports (for use in
886               diagnostics).
887
888           'package'
889               Package to which the event reports (for use in diagnostics).
890
891           'subname'
892               Sub that was called to generate the event (example: "ok()").
893
894           'skip'
895               Set to the skip value if the result was generated by skipping
896               tests.
897
898           'todo'
899               Set to the todo value if TODO was set when the event was
900               generated.
901
902           'trace'
903               The "at file foo.t line 42" string that will be used in
904               diagnostics.
905
906           'tid'
907               Thread ID in which the event was generated.
908
909           'pid'
910               Process ID in which the event was generated.
911
912           NOTE: Event checks have an implicit "etc()" added. This means you
913           need to use "end()" if you want to fail on unexpected hash keys or
914           array indexes. This implicit "etc()" extends to all forms,
915           including builder, hashref, and no argument.
916
917       @checks = fail_events $TYPE;
918       @checks = fail_events $TYPE => sub { ... };
919       @checks = fail_events $TYPE => { ... };
920           Just like "event()" documented above. The difference is that this
921           produces two events, the one you specify, and a "Diag" after it.
922           There are no extra checks in the Diag.
923
924           Use this to validate a simple failure where you do not want to be
925           bothered with the default diagnostics. It only adds a single Diag
926           check, so if your failure has custom diagnostics you will need to
927           add checks for them.
928

SOURCE

930       The source code repository for Test2-Suite can be found at
931       https://github.com/Test-More/Test2-Suite/.
932

MAINTAINERS

934       Chad Granum <exodist@cpan.org>
935

AUTHORS

937       Chad Granum <exodist@cpan.org>
938
940       Copyright 2018 Chad Granum <exodist@cpan.org>.
941
942       This program is free software; you can redistribute it and/or modify it
943       under the same terms as Perl itself.
944
945       See http://dev.perl.org/licenses/
946
947
948
949perl v5.30.1                      2020-01-31          Test2::Tools::Compare(3)
Impressum