1Test::Trap::Builder(3)User Contributed Perl DocumentationTest::Trap::Builder(3)
2
6 Test::Trap::Builder - Backend for building test traps
7
9 Version 0.3.5
10
12 package My::Test::Trap;
13 use Test::Trap::Builder;
15 my $B = Test::Trap::Builder->new;
16 $B->layer( $layer_name => \&layer_implementation );
18 $B->accessor( simple => [ $layer_name ] );
19 $B->multi_layer( $multi_name => @names );
21 $B->test( $test_name => 'trap, predicate, name', \&test_function );
23
25 Test::Trap neither traps nor tests everything you may want to trap or
26 test. So, Test::Trap::Builder provides methods to write your own trap
27 layers, accessors, and test callbacks -- preferably for use with your
28 own modules (trappers).
29 Note that layers are methods with mangled names (names are prefixed
31 with "layer:"), and so inherited like any other method, while accessors
32 are ordinary methods. Meanwhile, test callbacks are not referenced in
33 the symbol table by themselves, but only in combinations with
34 accessors, all methods of the form ACCESSOR_TEST.
35
37 Trappers should not inherit from Test::Trap::Builder, but may import a
38 few convenience methods for use in building the trap. Do not use them
39 as methods of Test::Trap::Builder -- they are intended to be methods of
40 trap objects. (If you inherit from another trapper, you need not, and
41 probably should not, import these yourself -- you should inherit these
42 methods like any other.)
43 Trappers may import any number of these methods, or all of them by way
45 of the ":methods" tag.
46 Layers should be implemented as methods, and while they need not call
48 any of these convenience methods in turn, that likely makes for more
49 readable code than any alternative. Likewise, test callbacks may use
50 convenience methods for more readable code.
51 Of course, certain convenience methods may also be useful in more
53 generic methods messing with trap or builder objects.
54 Prop [PACKAGE]
56 A method returning a reference to a hash, holding the PACKAGE's (by
57 default the caller's) tag-on properties for the (current) trap object.
58 Currently, Test::Trap::Builder defines the following properties:
59 layers
61 While the trap is springing, the queue of layers remaining.
62 Usually set by the "trap" method and consumed by the "Next" method.
63 teardown
65 While the trap is springing, the queue of teardown actions
66 remaining. Usually accumulated through the "Teardown" method and
67 invoked by the "trap" method.
68 code
70 The user code trapped. Usually set by the "trap" method and
71 invoked by the "Run" method.
72 exception
74 An internal exception. Usually set through the "Exception" method
75 and examined by the "trap" method.
76 on_test_failure
78 A callback invoked by the "TestFailure" method. Layers in
79 particular may want to set this.
80 test_accessor
82 The name and (optionally) the index of the accessor, the contents
83 of which we're currently testing. Best accessed through the
84 "TestAccessor" method, and usually set by the "test" and "accessor"
85 methods, but if you are writing your own tests or accessors
86 directly, you just might need to set it. Perhaps.
87 Be nice: Treat another module's tag-on properties as you would treat
89 another module's global variables. Don't use them except as
90 documented.
91 Example:
93 # in a layer, setting the callback for TestFailure:
95 $self->Prop('Test::Trap::Builder')->{on_test_failure} = \&mydiag;
96 DESTROY
98 This cleans up the tag-on properties when the trap object is destroyed.
99 Don't try to make a trapper that doesn't call this; it will get
100 confused.
101 If your trapper needs its own "DESTROY", make sure it calls this one as
103 well:
104 sub DESTROY {
106 my $self = shift;
107 # do your thing
108 $self->Test::Trap::Builder::DESTROY;
109 # and more things
110 }
111 Run
113 A terminating layer should call this method to run the user code.
114 Should only be called in a dynamic context in which layers are being
115 applied.
116 Next
118 Every non-terminating layer should call this method (or an equivalent)
119 to progress to the next layer. Should only be called in a dynamic
120 context in which layers are being applied. Note that this method need
121 not return, so any tear-down actions should probably be registered with
122 the Teardown method (see below).
123 Teardown SUBS
125 If your layer wants to clean up its setup, it may use this method to
126 register any number of tear-down actions, to be performed (in reverse
127 registration order) once the user code has been executed. Should only
128 be called in a dynamic context in which layers are being applied.
129 TestAccessor
131 Returns a string of the form "NAME(INDEX)", where NAME and INDEX are
132 the name of the accessor and the index (if any) being tested. Should
133 only be called in the dynamic context of test callbacks.
134 This is intended for diagnostics:
136 diag( sprintf 'Expected %s in %s; got %s',
138 $expected, $self->TestAccessor, dump($got),
139 );
140 TestFailure
142 Runs the "on_test_failure" tag-on property (if any) on the trap object.
143 If you are writing unregistered tests, you might want to include (some
144 variation of) this call:
145 $ok or $self->TestFailure;
147 Exception STRINGS
149 Layer implementations may run into exceptional situations, in which
150 they want the entire trap to fail. Unfortunately, another layer may be
151 trapping ordinary exceptions, so you need some kind of magic in order
152 to throw an untrappable exception. This is one convenient way.
153 Should only be called in a dynamic context in which layers are being
155 applied.
156 Note: The Exception method won't work if called from outside of the
158 regular control flow, like inside a DESTROY method or signal handler.
159 If anything like this happens, CORE::exit will be called with an exit
160 code of 8.
161 Note: Direct calls to the Exception method within closures may cause
163 circular references and so leakage. To avoid this, fetch an
164 "ExceptionFunction" and call it from the closure instead.
165 ExceptionFunction
167 This method returns a function that may be called with the same effect
168 as calling the "Exception" method, allowing closures to throw
169 exceptions without causing circular references by closing over the trap
170 object itself.
171 To illustrate:
173 # this will create a circular reference chain:
175 # trap object has property collection has teardown closure has trap object
176 $self->Teardown($_) for sub {
177 do_stuff() or $self->Exception("Stuff didn't work.");
178 };
179 # this will break the circular reference chain:
181 # teardown closure no longer has trap object
182 $Exception = $self->ExceptionFunction;
183 $self->Teardown($_) for sub {
184 do_things() or $Exception->("Things didn't work.");
185 };
186
188 new
189 Returns a singleton object. Don't expect this module to work with a
190 different instance object of this class.
191 trap TRAPPER, GLOBREF, LAYERARRAYREF, CODE
193 Implements a trap for the TRAPPER module, applying the layers of
194 LAYERARRAYREF, trapping various outcomes of the user CODE, and storing
195 the trap object into the scalar slot of GLOBREF.
196 In most cases, the trapper should conveniently export a function
198 calling this method.
199 layer NAME, CODE
201 Registers a layer by NAME to the calling trapper. When the layer is
202 applied, the CODE will be invoked on the trap object being built, with
203 no arguments, and should call either the Next() or Run() method or
204 equivalent.
205 output_layer NAME, GLOBREF
207 Registers (by NAME and to the calling trapper) a layer for trapping
208 output on the file handle of the GLOBREF, using NAME also as the
209 attribute name.
210 capture_strategy NAME, [CODE]
212 When called with two arguments, registers (by NAME and globally) a
213 strategy for output trap layers. When called with a single argument,
214 looks up and returns the strategy registered by NAME (or undef).
215 When a layer using this strategy is applied, the CODE will be called on
217 the trap object, with the layer name and the output handle's fileno and
218 globref as arguments.
219 output_layer_backend SPEC
221 Back-compat alias of the above.
222 first_capture_strategy SPEC
224 Where SPEC is empty, just returns.
225 Where SPEC is a string of comma-or-semicolon separated names, runs
227 through the names, returning the first strategy it finds. Dies if no
228 strategy is found by any of these names.
229 first_output_layer_backend SPEC
231 Back-compat alias of the above.
232 multi_layer NAME, LAYERS
234 Registers (by NAME) a layer that just pushes a number of other LAYERS
235 on the stack of layers. If any of the LAYERS is neither an anonymous
236 method nor the name of a layer registered to the caller or a trapper it
237 inherits from, an exception is raised.
238 layer_implementation TRAPPER, LAYERS
240 Returns the subroutines that implement the requested LAYERS. If any of
241 the LAYERS is neither an anonymous method nor the name of a layer
242 registered to or inherited by the TRAPPER, an exception is raised.
243 accessor NAMED_ARGS
245 Generates and registers any number of accessors according to the
246 NAMED_ARGS, and also generates the proper test methods for these
247 accessors (see below).
248 The following named arguments are recognized:
250 is_leaveby
252 If true, the tests methods will generate better diagnostics if the
253 trap was not left as specified. Also, a special did_ACCESSOR test
254 method will be generated (unless already present), simply passing
255 as long as the trap was left as specified.
256 is_array
258 If true, the simple accessor(s) will be smart about context and
259 arguments, returning an arrayref on no argument (in any context),
260 an array slice in list context (on any number of arguments), and
261 the element indexed by the first argument otherwise.
262 simple
264 Should be a reference to an array of accessor names. For each
265 name, an accessor (assuming hash based trap object with accessor
266 names as keys), will be generated and registered.
267 flexible
269 Should be a reference to a hash. For each pair, a name and an
270 implementation, an accessor is generated and registered.
271 test NAME, ARGSPEC, CODE
273 Registers a test callback by NAME and to the calling trapper.
274 Trappers inherit test callbacks like methods (though they are not
276 implemented as such; don't expect to find them in the symbol table).
277 Test methods of the form ACCESSOR_TEST will be made available (directly
279 or by inheritance) to every trapper that registers or inherits both the
280 accessor named ACCESSOR and the test named TEST.
281 (In more detail, the method will be generated in every trapper that
283 either (1) registers both the test and the accessor, or (2) registers
284 either and inherits the other.)
285 When the test method is called, any implicit leaveby condition will be
287 tested first, and if it passes (or there were none), the CODE is called
288 with arguments according to the words found in the ARGSPEC string:
289 trap
291 The trap object.
292 entirety
294 The ACCESSOR's return value when called without arguments.
295 element
297 The ACCESSOR's return value when called with index, if applicable
298 (i.e. for array accessors). Index is not applicable to scalar
299 accessors, so such are still called without index.
300 The index, when applicable, will be taken from the test method's
302 arguments.
303 predicate
305 What the ACCESSOR's return value should be tested against (taken
306 from the test method's arguments). (There may be any fixed number
307 of predicates.)
308 name
310 The test name (taken from the test method's arguments).
311
313 A complete example, implementing a timeout layer (depending on
314 Time::HiRes::ualarm being present), a simpletee layer (printing the
315 trapped stdout/stderr to the original file handles after the trap has
316 sprung), and a cmp_ok test method template:
317 package My::Test::Trap;
319 use base 'Test::Trap'; # for example
320 use Test::Trap::Builder;
321 my $B = Test::Trap::Builder->new;
323 # example (layer:timeout):
325 use Time::HiRes qw/ualarm/;
326 $B->layer( timeout => $_ ) for sub {
327 my $self = shift;
328 eval {
329 local $SIG{ALRM} = sub {
330 $self->{timeout} = 1; # simple truth
331 $SIG{ALRM} = sub {die};
332 die;
333 };
334 ualarm 1000, 1; # one second max, then die repeatedly!
335 $self->Next;
336 };
337 alarm 0;
338 if ($self->{timeout}) {
339 $self->{leaveby} = 'timeout';
340 delete $self->{$_} for qw/ die exit return /;
341 }
342 };
343 $B->accessor( is_leaveby => 1,
344 simple => ['timeout'],
345 );
346 # example (layer:simpletee):
348 $B->layer( simpletee => $_ ) for sub {
349 my $self = shift;
350 for (qw/ stdout stderr /) {
351 exists $self->{$_} or $self->Exception("Too late to tee $_");
352 }
353 $self->Teardown($_) for sub {
354 print STDOUT $self->{stdout} if exists $self->{stdout};
355 print STDERR $self->{stderr} if exists $self->{stderr};
356 };
357 $self->Next;
358 };
359 # no accessor for this layer
360 $B->multi_layer( flow => qw/ raw die exit timeout / );
362 $B->multi_layer( default => qw/ flow stdout stderr warn simpletee / );
363 $B->test_method( cmp_ok => 1, 2, \&Test::More::cmp_ok );
365
367 The interface of this module is likely to remain somewhat in flux for a
368 while yet.
369 The different strategies for output trap layers have their own caveats;
371 see Test::Trap::Builder::Tempfile, Test::Trap::Builder::PerlIO,
372 Test::Trap::Builder::SystemSafe.
373 Multiple inheritance is not (yet?) fully supported. If one parent has
375 registered a test callback "X" and another has registered an accessor
376 "Y", the test method "Y_X" will not be generated.
377 Threads? No idea. It might even work correctly.
379
381 Please report any bugs or feature requests directly to the author.
382
384 Eirik Berg Hanssen, "<ebhanssen@cpan.org>"
385
387 Copyright 2006-2014 Eirik Berg Hanssen, All Rights Reserved.
388 This program is free software; you can redistribute it and/or modify it
390 under the same terms as Perl itself.
391perl v5.36.0 2022-08-01 Test::Trap::Builder(3)