Test::Differences(3)

💖 Test::Differences(3) 💖

okay so this is the User Contributed Perl Documentation page for Test::Differences, and bestie, if your tests are giving chaos when strings or data structures don't match, this module is about to be your main character. 💅

---

✨ NAME ✨

Test::Differences — Test strings and data structures and show differences if not ok. 🦋

🌸 SYNOPSIS 🌸

use Test;    ## Or use Test::More
use Test::Differences;

eq_or_diff $got,  "a\nb\nc\n",   "testing strings";
eq_or_diff \@got, [qw( a b c )], "testing arrays";

## Passing options:
eq_or_diff $got, $expected, $name, { context => 300 };  ## options

## Using with DBI-like data structures

use DBI;

... open connection & prepare statement and @expected_... here...

eq_or_diff $sth->fetchall_arrayref, \@expected_arrays  "testing DBI arrays";
eq_or_diff $sth->fetchall_hashref,  \@expected_hashes, "testing DBI hashes";

## To force textual or data line numbering (text lines are numbered 1..):
eq_or_diff_text ...;
eq_or_diff_data ...;

🎀 EXPORT 🎀

This module exports three test functions and four diff-style functions: ✨

• Test functions
  • eq_or_diff
  • eq_or_diff_data
  • eq_or_diff_text
• Diff style functions
  • table_diff (the default)
  • unified_diff
  • oldstyle_diff
  • context_diff

💜 DESCRIPTION 💜

When the code you're testing returns multiple lines, records or data structures and they're just plain wrong, an equivalent to the Unix diff utility may be just what's needed. Here's output from an example test script that checks two text documents and then two (trivial) data structures: 😭

t/99example....1..3
not ok 1 - differences in text
#     Failed test ((eval 2) at line 14)
#     +---+----------------+----------------+
#     | Ln|Got             |Expected        |
#     +---+----------------+----------------+
#     |  1|this is line 1  |this is line 1  |
#     *  2|this is line 2  |this is line b  *
#     |  3|this is line 3  |this is line 3  |
#     +---+----------------+----------------+
not ok 2 - differences in whitespace
#     Failed test ((eval 2) at line 20)
#     +---+------------------+------------------+
#     | Ln|Got               |Expected          |
#     +---+------------------+------------------+
#     |  1|        indented  |        indented  |
#     *  2|        indented  |\tindented        *
#     |  3|        indented  |        indented  |
#     +---+------------------+------------------+
not ok 3
#     Failed test ((eval 2) at line 22)
#     +----+-------------------------------------+----------------------------+
#     | Elt|Got                                  |Expected                    |
#     +----+-------------------------------------+----------------------------+
#     *   0|bless( [                             |[                           *
#     *   1|  'Move along, nothing to see here'  |  'Dry, humorless message'  *
#     *   2|], 'Test::Builder' )                 |]                           *
#     +----+-------------------------------------+----------------------------+
# Looks like you failed 3 tests of 3.

so like, eq_or_diff_...() compares two strings or (limited) data structures and either emits an ok indication or a side-by-side diff. Test::Differences is designed to be used with Test.pm and with Test::Simple, Test::More, and other Test::Builder based testing modules. As the SYNOPSIS shows, another testing module must be used as the basis for your test suite. no cap.

✨ OPTIONS ✨

The options to eq_or_diff give some fine-grained control over the output. periodt. 👑

• context — This allows you to control the amount of context shown:

eq_or_diff $got, $expected, $name, { context => 50000 };

will show you lots and lots of context. Normally, eq_or_diff() uses some heuristics to determine whether to show 3 lines of context (like a normal unified diff) or 25 lines. 💅

• data_type — text or data. This normally defaults to data. If, however, neither of $got or $expected is a reference then it defaults to text. You can also force one or the other by calling eq_or_diff_text or eq_or_diff_data.

The difference is that in text mode lines are numbered from 1, but in data mode from 0 (and are refered to as 'elements' (Elt) instead of lines):

