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

OPTIONS

98       The options to "eq_or_diff" give some fine-grained control over the
99       output.
100
101       •   "context"
102
103           This allows you to control the amount of context shown:
104
105              eq_or_diff $got, $expected, $name, { context => 50000 };
106
107           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
111       •   "data_type"
112
113           "text" or "data". This normally defaults to "data". If, however,
114           neither of $got or $expected is a reference then  it defaults to
115           "text". You can also force one or the other by calling
116           "eq_or_diff_text" or "eq_or_diff_data".
117
118           The difference is that in text mode lines are numbered from 1, but
119           in data mode from 0 (and are refered to as 'elements' (Elt) instead
120           of lines):
121
122               # +---+-------+----------+
123               # | Ln|Got    |Expected  |
124               # +---+-------+----------+
125               # *  1|'foo'  |'bar'     *
126               # +---+-------+----------+
127
128               # +----+---------+----+----------+
129               # | Elt|Got      | Elt|Expected  |
130               # +----+---------+----+----------+
131               # *   0|[        *   0|'bar'     *
132               # *   1|  'foo'  *    |          |
133               # *   2|]        *    |          |
134               # +----+---------+----+----------+
135
136           The difference is purely cosmetic, it makes no difference to how
137           comparisons are performed.
138
139       •   "Sortkeys"
140
141           If passed, whatever value is added is used as the argument for
142           Data::Dumper Sortkeys option. See the Data::Dumper docs to
143           understand how you can control the Sortkeys behavior.
144
145       •   "filename_a" and "filename_b"
146
147           The column headers to use in the output. They default to 'Got' and
148           'Expected'.
149

DIFF STYLES

151       For extremely long strings, a table diff can wrap on your screen and be
152       hard to read.  If you are comfortable with different diff formats, you
153       can switch to a format more suitable for your data.  These are the four
154       formats supported by the Text::Diff module and are set with the
155       following functions:
156
157       •   "table_diff" (the default)
158
159       •   "unified_diff"
160
161       •   "oldstyle_diff"
162
163       •   "context_diff"
164
165       You can run the following to understand the different diff output
166       styles:
167
168        use Test::More 'no_plan';
169        use Test::Differences;
170
171        my $long_string = join '' => 1..40;
172
173        TODO: {
174            local $TODO = 'Testing diff styles';
175
176            # this is the default and does not need to explicitly set unless you need
177            # to reset it back from another diff type
178            table_diff;
179            eq_or_diff $long_string, "-$long_string", 'table diff';
180
181            unified_diff;
182            eq_or_diff $long_string, "-$long_string", 'unified diff';
183
184            context_diff;
185            eq_or_diff $long_string, "-$long_string", 'context diff';
186
187            oldstyle_diff;
188            eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
189        }
190

UNICODE

192       Generally you'll find that the following test output is disappointing.
193
194           use Test::Differences;
195           use utf8;
196
197           my $want = { 'Traditional Chinese' => '中國' };
198           my $have = { 'Traditional Chinese' => '中国' };
199
200           eq_or_diff $have, $want, 'Unicode, baby';
201
202       Here's what you get:
203
204           #   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
216       A patch to fix this would be *most* welcome.
217

Unknown::Values

219       Unknown::Values is a module which provides values which will never
220       compare as being the same as anything else, not even the same as
221       itself.
222
223       If code looks too hard at one of these values (and Test::Differences
224       looks very hard indeed) that is a fatal error. This means that while we
225       can detect the presence of these beasties, and tell you that they
226       compare different, for Complicated Internals Reasons we can't show you
227       much context. Sorry.
228
229       NB that the support for these is experimental and relies on an
230       undocumented unstable interface in Unknown::Values. If that fails then
231       Test::Differences will probably just die when it sees them instead of
232       telling you that the comparison failed.
233

LIMITATIONS

