Test::HexString(3pm)

💖 Test::HexString 💖

okay bestie, so this is Test::HexString — a lil Perl module from the User Contributed Perl Documentation crew 🫶 and its whole vibe is test binary strings with hex dump diagnostics. yes, hex dumps. we're being ✨responsible✨ about binary data today.

---

🌸 NAME 🌸

Test::HexString — test binary strings with hex dump diagnostics 💅

---

✨ SYNOPSIS ✨

like, here's the whole thing, it's so simple it's giving main character energy:

use Test::More tests => 1;
use Test::HexString;

my $data = generate_some_output;

is_hexstr( $data, "\x01\x02\x03\x04", 'Generated output' );

---

🦋 DESCRIPTION 🦋

This testing module provides a single function, is_hexstr(), which asserts that the given string matches what was expected. When the strings match — i.e. they compare equal using the eq operator — the behaviour is identical to the usual is() function provided by Test::More. no drama, no notes, same energy 💖

When the strings are different, though? That's when the glow-up happens: a hex dump</> is produced as the diagnostic, instead of just printing the string values raw. This may be beneficial if the string contains largely binary data, such as may be produced by binary file or network protocol modules. because ngl, staring at raw binary in your test output is not the moment 😭

To print the hex dump when it fails, each string is broken into 16 byte chunks. The first pair of chunks that fail to match are then printed, in both hexadecimal and character form, in a message in the following format:

#   Failed test at -e line 1.
#   at bytes 0-0xf (0-15)
#   got: | 61 20 6c 6f 6e 67 20 73 74 72 69 6e 67 20 68 65 |a long string he|
#   exp: | 61 20 6c 6f 6e 67 20 53 74 72 69 6e 67 20 68 65 |a long String he|
# Looks like you failed 1 test of 1.

Only bytes in the range 0x20-0x7e are printed as literal characters. Any other byte is rendered as .:

#   Failed test at -e line 1.
#   at bytes 0-0xf (0-15)
#   got: | 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |................|
#   exp: | 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 |................|
# Looks like you failed 1 test of 1.

Only the first differing line is printed — because otherwise it may result in a long output because of misaligned bytes. she's keeping it cute and concise, periodt 💅

And if STDOUT is a terminal, then different bytes are printed in bold for visibility. obsessed with that actually ✨

---

🎀 FUNCTIONS 🎀

is_hexstr( $got, $expect, $name )

Test that the string $got is what was expected by $expect. If the strings are not equal, a hex dump is printed showing the region where they first start to differ. it's giving "I got you, bestie, here's exactly where it went wrong" 🫶

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> 🌈

---

and that's the whole page, babe — no cap, every flag and fact is still in there 💖

this manual page came from perl v5.36.0, dated 2022-11-20, and it lives in the Test::HexString(3pm) section of the User Contributed Perl Documentation 🎀✨ bye bestie, go write some tests 💅