1Test::NiceDump(3)     User Contributed Perl Documentation    Test::NiceDump(3)
2
3
4

NAME

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

VERSION

10       version 1.0.1
11

SYNOPSIS

13           use Test::Deep;
14           use Test::NiceDump 'nice_explain';
15
16           cmp_deeply($got,$expected,'it works')
17               or nice_explain($got,$expected);
18

DESCRIPTION

20       This module uses "Data::Dump::Filtered" and a set of sensible filters
21       to dump test data in a more readable way.
22
23       For example, "DateTime" objects get printed in the full ISO 8601
24       format, and "DBIx::Class::Row" objects get printed as hashes of their
25       inflated columns.
26

FUNCTIONS

28   "nice_dump"
29           my $dumped_string = nice_dump $data;
30
31       Serialise $data in a nice, readable way.
32
33   "nice_explain"
34           nice_explain $data;
35           nice_explain $data, $comparator;
36
37       Calls ""nice_dump"" on $data and $comparator (if provided), and uses
38       "diag" to provide test failure feedback with the dumped strings.
39

HOW TO ADD FILTERS

41       If the built-in filtering of input data is not enough for you, you can
42       add extra filters. A filter is a coderef that takes a single argument
43       (the value to be dumped), and returns either:
44
45       nothing at all
46           to signal that it won't handle this particular value
47
48       any single value
49           which will be dumped instead
50
51       Let's say you have a class "My::Class", and you don't want its
52       instances to be dumped directly (maybe they contain cached data that's
53       not very useful to see). That class may have a "as_data_for_log" method
54       that returns only the important bits of data (as a hashref, probably),
55       so you want the return value of that method to be dumped instead. You
56       could say:
57
58           use Safe::Isa;
59
60           Test::NiceDump::add_filter(
61               my_filter => sub {
62                   $_[0]->$_isa('My::Class')
63                       ? $_[0]->as_data_for_log
64                       : ();
65               },
66           );
67
68       or, if you want to do the same for any object with that method:
69
70           use Safe::Isa;
71
72           Test::NiceDump::add_filter(
73               my_filter => sub { $_[0]->$_call_if_can('as_data_for_log') },
74           );
75
76   "add_filter"
77         Test::NiceDump::add_filter($name => $code);
78
79       Adds a new filter. Adding a filter with an existing name overrides it.
80
81       Filters are invoked in "cmp" order of name. The names of all built-in
82       filters match "/^Test::NiceDump::/".
83
84       Try to be specific with your checks, to avoid surprises due to the
85       interaction of different filters.
86
87       Your filter must return nothing at all if it didn't handle the value.
88       Failure to do so will probably lead to infinite recursion.
89
90   "remove_filter"
91         Test::NiceDump::remove_filter($name);
92
93       Removes the filter with the given name. Nothing happens if such a
94       filter does not exist.
95

AUTHOR

97       Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>
98
100       This software is copyright (c) 2019 by BroadBean UK, a CareerBuilder
101       Company.
102
103       This is free software; you can redistribute it and/or modify it under
104       the same terms as the Perl 5 programming language system itself.
105
106
107
108perl v5.36.0                      2023-01-20                 Test::NiceDump(3)
Impressum