Please feel free to test and suggest :).
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" ; # lines numbered 1...
eq_or_diff \@got, [qw( a b c )], "testing arrays" ; # elts numbered 0...
# Using with DBI-like data structures
eq_or_diff $sth->fetchall_arrayref, \@exp_arrays ;
eq_or_diff $sth->fetchall_hashref, \@exp_hashes ;
# To force textual or data line numbering
eq_or_diff_text @got_lines, \@exp_lines ; # elements numbered 1...
eq_or_diff_data $foo, $bar ; # lines numbered 0...
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() compare two strings or (limited) data structures and either
emits an ok indication (if they are equal) or 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
Data of these types are flattened in to single strings which are then
compared for differences. Differently data structures can be compared,
as long as they flatten identically. Hashes are presented in columnar
format with the first line having the titles.
All other data structures are run through Data::Dumper first. This is a
bit dangerous, see the LIMITATIONS entry elsewhere in this document. On
newer Data::Dumpers (after perl5.6.1), hash keys will be sorted. If you
have embedded code refs, Data::Dumper cannot tell if they are different.
All nonprintable characters (including "\n" or "\r\n") are converted to
escape codes ("\n", "\0x00"), 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. On "\n"-ary systems, 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-typeset epic poems.
"eq_or_diff()" starts counting records at 0 unless you pass it two text
strings:
eq_or_diff $a, $b, $name ; ## First line is line number 1
eq_or_diff @a, @b, $name ; ## First element is element 0
eq_or_diff $a, @b, $name ; ## 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 to offer two additional functions instead of passing in an
options hash because it's clearer and simpler this way. YMMV.
LIMITATIONS
Uses Data::Dumper for complex data structures (like hashes :), which can
lead to some problems on older perls. Expect this to change as time
permits.
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.
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.
At this time, each data structure is flattened independantly, which
looks goofy if one goes through Data::Dumper and the other doesn't.
AUTHOR
Barrie Slaymaker <[EMAIL PROTECTED]>
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.
