NAME

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

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);

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.

FUNCTIONS

   "nice_dump"
           my $dumped_string = nice_dump $data;

       Serialise $data in a nice, readable way.

   "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.

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') },
           );

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

       Adds a new filter. Adding a filter with an existing name overrides it.

       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.

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

       Removes the filter with the given name. Nothing happens if such a filter does not exist.

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.