Test::BinaryData - compare two things, give hex dumps if they differ
my $computed_data = do_something_complicated;
my $expected_data = read_file('correct.data');
"basic data computation",
Sometimes using Test::More's is test isn't good enough. Its diagnostics may make it easy to miss differences between strings.
For example, given two strings which differ only in their line endings, you can end up with diagnostic output like this:
not ok 1
# Failed test in demo.t at line 8.
# got: 'foo
# expected: 'foo
That's not very helpful, except to tell you that the alphanumeric characters seem to be in the right place. By using is_binary instead of is, this output would be generated instead:
not ok 2
# Failed test in demo.t at line 10.
# have (hex) have want (hex) want
# 666f6f0a6261720a---- foo.bar. ! 666f6f0d0a6261720d0a foo..bar..
The "!" tells us that the lines differ, and we can quickly scan the bytes that make up the line to see which differ.
When comparing very long strings, we can stop after we've seen a few differences. Here, we'll just look for two:
# have (hex) have want (hex) want
# 416c6c20435220616e64 All CR and = 416c6c20435220616e64 All CR and
# 206e6f204c46206d616b no LF mak = 206e6f204c46206d616b no LF mak
# 6573204d616320612064 es Mac a d = 6573204d616320612064 es Mac a d
# 756c6c20626f792e0d41 ull boy..A = 756c6c20626f792e0d41 ull boy..A
# 6c6c20435220616e6420 ll CR and = 6c6c20435220616e6420 ll CR and
# 6e6f204c46206d616b65 no LF make = 6e6f204c46206d616b65 no LF make
# 73204d61632061206475 s Mac a du = 73204d61632061206475 s Mac a du
# 6c6c20626f792e0d416c ll boy..Al ! 6c6c20626f792e0a416c ll boy..Al
# 6c20435220616e64206e l CR and n = 6c20435220616e64206e l CR and n
# 6f204c46206d616b6573 o LF makes = 6f204c46206d616b6573 o LF makes
# 204d616320612064756c Mac a dul = 204d616320612064756c Mac a dul
# 6c20626f792e0d416c6c l boy..All ! 6c20626f792e0a416c6c l boy..All
# 20435220616e64206e6f CR and no = 20435220616e64206e6f CR and no
This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.
Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.
is_binary($have, $want, $comment, \%arg);
This test behaves like Test::More's is test, but if the given data are not string equal, the diagnostics emits four columns, describing the strings in parallel, showing a simplified ASCII representation and a hexadecimal dump.
If $want is an arrayref, it's treated as a sequence of strings giving hex values for expected bytes. For example, this is a passing test:
[ qw(4d75 6d62 6c65 6672 6f74 7a0a) ],
Notice that each string in the sequence is broken into two-character pieces. This makes this interface accept the kind of dumps produced by xxd or Test::BinaryData itself.
Between the got and expected data for each line, a "=" or "!" indicates whether the chunks are identical or different.
The $comment and %arg arguments are optional. Valid arguments are:
columns - the number of screen columns available
if the COLUMNS environment variable is an positive integer, then
COLUMNS - is used; otherwise, the default is 79
max_diffs - if given, this is the maximum number of differing lines that will
be compared; if output would have been given beyond this line,
it will be replaced with an elipsis ("...")
This library is for comparing binary data. That is, byte strings. Often, in Perl 5, it is not clear whether a scalar contains a byte string or a character strings. You should use this library for comparing byte strings only. If either the "have" or "want" values contain wide characters -- that is, characters that won't fit in one byte -- then the test will fail.
optional position markers
have (hex) have want (hex) want
00 46726f6d206d6169 From mai = 46726f6d206d6169 From mai
08 3130353239406c6f 10529@lo = 3130353239406c6f 10529@lo
16 63616c686f737420 calhost = 63616c686f737420 calhost
24 5765642044656320 Wed Dec = 5765642044656320 Wed Dec
32 31382031323a3037 18 12:07 = 31382031323a3037 18 12:07
40 3a35352032303032 :55 2002 = 3a35352032303032 :55 2002
48 0a52656365697665 .Receive ! 0d0a526563656976 ..Receiv
investigate probably bugs with wide chars, multibyte strings
I wrote this primarily for detecting CRLF problems, but it's also very useful for dealing with encoded strings.
Ricardo Signes <firstname.lastname@example.org>
Ricardo SIGNES <email@example.com>
Ricardo Signes <firstname.lastname@example.org>
This software is copyright (c) 2010 by Ricardo Signes.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Test::BinaryData, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.