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

NAME

6       Test::Differences - Test strings and data structures and show differ‐
7       ences 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

DESCRIPTION

33       When the code you're testing returns multiple lines, records or data
34       structures and they're just plain wrong, an equivalent to the Unix
35       "diff" utility may be just what's needed.  Here's output from an exam‐
36       ple test script that checks two text documents and then two (trivial)
37       data structures:
38
39        t/99example....1..3
40        not ok 1 - differences in text
41        #     Failed test ((eval 2) at line 14)
42        #     +---+----------------+----------------+
43        #     ⎪ Ln⎪Got             ⎪Expected        ⎪
44        #     +---+----------------+----------------+
45        #     ⎪  1⎪this is line 1  ⎪this is line 1  ⎪
46        #     *  2⎪this is line 2  ⎪this is line b  *
47        #     ⎪  3⎪this is line 3  ⎪this is line 3  ⎪
48        #     +---+----------------+----------------+
49        not ok 2 - differences in whitespace
50        #     Failed test ((eval 2) at line 20)
51        #     +---+------------------+------------------+
52        #     ⎪ Ln⎪Got               ⎪Expected          ⎪
53        #     +---+------------------+------------------+
54        #     ⎪  1⎪        indented  ⎪        indented  ⎪
55        #     *  2⎪        indented  ⎪\tindented        *
56        #     ⎪  3⎪        indented  ⎪        indented  ⎪
57        #     +---+------------------+------------------+
58        not ok 3
59        #     Failed test ((eval 2) at line 22)
60        #     +----+-------------------------------------+----------------------------+
61        #     ⎪ Elt⎪Got                                  ⎪Expected                    ⎪
62        #     +----+-------------------------------------+----------------------------+
63        #     *   0⎪bless( [                             ⎪[                           *
64        #     *   1⎪  'Move along, nothing to see here'  ⎪  'Dry, humorless message'  *
65        #     *   2⎪], 'Test::Builder' )                 ⎪]                           *
66        #     +----+-------------------------------------+----------------------------+
67        # Looks like you failed 3 tests of 3.
68
69       eq_or_diff_...() compares two strings or (limited) data structures and
70       either emits an ok indication or a side-by-side diff.  Test::Differ‐
71       ences is designed to be used with Test.pm and with Test::Simple,
72       Test::More, and other Test::Builder based testing modules.  As the SYN‐
73       OPSIS shows, another testing module must be used as the basis for your
74       test suite.
75
76       These functions assume that you are presenting it with "flat" records,
77       looking like:
78
79          - scalars composed of record-per-line
80          - arrays of scalars,
81          - arrays of arrays of scalars,
82          - arrays of hashes containing only scalars
83
84       All of these are flattened in to single strings which are then compared
85       for differences.  Differently data structures can be compared, as long
86       as they flatten identically.
87
88       All other data structures are run through Data::Dumper first.  This is
89       a bit dangerous, as some versions of perl shipped with Data::Dumpers
90       that could do the oddest things with unexpected, like core dump.  Only
91       as of 5.8.0 does Data::Dumper sort hash keys, which is necessary for
92       HASH dumps to be fully predictable.  This will be changed when this
93       bites somebody or I get some free time.
94
95       "eq_or_diff()" starts counting records at 0 unless you pass it two text
96       strings:
97
98          eq_or_diff $a, $b;   ## First line is line number 1
99          eq_or_diff @a, @b;   ## First element is element 0
100          eq_or_diff $a, @b;   ## First line/element is element 0
101
102       If you want to force a first record number of 0, use "eq_or_diff_data".
103       If you want to force a first record number of 1, use "eq_or_diff_text".
104       I chose this over passing in an options hash because it's clearer and
105       simpler this way.  YMMV.
106

OPTIONS

