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 my $want = { 'Traditional Chinese' => '中國' };
197 my $have = { 'Traditional Chinese' => '中国' };
198 eq_or_diff $have, $want, 'Unicode, baby';
200 The output looks like this:
202 # Failed test 'Unicode, baby'
204 # at t/unicode.t line 12.
205 # +----+----------------------------+----------------------------+
206 # | Elt|Got |Expected |
207 # +----+----------------------------+----------------------------+
208 # | 0|'Traditional Chinese' |'Traditional Chinese' |
209 # * 1|'\xe4\xb8\xad\xe5\x9b\xbd' |'\xe4\xb8\xad\xe5\x9c\x8b' *
210 # +----+----------------------------+----------------------------+
211 # Looks like you failed 1 test of 1.
212 Dubious, test returned 1 (wstat 256, 0x100)
213 This is generally not helpful and someone points out that you didn't
215 declare your test program as being utf8, so you do that:
216 use Test::Differences;
218 use utf8;
219 my $want = { 'Traditional Chinese' => '中國' };
221 my $have = { 'Traditional Chinese' => '中国' };
222 eq_or_diff $have, $want, 'Unicode, baby';
224 Here's what you get:
226 # Failed test 'Unicode, baby'
228 # at t/unicode.t line 12.
229 # +----+-----------------------+-----------------------+
230 # | Elt|Got |Expected |
231 # +----+-----------------------+-----------------------+
232 # | 0|'Traditional Chinese' |'Traditional Chinese' |
233 # * 1|'\x{4e2d}\x{56fd}' |'\x{4e2d}\x{570b}' *
234 # +----+-----------------------+-----------------------+
235 # Looks like you failed 1 test of 1.
236 Dubious, test returned 1 (wstat 256, 0x100)
237 Failed 1/1 subtests
238 That's better, but still awful. However, if you have "Text::Diff" 0.40
240 or higher installed, you can add this to your code:
241 BEGIN { $ENV{DIFF_OUTPUT_UNICODE} = 1 }
243 Make sure you do this before you load Text::Diff. Then this is the
245 output:
246 # +----+-----------------------+-----------------------+
248 # | Elt|Got |Expected |
249 # +----+-----------------------+-----------------------+
250 # | 0|'Traditional Chinese' |'Traditional Chinese' |
251 # * 1|'中国' |'中國' *
252 # +----+-----------------------+-----------------------+
253
255 There are several basic ways of deploying Test::Differences requiring
256 more or less labor by you or your users.
257 • Fallback to "is_deeply".
259 This is your best option if you want this module to be optional.
261 use Test::More;
263 BEGIN {
264 if (!eval q{ use Test::Differences; 1 }) {
265 *eq_or_diff = \&is_deeply;
266 }
267 }
268 •
270 eval "use Test::Differences";
273 If you want to detect the presence of Test::Differences on the fly,
275 something like the following code might do the trick for you:
276 use Test qw( !ok ); ## get all syms *except* ok
278 eval "use Test::Differences";
280 use Data::Dumper;
281 sub ok {
283 goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
284 @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
285 goto Test::&ok;
286 }
287 plan tests => 1;
289 ok "a", "b";
291 • PREREQ_PM => { .... "Test::Differences" => 0, ... }
293 This method will let CPAN and CPANPLUS users download it
295 automatically. It will discomfit those users who choose/have to
296 download all packages manually.
297 • t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
299 By placing Test::Differences and its prerequisites in the t/lib
301 directory, you avoid forcing your users to download the
302 Test::Differences manually if they aren't using CPAN or CPANPLUS.
303 If you put a "use lib "t/lib";" in the top of each test suite
305 before the "use Test::Differences;", "make test" should work well.
306 You might want to check once in a while for new Test::Differences
308 releases if you do this.
309
311 "Test" or "Test::More"
312 This module "mixes in" with Test.pm or any of the test libraries based
313 on Test::Builder (Test::Simple, Test::More, etc). It does this by
314 peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
315 are not using one of those, it will print a warning and play dumb by
316 not emitting test numbers (or incrementing them). If you are using one
317 of these, it should interoperate nicely.
318 Exporting
320 Exports all 3 functions by default (and by design). Use
321 use Test::Differences ();
323 to suppress this behavior if you don't like the namespace pollution.
325 This module will not override functions like ok(), is(), is_deeply(),
327 etc. If it did, then you could "eval "use Test::Differences qw(
328 is_deeply );"" to get automatic upgrading to diffing behaviors without
329 the "sub my_ok" shown above. Test::Differences intentionally does not
330 provide this behavior because this would mean that Test::Differences
331 would need to emulate every popular test module out there, which would
332 require far more coding and maintenance that I'm willing to do. Use
333 the eval and my_ok deployment shown above if you want some level of
334 automation.
335 Unicode
337 Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
338 seems broken. This means that you might get odd results using
339 perl5.6.0 with unicode strings.
340 "Data::Dumper" and older Perls.
342 Relies on Data::Dumper (for now), which, prior to perl5.8, will not
343 always report hashes in the same order. $Data::Dumper::Sortkeys is
344 set to 1, so on more recent versions of Data::Dumper, this should not
345 occur. Check CPAN to see if it's been peeled out of the main perl
346 distribution and backported. Reported by Ilya Martynov
347 <ilya@martynov.org>, although the Sortkeys "future perfect" workaround
348 has been set in anticipation of a new Data::Dumper for a while. Note
349 that the two hashes should report the same here:
350 not ok 5
352 # Failed test (t/ctrl/05-home.t at line 51)
353 # +----+------------------------+----+------------------------+
354 # | Elt|Got | Elt|Expected |
355 # +----+------------------------+----+------------------------+
356 # | 0|{ | 0|{ |
357 # | 1| 'password' => '', | 1| 'password' => '', |
358 # * 2| 'method' => 'login', * | |
359 # | 3| 'ctrl' => 'home', | 2| 'ctrl' => 'home', |
360 # | | * 3| 'method' => 'login', *
361 # | 4| 'email' => 'test' | 4| 'email' => 'test' |
362 # | 5|} | 5|} |
363 # +----+------------------------+----+------------------------+
364 Data::Dumper also overlooks the difference between
366 $a[0] = \$a[1];
368 $a[1] = \$a[0]; # $a[0] = \$a[1]
369 and
371 $x = \$y;
373 $y = \$x;
374 @a = ( $x, $y ); # $a[0] = \$y, not \$a[1]
375 The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
377 This was carefully explained to me in words of two syllables or less by
378 Yves Orton <demerphq@hotmail.com>. The plan to address this is to
379 allow you to select Data::Denter or some other module of your choice as
380 an option.
381 Code-refs
383 Test::Differences turns on $Data::Dumper::Deparse, so any code-refs in
384 your data structures will be turned into text before they are examined,
385 using B::Deparse. The precise text generated for a sub-ref might not be
386 what you expect as it is generated from the compiled version of the
387 code, but it should at least be consistent and spot differences
388 correctly.
389 You can turn this behaviour off by setting
391 $Test::Differences::NoDeparse.
392
394 Barrie Slaymaker <barries@slaysys.com> - original author
395 Curtis "Ovid" Poe <ovid@cpan.org>
397 David Cantrell <david@cantrell.org.uk>
399
401 Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.
402 All Rights Reserved.
404 You may use, distribute and modify this software under the terms of the
406 GNU public license, any version, or the Artistic license.
407perl v5.34.0 2021-07-23 Test::Differences(3)