1Test::Differences(3)  User Contributed Perl Documentation Test::Differences(3)
2
3
4

NAME

6       Test::Differences - Test strings and data structures and show
7       differences if not ok
8

SYNOPSIS

10          use Test;    ## Or use Test::More
11          use Test::Differences;
12
13          eq_or_diff $got,  "a\nb\nc\n",   "testing strings";
14          eq_or_diff \@got, [qw( a b c )], "testing arrays";
15
16          ## Passing options:
17          eq_or_diff $got, $expected, $name, { context => 300 };  ## options
18
19          ## Using with DBI-like data structures
20
21          use DBI;
22
23          ... open connection & prepare statement and @expected_... here...
24
25          eq_or_diff $sth->fetchall_arrayref, \@expected_arrays  "testing DBI arrays";
26          eq_or_diff $sth->fetchall_hashref,  \@expected_hashes, "testing DBI hashes";
27
28          ## To force textual or data line numbering (text lines are numbered 1..):
29          eq_or_diff_text ...;
30          eq_or_diff_data ...;
31

EXPORT

33       This module exports three test functions and four diff-style functions:
34
35       ·   Test functions
36
37           ·   "eq_or_diff"
38
39           ·   "eq_or_diff_data"
40
41           ·   "eq_or_diff_text"
42
43       ·   Diff style functions
44
45           ·   "table_diff" (the default)
46
47           ·   "unified_diff"
48
49           ·   "oldstyle_diff"
50
51           ·   "context_diff"
52

DESCRIPTION

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
60        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
90       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
97       These functions assume that you are presenting it with "flat" records,
98       looking like:
99
100          - scalars composed of record-per-line
101          - arrays of scalars,
102          - arrays of arrays of scalars,
103          - arrays of hashes containing only scalars
104
105       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
109       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
116       "eq_or_diff()" starts counting records at 0 unless you pass it two text
117       strings:
118
119          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
123       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

OPTIONS

129       There is currently only one option: "context".  This allows you to
130       control the amount of context shown:
131
132          eq_or_diff $got, $expected, $name, { context => 50000 };
133
134       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

DIFF STYLES

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
145       ·   "table_diff" (the default)
146
147       ·   "unified_diff"
148
149       ·   "oldstyle_diff"
150
151       ·   "context_diff"
152
153       You can run the following to understand the different diff output
154       styles:
155
156        use Test::More 'no_plan';
157        use Test::Differences;
158
159        my $long_string = join '' => 1..40;
160
161        TODO: {
162            local $TODO = 'Testing diff styles';
163
164            # 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
169            unified_diff;
170            eq_or_diff $long_string, "-$long_string", 'unified diff';
171
172            context_diff;
173            eq_or_diff $long_string, "-$long_string", 'context diff';
174
175            oldstyle_diff;
176            eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
177        }
178

DEPLOYING

180       There are several basic ways of deploying Test::Differences requiring
181       more or less labor by you or your users.
182
183       ·   Fallback to "is_deeply".
184
185           This is your best option if you want this module to be optional.
186
187            use Test::More;
188            BEGIN {
189                if (!eval q{ use Test::Differences; 1 }) {
190                    *eq_or_diff = \&is_deeply;
191                }
192            }
193
194       ·
195
196
197            eval "use Test::Differences";
198
199           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
202               use Test qw( !ok );   ## get all syms *except* ok
203
204               eval "use Test::Differences";
205               use Data::Dumper;
206
207               sub ok {
208                   goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
209                   @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
210                   goto Test::&ok;
211               }
212
213               plan tests => 1;
214
215               ok "a", "b";
216
217       ·   PREREQ_PM => { .... "Test::Differences" => 0, ... }
218
219           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
223       ·   t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
224
225           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
229           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
232           You might want to check once in a while for new Test::Differences
233           releases if you do this.
234

LIMITATIONS

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
244   Exporting
245       Exports all 3 functions by default (and by design).  Use
246
247           use Test::Differences ();
248
249       to suppress this behavior if you don't like the namespace pollution.
250
251       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
261   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
266   "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
276           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
290       Data::Dumper also overlooks the difference between
291
292           $a[0] = \$a[1];
293           $a[1] = \$a[0];   # $a[0] = \$a[1]
294
295       and
296
297           $x = \$y;
298           $y = \$x;
299           @a = ( $x, $y );  # $a[0] = \$y, not \$a[1]
300
301       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

AUTHOR

308           Barrie Slaymaker <barries@slaysys.com>
309

MAINTAINER

311           Curtis "Ovid" Poe <ovid@cpan.org>
312

LICENSE

314       Copyright 2001-2008 Barrie Slaymaker, All Rights Reserved.
315
316       You may use this software under the terms of the GNU public license,
317       any version, or the Artistic license.
318
319
320
321perl v5.12.1                      2009-10-17              Test::Differences(3)
Impressum