108       There is currently only one option: "context".  This allows you to con‐
109       trol the amount of context shown:
110
111          eq_or_diff $got, $expected, $name, { context => 50000};
112
113       will show you lots and lots of context.  Normally, eq_or_diff() uses
114       some heuristics to determine whether to show 3 lines of context (like a
115       normal unified diff) or 25 lines (for
116

Deploying Test::Differences

118       There are three basic ways of deploying Test::Differences requiring
119       more or less labor by you or your users.
120
121       ·   eval "use Test::Differences";
122
123           This is the easiest option.
124
125           If you want to detect the presence of Test::Differences on the fly,
126           something like the following code might do the trick for you:
127
128               use Test qw( !ok );   ## get all syms *except* ok
129
130               eval "use Test::Differences";
131               use Data::Dumper;
132
133               sub ok {
134                   goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
135                   @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
136                   goto Test::&ok;
137               }
138
139               plan tests => 1;
140
141               ok "a", "b";
142
143       ·   PREREQ_PM => { .... "Test::Differences" => 0, ... }
144
145           This method will let CPAN and CPANPLUS users download it automati‐
146           cally.  It will discomfit those users who choose/have to download
147           all packages manually.
148
149       ·   t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
150
151           By placing Test::Differences and it's prerequisites in the t/lib
152           directory, you avoid forcing your users to download the Test::Dif‐
153           ferences manually if they aren't using CPAN or CPANPLUS.
154
155           If you put a "use lib "t/lib";" in the top of each test suite
156           before the "use Test::Differences;", "make test" should work well.
157
158           You might want to check once in a while for new Test::Differences
159           releases if you do this.
160

LIMITATIONS

162       This module "mixes in" with Test.pm or any of the test libraries based
163       on Test::Builder (Test::Simple, Test::More, etc).  It does this by
164       peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
165       are not using one of those, it will print a warning and play dumb by
166       not emitting test numbers (or incrementing them).  If you are using one
167       of these, it should interoperate nicely.
168
169       Uses Data::Dumper for complex data structures (like hashes :), which
170       can lead to some problems on older perls.
171
172       Exports all 3 functions by default (and by design).  Use
173
174           use Test::Differences ();
175
176       to suppress this behavior if you don't like the namespace pollution.
177
178       This module will not override functions like ok(), is(), is_deeply(),
179       etc.  If it did, then you could "eval "use Test::Differences qw(
180       is_deeply );"" to get automatic upgrading to diffing behaviors without
181       the "sub my_ok" shown above.  Test::Differences intentionally does not
182       provide this behavior because this would mean that Test::Differences
183       would need to emulate every popular test module out there, which would
184       require far more coding and maintenance that I'm willing to do.  Use
185       the eval and my_ok deployment shown above if you want some level of au‐
186       tomation.
187

LIMITATIONS

189       Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
190       seems broken.  This means that you might get odd results using
191       perl5.6.0 with unicode strings.
192
193       Relies on Data::Dumper (for now), which, prior to perl5.8, will not
194       always report hashes in the same order.   $Data::Dumper::SortKeys is
195       set to 1, so on more recent versions of Data::Dumper, this should not
196       occur.  Check CPAN to see if it's been peeled out of the main perl dis‐
197       tribution and backported.  Reported by Ilya Martynov <ilya@mar‐
198       tynov.org>, although the SortKeys "future perfect" workaround has been
199       set in anticipation of a new Data::Dumper for a while.  Note that the
200       two hashes should report the same here:
201
202           not ok 5
203           #     Failed test (t/ctrl/05-home.t at line 51)
204           # +----+------------------------+----+------------------------+
205           # ⎪ Elt⎪Got                     ⎪ Elt⎪Expected                ⎪
206           # +----+------------------------+----+------------------------+
207           # ⎪   0⎪{                       ⎪   0⎪{                       ⎪
208           # ⎪   1⎪  'password' => '',     ⎪   1⎪  'password' => '',     ⎪
209           # *   2⎪  'method' => 'login',  *    ⎪                        ⎪
210           # ⎪   3⎪  'ctrl' => 'home',     ⎪   2⎪  'ctrl' => 'home',     ⎪
211           # ⎪    ⎪                        *   3⎪  'method' => 'login',  *
212           # ⎪   4⎪  'email' => 'test'     ⎪   4⎪  'email' => 'test'     ⎪
213           # ⎪   5⎪}                       ⎪   5⎪}                       ⎪
214           # +----+------------------------+----+------------------------+
215
216       Data::Dumper also overlooks the difference between
217
218           $a[0] = \$a[1];
219           $a[1] = \$a[0];   # $a[0] = \$a[1]
220
221       and
222
223           $x = \$y;
224           $y = \$x;
225           @a = ( $x, $y );  # $a[0] = \$y, not \$a[1]
226
227       The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
228       This was carefully explained to me in words of two syllables or less by
229       Yves Orton <demerphq@hotmail.com>.  The plan to address this is to
230       allow you to select Data::Denter or some other module of your choice as
231       an option.
232

AUTHOR

234           Barrie Slaymaker <barries@slaysys.com>
235

LICENSE

237       Copyright 2001 Barrie Slaymaker, All Rights Reserved.
238
239       You may use this software under the terms of the GNU public license,
240       any version, or the Artistic license.
241
242
243
244perl v5.8.8                       2003-06-16                    Differences(3)
Impressum