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 These functions assume that you are presenting it with "flat" records,
98 looking like:
99 - scalars composed of record-per-line
101 - arrays of scalars,
102 - arrays of arrays of scalars,
103 - arrays of hashes containing only scalars
104 All of these are flattened in to single strings which are then compared
106 for differences. Differently data structures can be compared, as long
107 as they flatten identically.
108 All other data structures are run through Data::Dumper first. This is
110 a bit dangerous, as some versions of perl shipped with Data::Dumpers
111 that could do the oddest things with unexpected, like core dump. Only
112 as of 5.8.0 does Data::Dumper sort hash keys, which is necessary for
113 HASH dumps to be fully predictable. This will be changed when this
114 bites somebody or I get some free time.
115 "eq_or_diff()" starts counting records at 0 unless you pass it two text
117 strings:
118 eq_or_diff $a, $b; ## First line is line number 1
120 eq_or_diff @a, @b; ## First element is element 0
121 eq_or_diff $a, @b; ## First line/element is element 0
122 If you want to force a first record number of 0, use "eq_or_diff_data".
124 If you want to force a first record number of 1, use "eq_or_diff_text".
125 I chose this over passing in an options hash because it's clearer and
126 simpler this way. YMMV.
127
129 There is currently only one option: "context". This allows you to
130 control the amount of context shown:
131 eq_or_diff $got, $expected, $name, { context => 50000 };
133 will show you lots and lots of context. Normally, eq_or_diff() uses
135 some heuristics to determine whether to show 3 lines of context (like a
136 normal unified diff) or 25 lines.
137
139 For extremely long strings, a table diff can wrap on your screen and be
140 hard to read. If you are comfortable with different diff formats, you
141 can switch to a format more suitable for your data. These are the four
142 formats supported by the Text::Diff module and are set with the
143 following functions:
144 · "table_diff" (the default)
146 · "unified_diff"
148 · "oldstyle_diff"
150 · "context_diff"
152 You can run the following to understand the different diff output
154 styles:
155 use Test::More 'no_plan';
157 use Test::Differences;
158 my $long_string = join '' => 1..40;
160 TODO: {
162 local $TODO = 'Testing diff styles';
163 # this is the default and does not need to explicitly set unless you need
165 # to reset it back from another diff type
166 table_diff;
167 eq_or_diff $long_string, "-$long_string", 'table diff';
168 unified_diff;
170 eq_or_diff $long_string, "-$long_string", 'unified diff';
171 context_diff;
173 eq_or_diff $long_string, "-$long_string", 'context diff';
174 oldstyle_diff;
176 eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
177 }
178
180 There are several basic ways of deploying Test::Differences requiring
181 more or less labor by you or your users.
182 · Fallback to "is_deeply".
184 This is your best option if you want this module to be optional.
186 use Test::More;
188 BEGIN {
189 if (!eval q{ use Test::Differences; 1 }) {
190 *eq_or_diff = \&is_deeply;
191 }
192 }
193 ·
195 eval "use Test::Differences";
198 If you want to detect the presence of Test::Differences on the fly,
200 something like the following code might do the trick for you:
201 use Test qw( !ok ); ## get all syms *except* ok
203 eval "use Test::Differences";
205 use Data::Dumper;
206 sub ok {
208 goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
209 @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
210 goto Test::&ok;
211 }
212 plan tests => 1;
214 ok "a", "b";
216 · PREREQ_PM => { .... "Test::Differences" => 0, ... }
218 This method will let CPAN and CPANPLUS users download it
220 automatically. It will discomfit those users who choose/have to
221 download all packages manually.
222 · t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
224 By placing Test::Differences and its prerequisites in the t/lib
226 directory, you avoid forcing your users to download the
227 Test::Differences manually if they aren't using CPAN or CPANPLUS.
228 If you put a "use lib "t/lib";" in the top of each test suite
230 before the "use Test::Differences;", "make test" should work well.
231 You might want to check once in a while for new Test::Differences
233 releases if you do this.
234
236 "Test" or "Test::More"
237 This module "mixes in" with Test.pm or any of the test libraries based
238 on Test::Builder (Test::Simple, Test::More, etc). It does this by
239 peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
240 are not using one of those, it will print a warning and play dumb by
241 not emitting test numbers (or incrementing them). If you are using one
242 of these, it should interoperate nicely.
243 Exporting
245 Exports all 3 functions by default (and by design). Use
246 use Test::Differences ();
248 to suppress this behavior if you don't like the namespace pollution.
250 This module will not override functions like ok(), is(), is_deeply(),
252 etc. If it did, then you could "eval "use Test::Differences qw(
253 is_deeply );"" to get automatic upgrading to diffing behaviors without
254 the "sub my_ok" shown above. Test::Differences intentionally does not
255 provide this behavior because this would mean that Test::Differences
256 would need to emulate every popular test module out there, which would
257 require far more coding and maintenance that I'm willing to do. Use
258 the eval and my_ok deployment shown above if you want some level of
259 automation.
260 Unicode
262 Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
263 seems broken. This means that you might get odd results using
264 perl5.6.0 with unicode strings.
265 "Data::Dumper" and older Perls.
267 Relies on Data::Dumper (for now), which, prior to perl5.8, will not
268 always report hashes in the same order. $Data::Dumper::SortKeys is
269 set to 1, so on more recent versions of Data::Dumper, this should not
270 occur. Check CPAN to see if it's been peeled out of the main perl
271 distribution and backported. Reported by Ilya Martynov
272 <ilya@martynov.org>, although the SortKeys "future perfect" workaround
273 has been set in anticipation of a new Data::Dumper for a while. Note
274 that the two hashes should report the same here:
275 not ok 5
277 # Failed test (t/ctrl/05-home.t at line 51)
278 # +----+------------------------+----+------------------------+
279 # | Elt|Got | Elt|Expected |
280 # +----+------------------------+----+------------------------+
281 # | 0|{ | 0|{ |
282 # | 1| 'password' => '', | 1| 'password' => '', |
283 # * 2| 'method' => 'login', * | |
284 # | 3| 'ctrl' => 'home', | 2| 'ctrl' => 'home', |
285 # | | * 3| 'method' => 'login', *
286 # | 4| 'email' => 'test' | 4| 'email' => 'test' |
287 # | 5|} | 5|} |
288 # +----+------------------------+----+------------------------+
289 Data::Dumper also overlooks the difference between
291 $a[0] = \$a[1];
293 $a[1] = \$a[0]; # $a[0] = \$a[1]
294 and
296 $x = \$y;
298 $y = \$x;
299 @a = ( $x, $y ); # $a[0] = \$y, not \$a[1]
300 The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
302 This was carefully explained to me in words of two syllables or less by
303 Yves Orton <demerphq@hotmail.com>. The plan to address this is to
304 allow you to select Data::Denter or some other module of your choice as
305 an option.
306
308 Barrie Slaymaker <barries@slaysys.com>
309
311 Curtis "Ovid" Poe <ovid@cpan.org>
312
314 Copyright 2001-2008 Barrie Slaymaker, All Rights Reserved.
315 You may use this software under the terms of the GNU public license,
317 any version, or the Artistic license.
318perl v5.16.3 2009-10-17 Test::Differences(3)