1Test::Differences(3) User Contributed Perl Documentation Test::Differences(3)
2
6 Test::Differences - Test strings and data structures and show
7 differences if not ok
8
10 use Test; ## Or use Test::More
11 use Test::Differences;
12 eq_or_diff $got, "a\nb\nc\n", "testing strings";
14 eq_or_diff \@got, [qw( a b c )], "testing arrays";
15 ## Passing options:
17 eq_or_diff $got, $expected, $name, { context => 300 }; ## options
18 ## Using with DBI-like data structures
20 use DBI;
22 ... open connection & prepare statement and @expected_... here...
24 eq_or_diff $sth->fetchall_arrayref, \@expected_arrays "testing DBI arrays";
26 eq_or_diff $sth->fetchall_hashref, \@expected_hashes, "testing DBI hashes";
27 ## To force textual or data line numbering (text lines are numbered 1..):
29 eq_or_diff_text ...;
30 eq_or_diff_data ...;
31
33 This module exports three test functions and four diff-style functions:
34 • Test functions
36 • "eq_or_diff"
38 • "eq_or_diff_data"
40 • "eq_or_diff_text"
42 • Diff style functions
44 • "table_diff" (the default)
46 • "unified_diff"
48 • "oldstyle_diff"
50 • "context_diff"
52
54 When the code you're testing returns multiple lines, records or data
55 structures and they're just plain wrong, an equivalent to the Unix
56 "diff" utility may be just what's needed. Here's output from an
57 example test script that checks two text documents and then two
58 (trivial) data structures:
59 t/99example....1..3
61 not ok 1 - differences in text
62 # Failed test ((eval 2) at line 14)
63 # +---+----------------+----------------+
64 # | Ln|Got |Expected |
65 # +---+----------------+----------------+
66 # | 1|this is line 1 |this is line 1 |
67 # * 2|this is line 2 |this is line b *
68 # | 3|this is line 3 |this is line 3 |
69 # +---+----------------+----------------+
70 not ok 2 - differences in whitespace
71 # Failed test ((eval 2) at line 20)
72 # +---+------------------+------------------+
73 # | Ln|Got |Expected |
74 # +---+------------------+------------------+
75 # | 1| indented | indented |
76 # * 2| indented |\tindented *
77 # | 3| indented | indented |
78 # +---+------------------+------------------+
79 not ok 3
80 # Failed test ((eval 2) at line 22)
81 # +----+-------------------------------------+----------------------------+
82 # | Elt|Got |Expected |
83 # +----+-------------------------------------+----------------------------+
84 # * 0|bless( [ |[ *
85 # * 1| 'Move along, nothing to see here' | 'Dry, humorless message' *
86 # * 2|], 'Test::Builder' ) |] *
87 # +----+-------------------------------------+----------------------------+
88 # Looks like you failed 3 tests of 3.
89 eq_or_diff_...() compares two strings or (limited) data structures and
91 either emits an ok indication or a side-by-side diff.
92 Test::Differences is designed to be used with Test.pm and with
93 Test::Simple, Test::More, and other Test::Builder based testing
94 modules. As the SYNOPSIS shows, another testing module must be used as
95 the basis for your test suite.
96
98 The options to "eq_or_diff" give some fine-grained control over the
99 output.
100 • "context"
102 This allows you to control the amount of context shown:
104 eq_or_diff $got, $expected, $name, { context => 50000 };
106 will show you lots and lots of context. Normally, eq_or_diff()
108 uses some heuristics to determine whether to show 3 lines of
109 context (like a normal unified diff) or 25 lines.
110 • "data_type"
112 "text" or "data". This normally defaults to "data". If, however,
114 neither of $got or $expected is a reference then it defaults to
115 "text". You can also force one or the other by calling
116 "eq_or_diff_text" or "eq_or_diff_data".
117 The difference is that in text mode lines are numbered from 1, but
119 in data mode from 0 (and are refered to as 'elements' (Elt) instead
120 of lines):
121 # +---+-------+----------+
123 # | Ln|Got |Expected |
124 # +---+-------+----------+
125 # * 1|'foo' |'bar' *
126 # +---+-------+----------+
127 # +----+---------+----+----------+
129 # | Elt|Got | Elt|Expected |
130 # +----+---------+----+----------+
131 # * 0|[ * 0|'bar' *
132 # * 1| 'foo' * | |
133 # * 2|] * | |
134 # +----+---------+----+----------+
135 The difference is purely cosmetic, it makes no difference to how
137 comparisons are performed.
138 • "Sortkeys"
140 If passed, whatever value is added is used as the argument for
142 Data::Dumper Sortkeys option. See the Data::Dumper docs to
143 understand how you can control the Sortkeys behavior.
144 • "filename_a" and "filename_b"
146 The column headers to use in the output. They default to 'Got' and
148 'Expected'.
149
151 For extremely long strings, a table diff can wrap on your screen and be
152 hard to read. If you are comfortable with different diff formats, you
153 can switch to a format more suitable for your data. These are the four
154 formats supported by the Text::Diff module and are set with the
155 following functions:
156 • "table_diff" (the default)
158 • "unified_diff"
160 • "oldstyle_diff"
162 • "context_diff"
164 You can run the following to understand the different diff output
166 styles:
167 use Test::More 'no_plan';
169 use Test::Differences;
170 my $long_string = join '' => 1..40;
172 TODO: {
174 local $TODO = 'Testing diff styles';
175 # this is the default and does not need to explicitly set unless you need
177 # to reset it back from another diff type
178 table_diff;
179 eq_or_diff $long_string, "-$long_string", 'table diff';
180 unified_diff;
182 eq_or_diff $long_string, "-$long_string", 'unified diff';
183 context_diff;
185 eq_or_diff $long_string, "-$long_string", 'context diff';
186 oldstyle_diff;
188 eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
189 }
190
192 Generally you'll find that the following test output is disappointing.
193 use Test::Differences;
195 use utf8;
196 my $want = { 'Traditional Chinese' => '中國' };
198 my $have = { 'Traditional Chinese' => '中国' };
199 eq_or_diff $have, $want, 'Unicode, baby';
201 Here's what you get:
203 # Failed test 'Unicode, baby'
205 # at t/unicode.t line 12.
206 # +----+-----------------------+-----------------------+
207 # | Elt|Got |Expected |
208 # +----+-----------------------+-----------------------+
209 # | 0|'Traditional Chinese' |'Traditional Chinese' |
210 # * 1|'\x{4e2d}\x{56fd}' |'\x{4e2d}\x{570b}' *
211 # +----+-----------------------+-----------------------+
212 # Looks like you failed 1 test of 1.
213 Dubious, test returned 1 (wstat 256, 0x100)
214 Failed 1/1 subtests
215 A patch to fix this would be *most* welcome.
217
219 Unknown::Values is a module which provides values which will never
220 compare as being the same as anything else, not even the same as
221 itself.
222 If code looks too hard at one of these values (and Test::Differences
224 looks very hard indeed) that is a fatal error. This means that while we
225 can detect the presence of these beasties, and tell you that they
226 compare different, for Complicated Internals Reasons we can't show you
227 much context. Sorry.
228 NB that the support for these is experimental and relies on an
230 undocumented unstable interface in Unknown::Values. If that fails then
231 Test::Differences will probably just die when it sees them instead of
232 telling you that the comparison failed.
233
235 "Test" or "Test::More"
236 This module "mixes in" with Test.pm or any of the test libraries based
237 on Test::Builder (Test::Simple, Test::More, etc). It does this by
238 peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
239 are not using one of those, it will print a warning and play dumb by
240 not emitting test numbers (or incrementing them). If you are using one
241 of these, it should interoperate nicely.
242 Exporting
244 Exports all 3 functions by default (and by design). Use
245 use Test::Differences ();
247 to suppress this behavior if you don't like the namespace pollution.
249 This module will not override functions like ok(), is(), is_deeply(),
251 etc. If it did, then you could "eval "use Test::Differences qw(
252 is_deeply );"" to get automatic upgrading to diffing behaviors without
253 the "sub my_ok" shown above. Test::Differences intentionally does not
254 provide this behavior because this would mean that Test::Differences
255 would need to emulate every popular test module out there, which would
256 require far more coding and maintenance that I'm willing to do. Use
257 the eval and my_ok deployment shown above if you want some level of
258 automation.
259 Unicode
261 Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
262 seems broken. This means that you might get odd results using
263 perl5.6.0 with unicode strings.
264 "Data::Dumper" and older Perls.
266 Relies on Data::Dumper (for now), which, prior to perl5.8, will not
267 always report hashes in the same order. $Data::Dumper::Sortkeys is
268 set to 1, so on more recent versions of Data::Dumper, this should not
269 occur. Check CPAN to see if it's been peeled out of the main perl
270 distribution and backported. Reported by Ilya Martynov
271 <ilya@martynov.org>, although the Sortkeys "future perfect" workaround
272 has been set in anticipation of a new Data::Dumper for a while. Note
273 that the two hashes should report the same here:
274 not ok 5
276 # Failed test (t/ctrl/05-home.t at line 51)
277 # +----+------------------------+----+------------------------+
278 # | Elt|Got | Elt|Expected |
279 # +----+------------------------+----+------------------------+
280 # | 0|{ | 0|{ |
281 # | 1| 'password' => '', | 1| 'password' => '', |
282 # * 2| 'method' => 'login', * | |
283 # | 3| 'ctrl' => 'home', | 2| 'ctrl' => 'home', |
284 # | | * 3| 'method' => 'login', *
285 # | 4| 'email' => 'test' | 4| 'email' => 'test' |
286 # | 5|} | 5|} |
287 # +----+------------------------+----+------------------------+
288 Data::Dumper also overlooks the difference between
290 $a[0] = \$a[1];
292 $a[1] = \$a[0]; # $a[0] = \$a[1]
293 and
295 $x = \$y;
297 $y = \$x;
298 @a = ( $x, $y ); # $a[0] = \$y, not \$a[1]
299 The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
301 This was carefully explained to me in words of two syllables or less by
302 Yves Orton <demerphq@hotmail.com>. The plan to address this is to
303 allow you to select Data::Denter or some other module of your choice as
304 an option.
305 Code-refs
307 Test::Differences turns on $Data::Dumper::Deparse, so any code-refs in
308 your data structures will be turned into text before they are examined,
309 using B::Deparse. The precise text generated for a sub-ref might not be
310 what you expect as it is generated from the compiled version of the
311 code, but it should at least be consistent and spot differences
312 correctly.
313 You can turn this behaviour off by setting
315 $Test::Differences::NoDeparse.
316
318 Barrie Slaymaker <barries@slaysys.com> - original author
319 Curtis "Ovid" Poe <ovid@cpan.org>
321 David Cantrell <david@cantrell.org.uk>
323
325 Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.
326 All Rights Reserved.
328 You may use, distribute and modify this software under the terms of the
330 GNU public license, any version, or the Artistic license.
331perl v5.38.0 2023-07-21 Test::Differences(3)