---
name: "Test::NiceDump"
section: "3pm"
platform: "linux"
package: "libtest-nicedump-perl"
version: "1.0.1-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::NiceDump"
---

# Test::NiceDump(3pm)

let's have a nice and human readable dump of our objects!

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