235   "Test" or "Test::More"
236       This module "mixes in" with Test.pm or any of the test libraries based
237       on Test::Builder (Test::Simple, Test::More, etc).  It does this by
238       peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
239       are not using one of those, it will print a warning and play dumb by
240       not emitting test numbers (or incrementing them).  If you are using one
241       of these, it should interoperate nicely.
242
243   Exporting
244       Exports all 3 functions by default (and by design).  Use
245
246           use Test::Differences ();
247
248       to suppress this behavior if you don't like the namespace pollution.
249
250       This module will not override functions like ok(), is(), is_deeply(),
251       etc.  If it did, then you could "eval "use Test::Differences qw(
252       is_deeply );"" to get automatic upgrading to diffing behaviors without
253       the "sub my_ok" shown above.  Test::Differences intentionally does not
254       provide this behavior because this would mean that Test::Differences
255       would need to emulate every popular test module out there, which would
256       require far more coding and maintenance that I'm willing to do.  Use
257       the eval and my_ok deployment shown above if you want some level of
258       automation.
259
260   Unicode
261       Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
262       seems broken.  This means that you might get odd results using
263       perl5.6.0 with unicode strings.
264
265   "Data::Dumper" and older Perls.
266       Relies on Data::Dumper (for now), which, prior to perl5.8, will not
267       always report hashes in the same order.   $Data::Dumper::Sortkeys  is
268       set to 1, so on more recent versions of Data::Dumper, this should not
269       occur.  Check CPAN to see if it's been peeled out of the main perl
270       distribution and backported.  Reported by Ilya Martynov
271       <ilya@martynov.org>, although the Sortkeys "future perfect" workaround
272       has been set in anticipation of a new Data::Dumper for a while.  Note
273       that the two hashes should report the same here:
274
275           not ok 5
276           #     Failed test (t/ctrl/05-home.t at line 51)
277           # +----+------------------------+----+------------------------+
278           # | Elt|Got                     | Elt|Expected                |
279           # +----+------------------------+----+------------------------+
280           # |   0|{                       |   0|{                       |
281           # |   1|  'password' => '',     |   1|  'password' => '',     |
282           # *   2|  'method' => 'login',  *    |                        |
283           # |   3|  'ctrl' => 'home',     |   2|  'ctrl' => 'home',     |
284           # |    |                        *   3|  'method' => 'login',  *
285           # |   4|  'email' => 'test'     |   4|  'email' => 'test'     |
286           # |   5|}                       |   5|}                       |
287           # +----+------------------------+----+------------------------+
288
289       Data::Dumper also overlooks the difference between
290
291           $a[0] = \$a[1];
292           $a[1] = \$a[0];   # $a[0] = \$a[1]
293
294       and
295
296           $x = \$y;
297           $y = \$x;
298           @a = ( $x, $y );  # $a[0] = \$y, not \$a[1]
299
300       The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
301       This was carefully explained to me in words of two syllables or less by
302       Yves Orton <demerphq@hotmail.com>.  The plan to address this is to
303       allow you to select Data::Denter or some other module of your choice as
304       an option.
305
306   Code-refs
307       Test::Differences turns on $Data::Dumper::Deparse, so any code-refs in
308       your data structures will be turned into text before they are examined,
309       using B::Deparse. The precise text generated for a sub-ref might not be
310       what you expect as it is generated from the compiled version of the
311       code, but it should at least be consistent and spot differences
312       correctly.
313
314       You can turn this behaviour off by setting
315       $Test::Differences::NoDeparse.
316

AUTHORS

318           Barrie Slaymaker <barries@slaysys.com> - original author
319
320           Curtis "Ovid" Poe <ovid@cpan.org>
321
322           David Cantrell <david@cantrell.org.uk>
323

LICENSE

325       Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.
326
327       All Rights Reserved.
328
329       You may use, distribute and modify this software under the terms of the
330       GNU public license, any version, or the Artistic license.
331
332
333
334perl v5.38.0                      2023-07-21              Test::Differences(3)
Impressum