1Test2::Compare(3) User Contributed Perl Documentation Test2::Compare(3)
2
6 Test2::Compare - Test2 extension for writing deep comparison tools.
7
9 This library is the driving force behind deep comparison tools such as
10 Test2::Tools::Compare::is() and
11 Test2::Tools::ClassicCompare::is_deeply().
12
14 package Test2::Tools::MyCheck;
15 use Test2::Compare::MyCheck;
17 use Test2::Compare qw/compare/;
18 sub MyCheck {
20 my ($got, $exp, $name, @diag) = @_;
21 my $ctx = context();
22 my $delta = compare($got, $exp, \&convert);
24 if ($delta) {
26 $ctx->fail($name, $delta->diag, @diag);
27 }
28 else {
29 $ctx->ok(1, $name);
30 }
31 $ctx->release;
33 return !$delta;
34 }
35 sub convert {
37 my $thing = shift;
38 return $thing if blessed($thing) && $thing->isa('Test2::Compare::MyCheck');
39 return Test2::Compare::MyCheck->new(stuff => $thing);
41 }
42 See Test2::Compare::Base for details about writing a custom check.
44
46 $delta = compare($got, $expect, \&convert)
47 This will compare the structures in $got with those in $expect, The
48 convert sub should convert vanilla structures inside $expect into
49 checks. If there are differences in the structures they will be
50 reported back as an Test2::Compare::Delta tree.
51 $build = get_build()
53 Get the current global build, if any.
54 push_build($build)
56 Set the current global build.
57 $build = pop_build($build)
59 Unset the current global build. This will throw an exception if the
60 build passed in is different from the current global.
61 build($class, sub { ... })
63 Run the provided codeblock with a new instance of $class as the
64 current build. Returns the new build.
65 $check = convert($thing)
67 $check = convert($thing, $config)
68 This convert function is used by strict_convert() and
69 relaxed_convert() under the hood. It can also be used as the basis
70 for other convert functions.
71 If you want to use it with a custom configuration you should wrap
73 it in another sub like so:
74 sub my_convert {
76 my $thing_to_convert = shift;
77 return convert(
78 $thing_to_convert,
79 { ... }
80 );
81 }
82 Or the short variant:
84 sub my_convert { convert($_[0], { ... }) }
86 There are several configuration options, here they are with the
88 default setting listed first:
89 implicit_end => 1
91 This option toggles array/hash boundaries. If this is true then
92 no extra hash keys or array indexes will be allowed. This
93 setting effects generated compare objects as well as any passed
94 in.
95 use_regex => 1
97 This option toggles regex matching. When true (default) regexes
98 are converted to checks such that values must match the regex.
99 When false regexes will be compared to see if they are
100 identical regexes.
101 use_code => 0
103 This option toggles code matching. When false (default)
104 coderefs in structures must be the same coderef as specified.
105 When true coderefs will be run to verify the value being
106 checked.
107 $check = strict_convert($thing)
109 Convert $thing to an Test2::Compare::* object. This will behave
110 strictly which means it uses these settings:
111 implicit_end => 1
113 Array bounds will be checked when this object is used in a
114 comparison. No unexpected hash keys can be present.
115 use_code => 0
117 Sub references will be compared as refs (IE are these sub refs
118 the same ref?)
119 use_regex => 0
121 Regexes will be compared directly (IE are the regexes the
122 same?)
123 $compare = relaxed_convert($thing)
125 Convert $thing to an Test2::Compare::* object. This will be relaxed
126 which means it uses these settings:
127 implicit_end => 0
129 Array bounds will not be checked when this object is used in a
130 comparison. Unexpected hash keys can be present.
131 use_code => 1
133 Sub references will be run to verify a value.
134 use_regex => 1
136 Values will be checked against any regexes provided.
137
139 use Test2::Compare qw/compare convert/;
140 sub my_like($$;$@) {
142 my ($got, $exp, $name, @diag) = @_;
143 my $ctx = context();
144 # A custom converter that does the same thing as the one used by like()
146 my $convert = sub {
147 my $thing = shift;
148 return convert(
149 $thing,
150 {
151 implicit_end => 0,
152 use_code => 1,
153 use_regex => 1,
154 }
155 );
156 };
157 my $delta = compare($got, $exp, $convert);
159 if ($delta) {
161 $ctx->fail($name, $delta->diag, @diag);
162 }
163 else {
164 $ctx->ok(1, $name);
165 }
166 $ctx->release;
168 return !$delta;
169 }
170 The work of a comparison tool is done by 3 entities:
172 compare()
174 The compare() function takes the structure you got, the
175 specification you want to check against, and a "\&convert" sub that
176 will convert anything that is not an instance of an
177 Test2::Compare::Base subclass into one.
178 This tool will use the "\&convert" function on the specification,
180 and then produce an Test2::Compare::Delta structure that outlines
181 all the ways the structure you got deviates from the specification.
182 \&convert
184 Converts anything that is not an instance of an
185 Test2::Compare::Base subclass, and turns it into one. The objects
186 this produces are able to check that a structure matches a
187 specification.
188 $delta
190 An instance of Test2::Compare::Delta is ultimately returned. This
191 object represents all the ways in with the structure you got
192 deviated from the specification. The delta is a tree and may
193 contain child deltas for nested structures.
194 The delta is capable of rendering itself as a table, use "@lines =
196 $delta->diag" to get the table (lines in @lines will not be
197 terminated with "\n").
198 The convert() function provided by this package contains all the
200 specification behavior of like() and is(). It is intended to be wrapped
201 in a sub that passes in a configuration hash, which allows you to
202 control the behavior.
203 You are free to write your own "$check = compare($thing)" function, it
205 just needs to accept a single argument, and produce a single instance
206 of an Test2::Compare::Base subclass.
207
209 The source code repository for Test2-Suite can be found at
210 https://github.com/Test-More/Test2-Suite/.
211
213 Chad Granum <exodist@cpan.org>
214
216 Chad Granum <exodist@cpan.org>
217
219 Copyright 2018 Chad Granum <exodist@cpan.org>.
220 This program is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself.
223 See http://dev.perl.org/licenses/
225perl v5.38.0 2023-07-21 Test2::Compare(3)