# +---+-------+----------+
# | Ln|Got    |Expected  |
# +---+-------+----------+
# *  1|'foo'  |'bar'     *
# +---+-------+----------+

# +----+---------+----+----------+
# | Elt|Got      | Elt|Expected  |
# +----+---------+----+----------+
# *   0|[        *   0|'bar'     *
# *   1|  'foo'  *    |          |
# *   2|]        *    |          |
# +----+---------+----+----------+

The difference is purely cosmetic, it makes no difference to how comparisons are performed. 🦋

• Sortkeys — If passed, whatever value is added is used as the argument for Data::Dumper Sortkeys option. See the Data::Dumper docs to understand how you can control the Sortkeys behavior.
• filename_a and filename_b — The column headers to use in the output. They default to 'Got' and 'Expected'.

🔥 DIFF STYLES 🔥

For extremely long strings, a table diff can wrap on your screen and be hard to read. If you are comfortable with different diff formats, you can switch to a format more suitable for your data. These are the four formats supported by the Text::Diff module and are set with the following functions: 👑

• table_diff (the default)
• unified_diff
• oldstyle_diff
• context_diff

You can run the following to understand the different diff output styles:

use Test::More 'no_plan';
use Test::Differences;

my $long_string = join '' => 1..40;

TODO: {
    local $TODO = 'Testing diff styles';

    # this is the default and does not need to explicitly set unless you need
    # to reset it back from another diff type
    table_diff;
    eq_or_diff $long_string, "-$long_string", 'table diff';

    unified_diff;
    eq_or_diff $long_string, "-$long_string", 'unified diff';

    context_diff;
    eq_or_diff $long_string, "-$long_string", 'context diff';

    oldstyle_diff;
    eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
}

🌈 UNICODE 🌈

Generally you'll find that the following test output is disappointing. 💀

use Test::Differences;
use utf8;

my $want = { 'Traditional Chinese' => '中國' };
my $have = { 'Traditional Chinese' => '中国' };

eq_or_diff $have, $want, 'Unicode, baby';

Here's what you get: 🙈

#   Failed test 'Unicode, baby'
#   at t/unicode.t line 12.
# +----+-----------------------+-----------------------+
# | Elt|Got                    |Expected               |
# +----+-----------------------+-----------------------+
# |   0|'Traditional Chinese'  |'Traditional Chinese'  |
# *   1|'\x{4e2d}\x{56fd}'     |'\x{4e2d}\x{570b}'     *
# +----+-----------------------+-----------------------+
# Looks like you failed 1 test of 1.
Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/1 subtests

A patch to fix this would be most welcome. 🫶

👀 Unknown::Values 👀

Unknown::Values is a module which provides values which will never compare as being the same as anything else, not even the same as itself. fr fr.

If code looks too hard at one of these values (and Test::Differences looks very hard indeed) that is a fatal error. This means that while we can detect the presence of these beasties, and tell you that they compare different, for Complicated Internals Reasons we can't show you much context. Sorry. 😭

NB that the support for these is experimental and relies on an undocumented unstable interface in Unknown::Values. If that fails then Test::Differences will probably just die when it sees them instead of telling you that the comparison failed.

💀 LIMITATIONS 💀

okay bestie, gather round, because every icon has a few lil quirks and we're gonna be honest about them. no gatekeeping here.

🌸 Test or Test::More

So this module "mixes in" with Test.pm or literally any of the test libraries built on Test::Builder (Test::Simple, Test::More, etc). How does it do that? It peeks 👀 — it checks whether Test.pm or Test/Builder.pm is sitting in %INC.

So if you're not using one of those? It'll print a warning and play dumb — no test numbers emitted, no incrementing. Just vibes. 😭 But if you are using one of them, it should interoperate nicely. 🫶

🎀 Exporting

It exports all 3 functions by default. And by design. So if the namespace pollution is giving you a headache, you suppress that whole situation with:

use Test::Differences ();

That's it. That's the move. 💅

