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". See "eq_or_diff_text" and "eq_or_diff_data" to
114           understand this. You can usually ignore this.
115
116       ·   "Sortkeys"
117
118           If passed, whatever value is added is used as the argument for
119           Data::Dumper Sortkeys option. See the Data::Dumper docs to
120           understand how you can control the Sortkeys behavior.
121
122       ·   "filename_a" and "filename_b"
123
124           The column headers to use in the output. They default to 'Got' and
125           'Expected'.
126

DIFF STYLES

128       For extremely long strings, a table diff can wrap on your screen and be
129       hard to read.  If you are comfortable with different diff formats, you
130       can switch to a format more suitable for your data.  These are the four
131       formats supported by the Text::Diff module and are set with the
132       following functions:
133
134       ·   "table_diff" (the default)
135
136       ·   "unified_diff"
137
138       ·   "oldstyle_diff"
139
140       ·   "context_diff"
141
142       You can run the following to understand the different diff output
143       styles:
144
145        use Test::More 'no_plan';
146        use Test::Differences;
147
148        my $long_string = join '' => 1..40;
149
150        TODO: {
151            local $TODO = 'Testing diff styles';
152
153            # this is the default and does not need to explicitly set unless you need
154            # to reset it back from another diff type
155            table_diff;
156            eq_or_diff $long_string, "-$long_string", 'table diff';
157
158            unified_diff;
159            eq_or_diff $long_string, "-$long_string", 'unified diff';
160
161            context_diff;
162            eq_or_diff $long_string, "-$long_string", 'context diff';
163
164            oldstyle_diff;
165            eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
166        }
167

UNICODE

169       Generally you'll find that the following test output is disappointing.
170
171           use Test::Differences;
172
173           my $want = { 'Traditional Chinese' => '中國' };
174           my $have = { 'Traditional Chinese' => '中国' };
175
176           eq_or_diff $have, $want, 'Unicode, baby';
177
178       The output looks like this:
179
180           #   Failed test 'Unicode, baby'
181           #   at t/unicode.t line 12.
182           # +----+----------------------------+----------------------------+
183           # | Elt|Got                         |Expected                    |
184           # +----+----------------------------+----------------------------+
185           # |   0|'Traditional Chinese'       |'Traditional Chinese'       |
186           # *   1|'\xe4\xb8\xad\xe5\x9b\xbd'  |'\xe4\xb8\xad\xe5\x9c\x8b'  *
187           # +----+----------------------------+----------------------------+
188           # Looks like you failed 1 test of 1.
189           Dubious, test returned 1 (wstat 256, 0x100)
190
191       This is generally not helpful and someone points out that you didn't
192       declare your test program as being utf8, so you do that:
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       That's better, but still awful. However, if you have "Text::Diff" 0.40
217       or higher installed, you can add this to your code:
218
219           BEGIN { $ENV{DIFF_OUTPUT_UNICODE} = 1 }
220
221       Make sure you do this before you load Text::Diff. Then this is the
222       output:
223
224           # +----+-----------------------+-----------------------+
225           # | Elt|Got                    |Expected               |
226           # +----+-----------------------+-----------------------+
227           # |   0|'Traditional Chinese'  |'Traditional Chinese'  |
228           # *   1|'中国'                 |'中國'                 *
229           # +----+-----------------------+-----------------------+
230

DEPLOYING

232       There are several basic ways of deploying Test::Differences requiring
233       more or less labor by you or your users.
234
235       ·   Fallback to "is_deeply".
236
237           This is your best option if you want this module to be optional.
238
239            use Test::More;
240            BEGIN {
241                if (!eval q{ use Test::Differences; 1 }) {
242                    *eq_or_diff = \&is_deeply;
243                }
244            }
245
246       ·
247
248
249            eval "use Test::Differences";
250
251           If you want to detect the presence of Test::Differences on the fly,
252           something like the following code might do the trick for you:
253
254               use Test qw( !ok );   ## get all syms *except* ok
255
256               eval "use Test::Differences";
257               use Data::Dumper;
258
259               sub ok {
260                   goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
261                   @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
262                   goto Test::&ok;
263               }
264
265               plan tests => 1;
266
267               ok "a", "b";
268
269       ·   PREREQ_PM => { .... "Test::Differences" => 0, ... }
270
271           This method will let CPAN and CPANPLUS users download it
272           automatically.  It will discomfit those users who choose/have to
273           download all packages manually.
274
275       ·   t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
276
277           By placing Test::Differences and its prerequisites in the t/lib
278           directory, you avoid forcing your users to download the
279           Test::Differences manually if they aren't using CPAN or CPANPLUS.
280
281           If you put a "use lib "t/lib";" in the top of each test suite
282           before the "use Test::Differences;", "make test" should work well.
283
284           You might want to check once in a while for new Test::Differences
285           releases if you do this.
286

