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 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

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 DF E DNE FDNE U L
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 there
162           is a mismatch.
163
164       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
171   QUICK CHECKS
172       Note: None of these are exported by default. You need to request them.
173
174       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
178       Example:
179
180           is($foo, T(), '$foo has a true value');
181
182       $check = T()
183           This verifies that the value in the corresponding $got structure is
184           true, any true value will do.
185
186               is($foo, T(), '$foo has a true value');
187
188               is(
189                   { a => 'xxx' },
190                   { a => T() },
191                   "The 'a' key is true"
192               );
193
194       $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
198               is($foo, F(), '$foo has a false value');
199
200               is(
201                   { a => 0 },
202                   { a => F() },
203                   "The 'a' key is false"
204               );
205
206           It is important to note that a nonexistent value does not count as
207           false. This check will generate a failing test result:
208
209               is(
210                   { a => 1 },
211                   { a => 1, b => F() },
212                   "The 'b' key is false"
213               );
214
215           This will produce the following output:
216
217               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
226           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
231           If you want to check for false and/or DNE use the FDNE() check.
232
233       $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
237           This will pass:
238
239               is('foo', D(), 'foo is defined');
240
241           This will fail:
242
243               is(undef, D(), 'foo is defined');
244
245       $check = U()
246           This is to verify that the value in the $got structure is
247           undefined.
248
249           This will pass:
250
251               is(undef, U(), 'not defined');
252
253           This will fail:
254
255               is('foo', U(), 'not defined');
256
257       $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
261           This will pass:
262
263               is(0, DF(), 'foo is defined but false');
264
265           These will fail:
266
267               is(undef, DF(), 'foo is defined but false');
268               is(1, DF(), 'foo is defined but false');
269
270       $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
275           These pass:
276
277               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
280           These will fail:
281
282               is(['a', 'b'], ['a', 'b', E()], "Third item exists");
283               is({a => 1}, {a => 1, b => E()}, "'b' key exists");
284
285       $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
290           These pass:
291
292               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
295           These will fail:
296
297               is(['a', 'b', 'c'], ['a', 'b', DNE()], "No third item");
298               is({a => 1, b => 2}, {a => 1, b => DNE()}, "No 'b' key");
299
300       $check = FDNE()
301           This is a combination of F() and DNE(). This will pass for a false
302           value, or a nonexistent value.
303
304       $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
309           These will pass:
310
311               is('foo', L(), 'value is defined and has length');
312               is([],    L(), 'value is defined and has length');
313
314           These will fail:
315
316               is(undef, L(), 'value is defined and has length');
317               is('',    L(), 'value is defined and has length');
318
319   VALUE SPECIFICATIONS
320       Note: None of these are exported by default. You need to request them.
321
322       $check = string "..."
323           Verify that the value matches the given string using the "eq"
324           operator.
325
326       $check = !string "..."
327           Verify that the value does not match the given string using the
328           "ne" operator.
329
330       $check = number ...;
331           Verify that the value matches the given number using the "=="
332           operator.
333
334       $check = !number ...;
335           Verify that the value does not match the given number using the
336           "!=" operator.
337
338       $check = float ...;
339           Verify that the value is approximately equal to the given number.
340
341           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
345             is($near_val, float($val, precision => 4), "Near 4 decimal digits");
346
347           Otherwise, the check will be made within a range of +/-
348           'tolerance', with a default 'tolerance' of 1e-08.
349
350             is( $near_val, float($val, tolerance => 0.01), "Almost there...");
351
352           See also "within" and "rounded".
353
354       $check = !float ...;
355           Verify that the value is not approximately equal to the given
356           number.
357
358           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
362           Otherwise, the check will be made within a range of +/-
363           'tolerance', with a default 'tolerance' of 1e-08.
364
365           See also "!within" and "!rounded".
366
367       $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
372           $tolerance is optional and defaults to 1e-08.
373
374       $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
379           $tolerance is optional and defaults to 1e-08.
380
381       $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
386       $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
391       $check = bool ...;
392           Verify the value has the same boolean value as the given argument
393           (XNOR).
394
395       $check = !bool ...;
396           Verify the value has a different boolean value from the given
397           argument (XOR).
398
399       $check = check_isa ...;
400           Verify the value is an instance of the given class name.
401
402       $check = !check_isa ...;
403           Verify the value is not an instance of the given class name.
404
405       $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
410           Note: "!mismatch()" is documented for completion, please do not use
411           it.
412
413       $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
418           Note: mismatch() was created before overloading of "!" for match()
419           was a thing.
420
421       $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
430           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
433               my $check = validator(sub {
434                   my %params = @_;
435
436                   # These both work:
437                   my $got = $_;
438                   my $got = $params{got};
439
440                   # Check if a value exists at all
441                   my $exists = $params{exists}
442
443                   # What $OP (if any) did we specify when creating the validator
444                   my $operator = $params{operator};
445
446                   # What name (if any) did we specify when creating the validator
447                   my $name = $params{name};
448
449                   ...
450
451                   return $bool;
452               }
453
454       $check = exact_ref($ref)
455           Check that the value is exactly the same reference as the one
456           provided.
457
458   SET BUILDERS
459       Note: None of these are exported by default. You need to request them.
460
461       my $check = check_set($check1, $check2, ...)
462           Check that the value matches ALL of the specified checks.
463
464       my $check = in_set($check1, $check2, ...)
465           Check that the value matches ONE OR MORE of the specified checks.
466
467       not_in_set($check1, $check2, ...)
468           Check that the value DOES NOT match ANY of the specified checks.
469
470       check $thing
471           Check that the value matches the specified thing.
472
473   HASH BUILDER
474       Note: None of these are exported by default. You need to request them.
475
476           $check = hash {
477               field foo => 1;
478               field bar => 2;
479
480               # Ensure the 'baz' keys does not even exist in the hash.
481               field baz => DNE();
482
483               # Ensure the key exists, but is set to undef
484               field bat => undef;
485
486               # Any check can be used
487               field boo => $check;
488
489               # 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
494               ...
495
496               end(); # optional, enforces that no other keys are present.
497           };
498
499       $check = hash { ... }
500           This is used to define a hash check.
501
502       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
509           Note: This function can only be used inside a hash builder sub, and
510           must be called in void context.
511
512       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
517       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
523       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
529       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
534       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
538               field foo => DNE();
539
540   ARRAY BUILDER
541       Note: None of these are exported by default. You need to request them.
542
543           $check = array {
544               # Uses the next index, in this case index 0;
545               item 'a';
546
547               # Gets index 1 automatically
548               item 'b';
549
550               # Specify the index
551               item 2 => 'c';
552
553               # We skipped index 3, which means we don't care what it is.
554               item 4 => 'e';
555
556               # Gets index 5.
557               item 'f';
558
559               # Remove any REMAINING items that contain 0-9.
560               filter_items { grep {!m/[0-9]/} @_ };
561
562               # 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
567               # 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
571               item 7 => DNE; # Ensure index 7 does not exist.
572
573               end(); # Ensure no other indexes exist.
574           };
575
576       $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
585           You can provide any value to check in $VAL, or you can provide any
586           valid check object.
587
588           Note: Items MUST be added in order.
589
590           Note: This function can only be used inside an array, bag or subset
591           builder sub, and must be called in void context.
592
593       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
599           Note: This function can only be used inside an array builder sub,
600           and must be called in void context.
601
602       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
607       end()
608           Enforce that there are no indexes after the last one specified.
609           This will not force checking of skipped indexes.
610
611       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
616       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
620               item 5 => DNE();
621
622   BAG BUILDER
623       Note: None of these are exported by default. You need to request them.
624
625           $check = bag {
626               item 'a';
627               item 'b';
628
629               end(); # Ensure no other elements exist.
630           };
631
632       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
635       $check = bag { ... }
636       item $VAL
637       item $CHECK
638           Add an expected item to the bag.
639
640           You can provide any value to check in $VAL, or you can provide any
641           valid check object.
642
643           Note: This function can only be used inside an array, bag or subset
644           builder sub, and must be called in void context.
645
646       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
651       end()
652           Enforce that there are no more items after the last one specified.
653
654       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
659   ORDERED SUBSET BUILDER
660       Note: None of these are exported by default. You need to request them.
661
662           $check = subset {
663               item 'a';
664               item 'b';
665               item 'c';
666
667               # 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
670               item 'e';
671               item 'f';
672           };
673
674       $check = subset { ... }
675       item $VAL
676       item $CHECK
677           Add an expected item to the subset.
678
679           You can provide any value to check in $VAL, or you can provide any
680           valid check object.
681
682           Note: Items MUST be added in order.
683
684           Note: This function can only be used inside an array, bag or subset
685           builder sub, and must be called in void context.
686
687   META BUILDER
688       Note: None of these are exported by default. You need to request them.
689
690           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
698       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
704       prop $NAME => $VAL
705       prop $NAME => $CHECK
706           Check the property specified by $name against the value or check.
707
708           Valid properties are:
709
710           'blessed'
711               What package (if any) the thing is blessed as.
712
713           'reftype'
714               Reference type (if any) the thing is.
715
716           'isa'
717               What class the thing is an instance of.
718
719           'this'
720               The thing itself.
721
722           '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
727   OBJECT BUILDER
728       Note: None of these are exported by default. You need to request them.
729
730           my $check = object {
731               call foo => 1; # Call the 'foo' method, check the result.
732
733               # 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
738               # This can be used to ensure a method does not exist.
739               call nope => DNE();
740
741               # Check the hash key 'foo' of the underlying reference, this only works
742               # on blessed hashes.
743               field foo => 1;
744
745               # Check the value of index 4 on the underlying reference, this only
746               # works on blessed arrays.
747               item 4 => 'foo';
748
749               # Check the meta-property 'blessed' of the object.
750               prop blessed => 'My::Module';
751
752               # Check if the object is an instance of the specified class.
753               prop isa => 'My::Base';
754
755               # 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
761       $check = object { ... }
762           Specify an object check for use in comparisons.
763
764       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
774           The coderef form is useful if you need to do something more
775           complex.
776
777               my $ref = sub {
778                 local $SOME::GLOBAL::THING = 3;
779                 return [shift->get_values_for('thing')];
780               };
781
782               call $ref => ...;
783
784       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
793               call_list get_items => [ ... ];
794
795       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
805               call_hash get_items => { ... };
806
807       field $NAME => $VAL
808           Works just like it does for hash checks.
809
810       item $VAL
811       item $IDX, $VAL
812           Works just like it does for array checks.
813
814       prop $NAME => $VAL
815       prop $NAME => $CHECK
816           Check the property specified by $name against the value or check.
817
818           Valid properties are:
819
820           'blessed'
821               What package (if any) the thing is blessed as.
822
823           'reftype'
824               Reference type (if any) the thing is.
825
826           'isa'
827               What class the thing is an instance of.
828
829           'this'
830               The thing itself.
831
832           '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
837       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
842       end()
843           Turn on strict array/hash checking, ensuring that no extra
844           keys/indexes are present.
845
846       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
851   EVENT BUILDERS
852       Note: None of these are exported by default. You need to request them.
853
854       Check that we got an event of a specified type:
855
856           my $check = event 'Ok';
857
858       Check for details about the event:
859
860           my $check = event Ok => sub {
861               # Check for a failure
862               call pass => 0;
863
864               # Effective pass after TODO/SKIP are accounted for.
865               call effective_pass => 1;
866
867               # Check the diagnostics
868               call diag => [ match qr/Failed test foo/ ];
869
870               # Check the file the event reports to
871               prop file => 'foo.t';
872
873               # Check the line number the event reports o
874               prop line => '42';
875
876               # You can check the todo/skip values as well:
877               prop skip => 'broken';
878               prop todo => 'fixme';
879
880               # Thread-id and process-id where event was generated
881               prop tid => 123;
882               prop pid => 123;
883           };
884
885       You can also provide a fully qualified event package with the '+'
886       prefix:
887
888           my $check = event '+My::Event' => sub { ... }
889
890       You can also provide a hashref instead of a sub to directly check hash
891       values of the event:
892
893           my $check = event Ok => { pass => 1, ... };
894
895       USE IN OTHER BUILDERS
896
897       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
900           my $check = array {
901               event Ok => { ... };
902               event Note => { ... };
903
904               fail_events Ok => { pass => 0 };
905               # Get a Diag for free.
906           };
907
908       SPECIFICS
909
910       $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
917           Extra properties are:
918
919           'file'
920               File name to which the event reports (for use in diagnostics).
921
922           'line'
923               Line number to which the event reports (for use in
924               diagnostics).
925
926           'package'
927               Package to which the event reports (for use in diagnostics).
928
929           'subname'
930               Sub that was called to generate the event (example: ok()).
931
932           'skip'
933               Set to the skip value if the result was generated by skipping
934               tests.
935
936           'todo'
937               Set to the todo value if TODO was set when the event was
938               generated.
939
940           'trace'
941               The "at file foo.t line 42" string that will be used in
942               diagnostics.
943
944           'tid'
945               Thread ID in which the event was generated.
946
947           'pid'
948               Process ID in which the event was generated.
949
950           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
955       @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
962           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

SOURCE

968       The source code repository for Test2-Suite can be found at
969       https://github.com/Test-More/Test2-Suite/.
970

MAINTAINERS

972       Chad Granum <exodist@cpan.org>
973

AUTHORS

975       Chad Granum <exodist@cpan.org>
976
978       Copyright 2018 Chad Granum <exodist@cpan.org>.
979
980       This program is free software; you can redistribute it and/or modify it
981       under the same terms as Perl itself.
982
983       See http://dev.perl.org/licenses/
984
985
986
987perl v5.38.0                      2023-07-21          Test2::Tools::Compare(3)
Impressum