| 1 |
NAME |
| 2 |
"Test::HexString" - test binary strings with hex dump diagnostics |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Test::More tests => 1; |
| 6 |
use Test::HexString; |
| 7 |
|
| 8 |
my $data = generate_some_output; |
| 9 |
|
| 10 |
is_hexstr( $data, "\x01\x02\x03\x04", 'Generated output' ); |
| 11 |
|
| 12 |
DESCRIPTION |
| 13 |
This testing module provides a single function, "is_hexstr()", which |
| 14 |
asserts that the given string matches what was expected. When the |
| 15 |
strings match (i.e. compare equal using the "eq" operator), the |
| 16 |
behaviour is identical to the usual "is()" function provided by |
| 17 |
"Test::More". |
| 18 |
|
| 19 |
When the strings are different, a hex dump is produced as diagnostic, |
| 20 |
rather than the string values being printed raw. This may be beneficial |
| 21 |
if the string contains largely binary data, such as may be produced by |
| 22 |
binary file or network protocol modules. |
| 23 |
|
| 24 |
To print the hex dump when it fails, each string is broken into 16 byte |
| 25 |
chunks. The first pair of chunks that fail to match are then printed, in |
| 26 |
both hexadecimal and character form, in a message in the following |
| 27 |
format: |
| 28 |
|
| 29 |
# Failed test at -e line 1. |
| 30 |
# at bytes 0-0xf (0-15) |
| 31 |
# got: | 61 20 6c 6f 6e 67 20 73 74 72 69 6e 67 20 68 65 |a long string he| |
| 32 |
# exp: | 61 20 6c 6f 6e 67 20 53 74 72 69 6e 67 20 68 65 |a long String he| |
| 33 |
# Looks like you failed 1 test of 1. |
| 34 |
|
| 35 |
Only bytes in the range "0x20-0x7e" are printed as literal characters. |
| 36 |
Any other byte is rendered as ".": |
| 37 |
|
| 38 |
# Failed test at -e line 1. |
| 39 |
# at bytes 0-0xf (0-15) |
| 40 |
# got: | 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |................| |
| 41 |
# exp: | 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 |................| |
| 42 |
# Looks like you failed 1 test of 1. |
| 43 |
|
| 44 |
Only the first differing line is printed; because otherwise it may |
| 45 |
result in a long output because of misaligned bytes. |
| 46 |
|
| 47 |
If STDOUT is a terminal, then different bytes are printed in bold for |
| 48 |
visibility. |
| 49 |
|
| 50 |
FUNCTIONS |
| 51 |
is_hexstr( $got, $expect, $name ) |
| 52 |
Test that the string $got is what was expected by $expect. If the |
| 53 |
strings are not equal, a hex dump is printed showing the region where |
| 54 |
they first start to differ. |
| 55 |
|
| 56 |
AUTHOR |
| 57 |
Paul Evans <[email protected]> |
| 58 |
|