1Trace::Mask::Test(3) User Contributed Perl Documentation Trace::Mask::Test(3)
2
6 Trace::Mask::Test - Tools for testing Trace::Mask compliance.
7
9 This package provides tools for testing tracers. This allows you to
10 check that a tracer complies with the specifications.
11
13 use Trace::Mask::Test qw/test_tracer/;
14 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
27 NA()
28 Placeholder value for use in test_tracer to represent fields the
29 tracer does not provide.
30 ($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 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 name => "..."
47 Specify a name for your test.
48 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 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 convert => sub {
61 my ($trace) = @_;
62 ...
63 return [
64 [[$package1, NA(), $line1, $subname1, ...], \@args]
65 [[$package2, $file2, $line2, $subname2, ...], \@args]
66 ]
67 },
68 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 type => 'return'
80 The trace function will return a trace in a scalar, use that as
81 our trace.
82 type => 'exception'
84 The trace function will throw an exception, intercept it and
85 use the exception as the trace.
86 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 Note: If your tracer issues more than 1 warning and exception
92 will be thrown.
93 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 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 %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 test_tracer(
111 name => "foo",
112 type => 'return',
113 trace => \&trace,
114 convert => sub { ... },
115 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 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
141 The source code repository for Trace-Mask can be found at
142 http://github.com/exodist/Trace-Mask.
143
145 Chad Granum <exodist@cpan.org>
146
148 Chad Granum <exodist@cpan.org>
149
151 Copyright 2015 Chad Granum <exodist7@gmail.com>.
152 This program is free software; you can redistribute it and/or modify it
154 under the same terms as Perl itself.
155 See http://www.perl.com/perl/misc/Artistic.html
157
159 Hey! The above document had some coding errors, which are explained
160 below:
161 Around line 118:
163 Unterminated C<...> sequence
164perl v5.38.0 2023-07-21 Trace::Mask::Test(3)