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:

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.

OPTIONS

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

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. See eq_or_diff_text and eq_or_diff_data to understand this. You can usually ignore this.

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:

useTest::More'no_plan';useTest::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 typetable_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.

This method will let CPAN and CPANPLUS users download it automatically. It will discomfit those users who choose/have to download all packages manually.

t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...

By placing Test::Differences and its prerequisites in the t/lib directory, you avoid forcing your users to download the Test::Differences manually if they aren't using CPAN or CPANPLUS.

If you put a uselib"t/lib"; in the top of each test suite before the useTest::Differences;, make test should work well.

You might want to check once in a while for new Test::Differences releases if you do this.

LIMITATIONS

Test or Test::More

This module "mixes in" with Test.pm or any of the test libraries based on Test::Builder (Test::Simple, Test::More, etc). It does this by peeking to see whether Test.pm or Test/Builder.pm is in %INC, so if you are not using one of those, it will print a warning and play dumb by not emitting test numbers (or incrementing them). If you are using one of these, it should interoperate nicely.

Exporting

Exports all 3 functions by default (and by design). Use

useTest::Differences();

to suppress this behavior if you don't like the namespace pollution.

This module will not override functions like ok(), is(), is_deeply(), etc. If it did, then you could eval"use Test::Differences qw( is_deeply );" to get automatic upgrading to diffing behaviors without the sub my_ok shown above. Test::Differences intentionally does not provide this behavior because this would mean that Test::Differences would need to emulate every popular test module out there, which would require far more coding and maintenance that I'm willing to do. Use the eval and my_ok deployment shown above if you want some level of automation.

Unicode

Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0 seems broken. This means that you might get odd results using perl5.6.0 with unicode strings.

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:

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.