LIMITATIONS

288   "Test" or "Test::More"
289       This module "mixes in" with Test.pm or any of the test libraries based
290       on Test::Builder (Test::Simple, Test::More, etc).  It does this by
291       peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you
292       are not using one of those, it will print a warning and play dumb by
293       not emitting test numbers (or incrementing them).  If you are using one
294       of these, it should interoperate nicely.
295
296   Exporting
297       Exports all 3 functions by default (and by design).  Use
298
299           use Test::Differences ();
300
301       to suppress this behavior if you don't like the namespace pollution.
302
303       This module will not override functions like ok(), is(), is_deeply(),
304       etc.  If it did, then you could "eval "use Test::Differences qw(
305       is_deeply );"" to get automatic upgrading to diffing behaviors without
306       the "sub my_ok" shown above.  Test::Differences intentionally does not
307       provide this behavior because this would mean that Test::Differences
308       would need to emulate every popular test module out there, which would
309       require far more coding and maintenance that I'm willing to do.  Use
310       the eval and my_ok deployment shown above if you want some level of
311       automation.
312
313   Unicode
314       Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
315       seems broken.  This means that you might get odd results using
316       perl5.6.0 with unicode strings.
317
318   "Data::Dumper" and older Perls.
319       Relies on Data::Dumper (for now), which, prior to perl5.8, will not
320       always report hashes in the same order.   $Data::Dumper::Sortkeys  is
321       set to 1, so on more recent versions of Data::Dumper, this should not
322       occur.  Check CPAN to see if it's been peeled out of the main perl
323       distribution and backported.  Reported by Ilya Martynov
324       <ilya@martynov.org>, although the Sortkeys "future perfect" workaround
325       has been set in anticipation of a new Data::Dumper for a while.  Note
326       that the two hashes should report the same here:
327
328           not ok 5
329           #     Failed test (t/ctrl/05-home.t at line 51)
330           # +----+------------------------+----+------------------------+
331           # | Elt|Got                     | Elt|Expected                |
332           # +----+------------------------+----+------------------------+
333           # |   0|{                       |   0|{                       |
334           # |   1|  'password' => '',     |   1|  'password' => '',     |
335           # *   2|  'method' => 'login',  *    |                        |
336           # |   3|  'ctrl' => 'home',     |   2|  'ctrl' => 'home',     |
337           # |    |                        *   3|  'method' => 'login',  *
338           # |   4|  'email' => 'test'     |   4|  'email' => 'test'     |
339           # |   5|}                       |   5|}                       |
340           # +----+------------------------+----+------------------------+
341
342       Data::Dumper also overlooks the difference between
343
344           $a[0] = \$a[1];
345           $a[1] = \$a[0];   # $a[0] = \$a[1]
346
347       and
348
349           $x = \$y;
350           $y = \$x;
351           @a = ( $x, $y );  # $a[0] = \$y, not \$a[1]
352
353       The former involves two scalars, the latter 4: $x, $y, and @a[0,1].
354       This was carefully explained to me in words of two syllables or less by
355       Yves Orton <demerphq@hotmail.com>.  The plan to address this is to
356       allow you to select Data::Denter or some other module of your choice as
357       an option.
358
359   Code-refs
360       Test::Differences turns on $Data::Dumper::Deparse, so any code-refs in
361       your data structures will be turned into text before they are examined,
362       using B::Deparse. The precise text generated for a sub-ref might not be
363       what you expect as it is generated from the compiled version of the
364       code, but it should at least be consistent and spot differences
365       correctly.
366
367       You can turn this behaviour off by setting
368       $Test::Differences::NoDeparse.
369

AUTHORS

371           Barrie Slaymaker <barries@slaysys.com> - original author
372
373           Curtis "Ovid" Poe <ovid@cpan.org>
374
375           David Cantrell <david@cantrell.org.uk>
376

LICENSE

378       Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.
379
380       All Rights Reserved.
381
382       You may use, distribute and modify this software under the terms of the
383       GNU public license, any version, or the Artistic license.
384
385
386
387perl v5.30.1                      2020-01-30              Test::Differences(3)
Impressum