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";

## 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 ...;

DESCRIPTION

When the code you're testing returns multiple lines or records and they're just plain wrong, sometimes an equivalent to the Unix diff utility is just what's needed.

eq_or_diff_...() compares two strings or (limited) data structures and either emits an ok indication (if they are equal) or calls a side-by-side diff (if they differ) like:

not ok 10
# +-----+----------+
# | Got | Expected |
# +-----+----------+
# > a   * b        <
# +-----+----------+

These functions assume that you are presenting it with "flat" records, looking like:

- scalars composed of record-per-line
- arrays of scalars,
- arrays of arrays of scalars,
- arrays of hashes containing only scalars

All of these are flattened in to single strings which are then compared for differences. Differently data structures can be compared, as long as they flatten identically.

All other data structures are run through Data::Dumper first. This is a bit dangerous, as some version of perl shipped with Data::Dumpers that could do the oddest things with some input. This will be changed to an internal dumper with good backward compatability when this bites somebody or I get some free time.

All nonprintable characters (including "\n" or "\r\n") are converted to an escape code of some sort, since nonprinting characters can make identical looking strings different. This is especially true when comparing things on platforms like Win32 where "\n" and "\r\n" usually look identical when perl prints them, and a text file missing "\n" on the last line can ruin your whole day and make you go blind. This can be a bit ugly, but, hey, these are failing tests were talking about here, not hand-set epic poems.

eq_or_diff() starts counting records at 0 unless you pass it two text strings:

eq_or_diff $a, $b;   ## First line is line number 1
eq_or_diff @a, @b;   ## First element is element 0
eq_or_diff $a, @b;   ## First line/element is element 0

If you want to force a first record number of 0, use eq_or_diff_data. If you want to force a first record number of 1, use eq_or_diff_text. I chose this over passing in an options hash because it's clearer and simpler this way. YMMV.

LIMITATIONS

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.

Uses Data::Dumper for complex data structures (like hashes :), which can lead to some problems on older perls.

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

use Test::Differences ();

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

AUTHOR

Barrie Slaymaker <barries@slaysys.com>

LICENSE

Copyright 2001 Barrie Slaymaker, All Rights Reserved.

You may use this software under the terms of the GNU public license, any version, or the Artistic license.