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 0.62
11
13 use Test; ## Or use Test::More
14 use Test::Differences;
15 eq_or_diff $got, "a\nb\nc\n", "testing strings";
17 eq_or_diff \@got, [qw( a b c )], "testing arrays";
18 ## Passing options:
20 eq_or_diff $got, $expected, $name, { context => 300 }; ## options
21 ## Using with DBI-like data structures
23 use DBI;
25 ... open connection & prepare statement and @expected_... here...
27 eq_or_diff $sth->fetchall_arrayref, \@expected_arrays "testing DBI arrays";
29 eq_or_diff $sth->fetchall_hashref, \@expected_hashes, "testing DBI hashes";
30 ## To force textual or data line numbering (text lines are numbered 1..):
32 eq_or_diff_text ...;
33 eq_or_diff_data ...;
34
36 This module exports three test functions and four diff-style functions:
37 · Test functions
39 · "eq_or_diff"
41 · "eq_or_diff_data"
43 · "eq_or_diff_text"
45 · Diff style functions
47 · "table_diff" (the default)
49 · "unified_diff"
51 · "oldstyle_diff"
53 · "context_diff"
55
57 When the code you're testing returns multiple lines, records or data
58 structures and they're just plain wrong, an equivalent to the Unix
59 "diff" utility may be just what's needed. Here's output from an
60 example test script that checks two text documents and then two
61 (trivial) data structures:
62 t/99example....1..3
64 not ok 1 - differences in text
65 # Failed test ((eval 2) at line 14)
66 # +---+----------------+----------------+
67 # | Ln|Got |Expected |
68 # +---+----------------+----------------+
69 # | 1|this is line 1 |this is line 1 |
70 # * 2|this is line 2 |this is line b *
71 # | 3|this is line 3 |this is line 3 |
72 # +---+----------------+----------------+
73 not ok 2 - differences in whitespace
74 # Failed test ((eval 2) at line 20)
75 # +---+------------------+------------------+
76 # | Ln|Got |Expected |
77 # +---+------------------+------------------+
78 # | 1| indented | indented |
79 # * 2| indented |\tindented *
80 # | 3| indented | indented |
81 # +---+------------------+------------------+
82 not ok 3
83 # Failed test ((eval 2) at line 22)
84 # +----+-------------------------------------+----------------------------+
85 # | Elt|Got |Expected |
86 # +----+-------------------------------------+----------------------------+
87 # * 0|bless( [ |[ *
88 # * 1| 'Move along, nothing to see here' | 'Dry, humorless message' *
89 # * 2|], 'Test::Builder' ) |] *
90 # +----+-------------------------------------+----------------------------+
91 # Looks like you failed 3 tests of 3.
92 eq_or_diff_...() compares two strings or (limited) data structures and
94 either emits an ok indication or a side-by-side diff.
95 Test::Differences is designed to be used with Test.pm and with
96 Test::Simple, Test::More, and other Test::Builder based testing
97 modules. As the SYNOPSIS shows, another testing module must be used as
98 the basis for your test suite.
99
101 The options to "eq_or_diff" give some fine-grained control over the
102 output.
103 · "context"
105 This allows you to control the amount of context shown:
107 eq_or_diff $got, $expected, $name, { context => 50000 };
109 will show you lots and lots of context. Normally, eq_or_diff()
111 uses some heuristics to determine whether to show 3 lines of
112 context (like a normal unified diff) or 25 lines.
113 · "data_type"
115 "text" or "data". See "eq_or_diff_text" and "eq_or_diff_data" to
117 understand this. You can usually ignore this.
118 · "Sortkeys"
120 If passed, whatever value is added is used as the argument for
122 Data::Dumper Sortkeys option. See the Data::Dumper docs to
123 understand how you can control the Sortkeys behavior.
124 · "filename_a" and "filename_b"
126 The column headers to use in the output. They default to 'Got' and
128 'Expected'.
129
131 For extremely long strings, a table diff can wrap on your screen and be
132 hard to read. If you are comfortable with different diff formats, you
133 can switch to a format more suitable for your data. These are the four
134 formats supported by the Text::Diff module and are set with the
135 following functions:
136 · "table_diff" (the default)
138 · "unified_diff"
140 · "oldstyle_diff"
142 · "context_diff"
144 You can run the following to understand the different diff output
146 styles:
147 use Test::More 'no_plan';
149 use Test::Differences;
150 my $long_string = join '' => 1..40;
152 TODO: {
154 local $TODO = 'Testing diff styles';
155 # this is the default and does not need to explicitly set unless you need
157 # to reset it back from another diff type
158 table_diff;
159 eq_or_diff $long_string, "-$long_string", 'table diff';
160 unified_diff;
162 eq_or_diff $long_string, "-$long_string", 'unified diff';
163 context_diff;
165 eq_or_diff $long_string, "-$long_string", 'context diff';
166 oldstyle_diff;
168 eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
169 }
170
172 Generally you'll find that the following test output is disappointing.
173 use Test::Differences;
175 my $want = { 'Traditional Chinese' => '中國' };
177 my $have = { 'Traditional Chinese' => '中国' };
178 eq_or_diff $have, $want, 'Unicode, baby';
180 The output looks like this:
182 # Failed test 'Unicode, baby'
184 # at t/unicode.t line 12.
185 # +----+----------------------------+----------------------------+
186 # | Elt|Got |Expected |
187 # +----+----------------------------+----------------------------+
188 # | 0|'Traditional Chinese' |'Traditional Chinese' |
189 # * 1|'\xe4\xb8\xad\xe5\x9b\xbd' |'\xe4\xb8\xad\xe5\x9c\x8b' *
190 # +----+----------------------------+----------------------------+
191 # Looks like you failed 1 test of 1.
192 Dubious, test returned 1 (wstat 256, 0x100)
193 This is generally not helpful and someone points out that you didn't
195 declare your test program as being utf8, so you do that:
196 use Test::Differences;
198 use utf8;
199 my $want = { 'Traditional Chinese' => '中國' };
201 my $have = { 'Traditional Chinese' => '中国' };
202 eq_or_diff $have, $want, 'Unicode, baby';
204 Here's what you get:
206 # Failed test 'Unicode, baby'
208 # at t/unicode.t line 12.
209 # +----+-----------------------+-----------------------+
210 # | Elt|Got |Expected |
211 # +----+-----------------------+-----------------------+
212 # | 0|'Traditional Chinese' |'Traditional Chinese' |
213 # * 1|'\x{4e2d}\x{56fd}' |'\x{4e2d}\x{570b}' *
214 # +----+-----------------------+-----------------------+
215 # Looks like you failed 1 test of 1.
216 Dubious, test returned 1 (wstat 256, 0x100)
217 Failed 1/1 subtests
218 That's better, but still awful. However, if you have "Text::Diff" 0.40
220 or higher installed, you can add this to your code:
221 BEGIN { $ENV{DIFF_OUTPUT_UNICODE} = 1 }
223 Make sure you do this before you load Text::Diff. Then this is the
225 output:
226 # +----+-----------------------+-----------------------+
228 # | Elt|Got |Expected |
229 # +----+-----------------------+-----------------------+
230 # | 0|'Traditional Chinese' |'Traditional Chinese' |
231 # * 1|'中国' |'中國' *
232 # +----+-----------------------+-----------------------+
233
235 There are several basic ways of deploying Test::Differences requiring
236 more or less labor by you or your users.
237 · Fallback to "is_deeply".
239 This is your best option if you want this module to be optional.
241 use Test::More;
243 BEGIN {
244 if (!eval q{ use Test::Differences; 1 }) {
245 *eq_or_diff = \&is_deeply;
246 }
247 }
248 ·
250 eval "use Test::Differences";
253 If you want to detect the presence of Test::Differences on the fly,
255 something like the following code might do the trick for you:
256 use Test qw( !ok ); ## get all syms *except* ok
258 eval "use Test::Differences";
260 use Data::Dumper;
261 sub ok {
263 goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
264 @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
265 goto Test::&ok;
266 }
267 plan tests => 1;
269 ok "a", "b";
271 · PREREQ_PM => { .... "Test::Differences" => 0, ... }
273 This method will let CPAN and CPANPLUS users download it
275 automatically. It will discomfit those users who choose/have to
276 download all packages manually.
277 · t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
279 By placing Test::Differences and its prerequisites in the t/lib
281 directory, you avoid forcing your users to download the
282 Test::Differences manually if they aren't using CPAN or CPANPLUS.
283 If you put a "use lib "t/lib";" in the top of each test suite
285 before the "use Test::Differences;", "make test" should work well.
286 You might want to check once in a while for new Test::Differences
288 releases if you do this.
289
291 "Test" or "Test::More"
292 This module "mixes in" with Test.pm or any of the test libraries based
293 on Test::Builder (Test::Simple, Test::More, etc). It does this by
294 peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
295 are not using one of those, it will print a warning and play dumb by
296 not emitting test numbers (or incrementing them). If you are using one
297 of these, it should interoperate nicely.
298 Exporting
300 Exports all 3 functions by default (and by design). Use
301 use Test::Differences ();
303 to suppress this behavior if you don't like the namespace pollution.
305 This module will not override functions like ok(), is(), is_deeply(),
307 etc. If it did, then you could "eval "use Test::Differences qw(
308 is_deeply );"" to get automatic upgrading to diffing behaviors without
309 the "sub my_ok" shown above. Test::Differences intentionally does not
310 provide this behavior because this would mean that Test::Differences
311 would need to emulate every popular test module out there, which would
312 require far more coding and maintenance that I'm willing to do. Use
313 the eval and my_ok deployment shown above if you want some level of
314 automation.
315 Unicode
317 Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
318 seems broken. This means that you might get odd results using
319 perl5.6.0 with unicode strings.
320 "Data::Dumper" and older Perls.
322 Relies on Data::Dumper (for now), which, prior to perl5.8, will not
323 always report hashes in the same order. $Data::Dumper::Sortkeys is
324 set to 1, so on more recent versions of Data::Dumper, this should not
325 occur. Check CPAN to see if it's been peeled out of the main perl
326 distribution and backported. Reported by Ilya Martynov
327 <ilya@martynov.org>, although the Sortkeys "future perfect" workaround
328 has been set in anticipation of a new Data::Dumper for a while. Note
329 that the two hashes should report the same here:
330 not ok 5
332 # Failed test (t/ctrl/05-home.t at line 51)
333 # +----+------------------------+----+------------------------+
334 # | Elt|Got | Elt|Expected |
335 # +----+------------------------+----+------------------------+
336 # | 0|{ | 0|{ |
337 # | 1| 'password' => '', | 1| 'password' => '', |
338 # * 2| 'method' => 'login', * | |
339 # | 3| 'ctrl' => 'home', | 2| 'ctrl' => 'home', |
340 # | | * 3| 'method' => 'login', *
341 # | 4| 'email' => 'test' | 4| 'email' => 'test' |
342 # | 5|} | 5|} |
343 # +----+------------------------+----+------------------------+
344 Data::Dumper also overlooks the difference between
346 $a[0] = \$a[1];
348 $a[1] = \$a[0]; # $a[0] = \$a[1]
349 and
351 $x = \$y;
353 $y = \$x;
354 @a = ( $x, $y ); # $a[0] = \$y, not \$a[1]
355 The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
357 This was carefully explained to me in words of two syllables or less by
358 Yves Orton <demerphq@hotmail.com>. The plan to address this is to
359 allow you to select Data::Denter or some other module of your choice as
360 an option.
361
363 Barrie Slaymaker <barries@slaysys.com> - original author
364 Curtis "Ovid" Poe <ovid@cpan.org>
366 David Cantrell <david@cantrell.org.uk>
368
370 Copyright 2001-2008 Barrie Slaymaker, All Rights Reserved.
371 You may use this software under the terms of the GNU public license,
373 any version, or the Artistic license.
374perl v5.28.0 2015-11-22 Test::Differences(3)