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". See "eq_or_diff_text" and "eq_or_diff_data" to
114 understand this. You can usually ignore this.
115 · "Sortkeys"
117 If passed, whatever value is added is used as the argument for
119 Data::Dumper Sortkeys option. See the Data::Dumper docs to
120 understand how you can control the Sortkeys behavior.
121 · "filename_a" and "filename_b"
123 The column headers to use in the output. They default to 'Got' and
125 'Expected'.
126
128 For extremely long strings, a table diff can wrap on your screen and be
129 hard to read. If you are comfortable with different diff formats, you
130 can switch to a format more suitable for your data. These are the four
131 formats supported by the Text::Diff module and are set with the
132 following functions:
133 · "table_diff" (the default)
135 · "unified_diff"
137 · "oldstyle_diff"
139 · "context_diff"
141 You can run the following to understand the different diff output
143 styles:
144 use Test::More 'no_plan';
146 use Test::Differences;
147 my $long_string = join '' => 1..40;
149 TODO: {
151 local $TODO = 'Testing diff styles';
152 # this is the default and does not need to explicitly set unless you need
154 # to reset it back from another diff type
155 table_diff;
156 eq_or_diff $long_string, "-$long_string", 'table diff';
157 unified_diff;
159 eq_or_diff $long_string, "-$long_string", 'unified diff';
160 context_diff;
162 eq_or_diff $long_string, "-$long_string", 'context diff';
163 oldstyle_diff;
165 eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
166 }
167
169 Generally you'll find that the following test output is disappointing.
170 use Test::Differences;
172 my $want = { 'Traditional Chinese' => '中國' };
174 my $have = { 'Traditional Chinese' => '中国' };
175 eq_or_diff $have, $want, 'Unicode, baby';
177 The output looks like this:
179 # Failed test 'Unicode, baby'
181 # at t/unicode.t line 12.
182 # +----+----------------------------+----------------------------+
183 # | Elt|Got |Expected |
184 # +----+----------------------------+----------------------------+
185 # | 0|'Traditional Chinese' |'Traditional Chinese' |
186 # * 1|'\xe4\xb8\xad\xe5\x9b\xbd' |'\xe4\xb8\xad\xe5\x9c\x8b' *
187 # +----+----------------------------+----------------------------+
188 # Looks like you failed 1 test of 1.
189 Dubious, test returned 1 (wstat 256, 0x100)
190 This is generally not helpful and someone points out that you didn't
192 declare your test program as being utf8, so you do that:
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 That's better, but still awful. However, if you have "Text::Diff" 0.40
217 or higher installed, you can add this to your code:
218 BEGIN { $ENV{DIFF_OUTPUT_UNICODE} = 1 }
220 Make sure you do this before you load Text::Diff. Then this is the
222 output:
223 # +----+-----------------------+-----------------------+
225 # | Elt|Got |Expected |
226 # +----+-----------------------+-----------------------+
227 # | 0|'Traditional Chinese' |'Traditional Chinese' |
228 # * 1|'中国' |'中國' *
229 # +----+-----------------------+-----------------------+
230
232 There are several basic ways of deploying Test::Differences requiring
233 more or less labor by you or your users.
234 · Fallback to "is_deeply".
236 This is your best option if you want this module to be optional.
238 use Test::More;
240 BEGIN {
241 if (!eval q{ use Test::Differences; 1 }) {
242 *eq_or_diff = \&is_deeply;
243 }
244 }
245 ·
247 eval "use Test::Differences";
250 If you want to detect the presence of Test::Differences on the fly,
252 something like the following code might do the trick for you:
253 use Test qw( !ok ); ## get all syms *except* ok
255 eval "use Test::Differences";
257 use Data::Dumper;
258 sub ok {
260 goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
261 @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
262 goto Test::&ok;
263 }
264 plan tests => 1;
266 ok "a", "b";
268 · PREREQ_PM => { .... "Test::Differences" => 0, ... }
270 This method will let CPAN and CPANPLUS users download it
272 automatically. It will discomfit those users who choose/have to
273 download all packages manually.
274 · t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
276 By placing Test::Differences and its prerequisites in the t/lib
278 directory, you avoid forcing your users to download the
279 Test::Differences manually if they aren't using CPAN or CPANPLUS.
280 If you put a "use lib "t/lib";" in the top of each test suite
282 before the "use Test::Differences;", "make test" should work well.
283 You might want to check once in a while for new Test::Differences
285 releases if you do this.
286
288 "Test" or "Test::More"
289 This module "mixes in" with Test.pm or any of the test libraries based
290 on Test::Builder (Test::Simple, Test::More, etc). It does this by
291 peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
292 are not using one of those, it will print a warning and play dumb by
293 not emitting test numbers (or incrementing them). If you are using one
294 of these, it should interoperate nicely.
295 Exporting
297 Exports all 3 functions by default (and by design). Use
298 use Test::Differences ();
300 to suppress this behavior if you don't like the namespace pollution.
302 This module will not override functions like ok(), is(), is_deeply(),
304 etc. If it did, then you could "eval "use Test::Differences qw(
305 is_deeply );"" to get automatic upgrading to diffing behaviors without
306 the "sub my_ok" shown above. Test::Differences intentionally does not
307 provide this behavior because this would mean that Test::Differences
308 would need to emulate every popular test module out there, which would
309 require far more coding and maintenance that I'm willing to do. Use
310 the eval and my_ok deployment shown above if you want some level of
311 automation.
312 Unicode
314 Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
315 seems broken. This means that you might get odd results using
316 perl5.6.0 with unicode strings.
317 "Data::Dumper" and older Perls.
319 Relies on Data::Dumper (for now), which, prior to perl5.8, will not
320 always report hashes in the same order. $Data::Dumper::Sortkeys is
321 set to 1, so on more recent versions of Data::Dumper, this should not
322 occur. Check CPAN to see if it's been peeled out of the main perl
323 distribution and backported. Reported by Ilya Martynov
324 <ilya@martynov.org>, although the Sortkeys "future perfect" workaround
325 has been set in anticipation of a new Data::Dumper for a while. Note
326 that the two hashes should report the same here:
327 not ok 5
329 # Failed test (t/ctrl/05-home.t at line 51)
330 # +----+------------------------+----+------------------------+
331 # | Elt|Got | Elt|Expected |
332 # +----+------------------------+----+------------------------+
333 # | 0|{ | 0|{ |
334 # | 1| 'password' => '', | 1| 'password' => '', |
335 # * 2| 'method' => 'login', * | |
336 # | 3| 'ctrl' => 'home', | 2| 'ctrl' => 'home', |
337 # | | * 3| 'method' => 'login', *
338 # | 4| 'email' => 'test' | 4| 'email' => 'test' |
339 # | 5|} | 5|} |
340 # +----+------------------------+----+------------------------+
341 Data::Dumper also overlooks the difference between
343 $a[0] = \$a[1];
345 $a[1] = \$a[0]; # $a[0] = \$a[1]
346 and
348 $x = \$y;
350 $y = \$x;
351 @a = ( $x, $y ); # $a[0] = \$y, not \$a[1]
352 The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
354 This was carefully explained to me in words of two syllables or less by
355 Yves Orton <demerphq@hotmail.com>. The plan to address this is to
356 allow you to select Data::Denter or some other module of your choice as
357 an option.
358 Code-refs
360 Test::Differences turns on $Data::Dumper::Deparse, so any code-refs in
361 your data structures will be turned into text before they are examined,
362 using B::Deparse. The precise text generated for a sub-ref might not be
363 what you expect as it is generated from the compiled version of the
364 code, but it should at least be consistent and spot differences
365 correctly.
366 You can turn this behaviour off by setting
368 $Test::Differences::NoDeparse.
369
371 Barrie Slaymaker <barries@slaysys.com> - original author
372 Curtis "Ovid" Poe <ovid@cpan.org>
374 David Cantrell <david@cantrell.org.uk>
376
378 Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.
379 All Rights Reserved.
381 You may use, distribute and modify this software under the terms of the
383 GNU public license, any version, or the Artistic license.
384perl v5.30.0 2019-07-26 Test::Differences(3)