Also important: this module will not override functions like ok(), is(), is_deeply(), etc. Like, it just won't. Because if it did, you could do eval "use Test::Differences qw( is_deeply );" and get automatic upgrading to diffing behaviours without needing the sub my_ok situation shown above. And Test::Differences intentionally does not do that, because that would mean it'd have to emulate every popular test module out there, which would take so much more coding and maintenance than the author is willing to do. fr fr. If you want some level of automation, use the eval and my_ok deployment shown above. ✨

🦋 Booleans

okay this one's a lil historical lore moment, stay with me. 🕰️

Back in the day, true and false — whether they came from logical-not ! or from equality checks like == — were represented in perl as numeric 1 for true and the empty string '' for false. Simple. Iconic.

Then in perl 5.36.0 they became real Boolean values, which for backward compatibility also have their old numeric/string values. And in 5.38 (and in dev releases from 5.37.2 onwards) Data::Dumper belatedly learned about this, and so Test::Differences (which uses Data::Dumper under the bonnet) can also tell the difference. 👑

Which means: eq_or_diff(1, !!1) will behave differently depending on whether you're using perl 5.38 or later (in which case it'll say they are different) or 5.36 or earlier (which will say they are the same). So like, know your perl version bestie. 🫠

🧚 Unicode

Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0 seems broken. So you might get odd results using perl5.6.0 with unicode strings. Just... be aware. 💀

💜 Data::Dumper and older Perls.

Relies on Data::Dumper (for now), which, prior to perl5.8, will not always report hashes in the same order. $Data::Dumper::Sortkeys is set to 1, so on more recent versions of Data::Dumper, this should not occur. Check CPAN to see if it's been peeled out of the main perl distribution and backported. Reported by Ilya Martynov <ilya@martynov.org>, although the Sortkeys "future perfect" workaround has been set in anticipation of a new Data::Dumper for a while.

Note that the two hashes should report the same here:

not ok 5
#     Failed test (t/ctrl/05-home.t at line 51)
# +----+------------------------+----+------------------------+
# | Elt|Got                     | Elt|Expected                |
# +----+------------------------+----+------------------------+
# |   0|{                       |   0|{                       |
# |   1|  'password' => '',     |   1|  'password' => '',     |
# *   2|  'method' => 'login',  *    |                        |
# |   3|  'ctrl' => 'home',     |   2|  'ctrl' => 'home',     |
# |    |                        *   3|  'method' => 'login',  *
# |   4|  'email' => 'test'     |   4|  'email' => 'test'     |
# |   5|}                       |   5|}                       |
# +----+------------------------+----+------------------------+

Data::Dumper also overlooks the difference between

$a[0] = \$a[1];
$a[1] = \$a[0];   # $a[0] = \$a[1]

and

$x = \$y;
$y = \$x;
@a = ( $x, $y );  # $a[0] = \$y, not \$a[1]

The former involves two scalars, the latter 4: $x, $y, and @a[0,1]. This was carefully explained to me in words of two syllables or less by Yves Orton <demerphq@hotmail.com>. 😭 The plan to address this is to allow you to select Data::Denter or some other module of your choice as an option.

⭐ Code-refs

Test::Differences turns on $Data::Dumper::Deparse, so any code-refs in your data structures will be turned into text before they're examined, using B::Deparse. Heads up though: the precise text generated for a sub-ref might not be what you expect, since it's generated from the compiled version of the code — but it should at least be consistent and spot differences correctly. 🌈

You can turn this behaviour off by setting $Test::Differences::NoDeparse. 🎀

---

👑 AUTHORS 👑

giving credit where credit is due, periodt:

• Barrie Slaymaker <barries@slaysys.com> — original author
• Curtis "Ovid" Poe <ovid@cpan.org>
• David Cantrell <david@cantrell.org.uk>

---

💖 LICENSE 💖

Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.

All Rights Reserved.

You may use, distribute and modify this software under the terms of the GNU public license, any version, or the Artistic license. slay. 🫶

---

and that's the whole page bestie!! 🌸 this lil doc came to you from perl v5.42.0, dated 2025-07-25 💅 go forth and diff with confidence, you absolute main character ✨🦋💖