Test::NiceDump(3pm)

💖 Test::NiceDump — bestie edition 💖

okay so. you know how test failures dump your objects and it's giving "wall of cursed memory addresses"? yeah. this is the Test::NiceDump page from the Perl 5 manual (section 3pm, the module pages 💅) and it's here to save your whole entire life.

---

✨ NAME ✨

Test::NiceDump — let's have a nice and human readable dump of our objects! 🎀

like. literally that. the vibes are immaculate and the dumps are readable. no cap.

---

🌸 VERSION 🌸

version 1.0.1 ⭐

---

🦋 SYNOPSIS 🦋

use Test::Deep;
use Test::NiceDump 'nice_explain';

cmp_deeply($got,$expected,'it works')
    or nice_explain($got,$expected);

see how it's cmp_deeply(...) or nice_explain(...)? that's the whole move. when the test goes 💀, the explain kicks in and tells you what actually happened, in a way your eyeballs can process. iconic behavior tbh.

---

💜 DESCRIPTION 💜

This module uses Data::Dump::Filtered and a set of sensible filters to dump test data in a more readable way. 🌈

For example, DateTime objects get printed in the full ISO 8601 format, and DBIx::Class::Row objects get printed as hashes of their inflated columns.

like bestie, instead of "bless( { ... 47 nested refs ... }, 'DateTime' )" you get an actual date. groundbreaking. life-changing. obsessed. 😭💖

---

🔥 FUNCTIONS 🔥

nice_dump 💅

my $dumped_string = nice_dump $data;

Serialise $data in a nice, readable way. ✨ that's it, that's the function. it hands you back a string that doesn't make you want to close the laptop.

nice_explain 🫶

nice_explain $data;
nice_explain $data, $comparator;

Calls nice_dump on $data and $comparator (if provided), and uses diag to provide test failure feedback with the dumped strings. 📣

so if you don't pass a $comparator, it just dumps $data. pass one and it dumps both so you can see the two things side by side like 👀 "oh that's the difference".

---

🧚 HOW TO ADD FILTERS 🧚

If the built-in filtering of input data is not enough for you, you can add extra filters. A filter is a coderef that takes a single argument (the value to be dumped), and returns either:

• nothing at all — to signal that it won't handle this particular value 🙅
• any single value — which will be dumped instead 💫

Let's say you have a class My::Class, and you don't want its instances to be dumped directly (maybe they contain cached data that's not very useful to see). That class may have a as_data_for_log method that returns only the important bits of data (as a hashref, probably), so you want the return value of that method to be dumped instead. You could say:

use Safe::Isa;

Test::NiceDump::add_filter(
    my_filter => sub {
        $_[0]->$_isa('My::Class')
            ? $_[0]->as_data_for_log
            : ();
    },
);

or, if you want to do the same for any object with that method:

use Safe::Isa;

Test::NiceDump::add_filter(
    my_filter => sub { $_[0]->$_call_if_can('as_data_for_log') },
);

see that : () in the first one? that's the "nothing at all, not my problem" return. crucial. don't skip it. 🚨

add_filter 👑

Test::NiceDump::add_filter($name => $code);

Adds a new filter. Adding a filter with an existing name overrides it. 😈 (yes, it just takes over. no warning. the old one is gone.)

Filters are invoked in cmp order of name. The names of all built-in filters match /^Test::NiceDump::/.

Try to be specific with your checks, to avoid surprises due to the interaction of different filters.

⚠️ Your filter must return nothing at all if it didn't handle the value. Failure to do so will probably lead to infinite recursion. bestie that is NOT the vibe. that's the "laptop fan sounds like a jet engine" pipeline. 💀

remove_filter 🍓

Test::NiceDump::remove_filter($name);

Removes the filter with the given name. Nothing happens if such a filter does not exist. 🍃 super chill, no drama, no error, no nothing.

---

💌 AUTHOR 💌

Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2019 by BroadBean UK, a CareerBuilder Company.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay that's the whole page, you're caught up, you ate that 🫶 this was Test::NiceDump, version 1.0.1 in the perl v5.36.0 docs, dated 2022-10-14 — go forth and never read a raw object dump again ✨💖🎀