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

NAME

6       Trace::Mask::Test - Tools for testing Trace::Mask compliance.
7

DESCRIPTION

9       This package provides tools for testing tracers. This allows you to
10       check that a tracer complies with the specifications.
11

SYNOPSIS

13           use Trace::Mask::Test qw/test_tracer/;
14
15           test_tracer(
16               name => 'my tracer',
17               trace => \&trace,
18               type  => 'return',
19               convert => sub {
20                   my $stack = shift;
21                   ...
22                   return $stack;
23               },
24           );
25

EXPORTS

27       NA()
28           Placeholder value for use in test_tracer to represent fields the
29           tracer does not provide.
30
31       ($ok, $result, $expect) = test_tracer(trace => \&trace, convert =>
32       \&convert, name => "my test")
33       ($ok, $result, $expect) = test_tracer(trace => \&trace, convert =>
34       \&convert, name => "my test", %tests)
35           This will verify that a tracer follows the specification. This will
36           run every test in the test list below with both the specified
37           tracer and the refewrence tracer, it will then compare the results.
38
39           In scalar context the sub returns a true or false indicating if the
40           test passed or failed. In List context the sub will return the
41           boolen $ok value, the arrayref produced from your stack, and the
42           arrayref produced by the reference tracer. This behavior gives you
43           the ability to debug the final structures, and manually compare
44           them.
45
46           name => "..."
47               Specify a name for your test.
48
49           trace => \&trace
50               This should be your tracer, or a subroutine that calls it. This
51               subroutine is called in scalar context. This can return the
52               trace in any form you want so long as it is returned in a
53               scalar.
54
55           convert => \&convert
56               This will be given the scalar your tracer returns as its only
57               input argument.  This sub should convert the trace to a
58               standard form for comparison.
59
60                   convert => sub {
61                       my ($trace) = @_;
62                       ...
63                       return [
64                           [[$package1, NA(), $line1, $subname1, ...], \@args]
65                           [[$package2, $file2, $line2, $subname2, ...], \@args]
66                       ]
67                   },
68
69               The standard return is an arrayref with an arrayref for each
70               stack frame. Each frame arrayref should itself contain 2
71               arrayrefs. The first arrayref should contain the fields
72               caller() would return for that level. The second arrayref
73               should contain arguments that the function was called with. You
74               can use the ref returned from NA() in place of any value that
75               cannot be obtained from your stack trace results. In addition
76               it only checks values you have specified, if you only list the
77               first 4 fields from caller then only the first 4 are checked.
78
79           type => 'return'
80               The trace function will return a trace in a scalar, use that as
81               our trace.
82
83           type => 'exception'
84               The trace function will throw an exception, intercept it and
85               use the exception as the trace.
86
87           type => 'warning'
88               The trace function will issue a warning, intecept it using a
89               $SIG{__WARN__} override, then use the warning as our trace.
90
91               Note: If your tracer issues more than 1 warning and exception
92               will be thrown.
93
94               Note: Since this uses a $SIG{__WARN__}, it cannot be used to
95               check traces that require a custom "$SIG{__WARN__} override.
96               See the 'sigwarn' type below if you are testing a tool that
97               rewrites warnings."
98
99           type => 'sigwarn'
100               The trace function will issue a warning, but a custom
101               $SIG{__WARN__} needs to modify it before we see it. This will
102               NOT override $SIG{__WARN__}, instead it will intercept all
103               output to STDERR when it calls your tracer.
104
105           %tests
106               If you do not specify any tests then all will be run. If you
107               only want to run a subset of tests then you can list them with
108               a true value.
109
110                   test_tracer(
111                       name    => "foo",
112                       type    => 'return',
113                       trace   => \&trace,
114                       convert => sub { ... },
115
116                       test_stack_hide            => 1,
117                       test_stack_shift           => 1,
118                       test_stack_stop            => 1,
119                       test_stack_no_start        => 1,
120                       test_stack_alter           => 1,
121                       test_stack_shift_and_hide  => 1,
122                       test_stack_shift_short     => 1,
123                       test_stack_hide_short      => 1,
124                       test_stack_shift_and_alter => 1,
125                       test_stack_full_combo      => 1,
126                   );
127
128   OPTIONAL EXPORTS / TESTS
129       test_stack_hide(\&callback)
130       test_stack_shift(\&callback)
131       test_stack_stop(\&callback)
132       test_stack_no_start(\&callback)
133       test_stack_alter(\&callback)
134       test_stack_shift_and_hide(\&callback)
135       test_stack_shift_short(\&callback)
136       test_stack_hide_short(\&callback)
137       test_stack_shift_and_alter(\&callback)
138       test_stack_full_combo(\&callback)
139

SOURCE

141       The source code repository for Trace-Mask can be found at
142       http://github.com/exodist/Trace-Mask.
143

MAINTAINERS

145       Chad Granum <exodist@cpan.org>
146

AUTHORS

148       Chad Granum <exodist@cpan.org>
149
151       Copyright 2015 Chad Granum <exodist7@gmail.com>.
152
153       This program is free software; you can redistribute it and/or modify it
154       under the same terms as Perl itself.
155
156       See http://www.perl.com/perl/misc/Artistic.html
157

POD ERRORS

159       Hey! The above document had some coding errors, which are explained
160       below:
161
162       Around line 118:
163           Unterminated C<...> sequence
164
165
166
167perl v5.36.0                      2023-01-20              Trace::Mask::Test(3)
Impressum