NAME

Test::Builder::Trace - Module to represent a stack trace from a test event.

DESCRIPTION

When a test fails it will report the filename and line where the failure occured. In order to do this it needs to look at the stack and figure out where your tests stop, and the tools you are using begin. This object helps you find the desired caller frame.

CLASS METHODS

$trace = $class->new

Create a new object tracing from itself to the deepest stack frame.

my $trace = Test::Builder::Trace->new();

$class->nest(sub { ... })

Used as a tracing barrier. Events produced in the coderef will trace to that coderef and no deeper.

$class->anoint($TARGET_PACKAGE)

$class->anoint($TARGET_PACKAGE, $ANOINTED_BY_PACKAGE)

Used to anoint a package as a testing package.

UTILITY METHODS

$frame = $trace->report

Get the Test::Builder::Trace::Frame object that should be used when reporting errors. The 'report' is determined by examining the stack, $Test::Builder::Level, and provider/anointed metadata.

$package = $trace->todo_package

Get the name of the package from which the $TODO variable should be checked.

$trace = $trace->parent

A trace stops when it encounters a call to Test::Builder::Trace::nest which acts as a tracing barrier. When such a barrier is encountered the tracing continues, but stores the frames in a new Test::Builder::Trace object that is set as the parent. You can use this to examine the stack beyond the main trace.

STACKS

All stacks are arrayrefs containing Test::Builder::Trace::Frame objects.

$arrayref = $trace->stack

This stack contains all frames that are relevant to finding the report. Many frames are kept out of this list. This will usually be the most helpful stack to examine.

$arrayref = $trace->full

Absolutely every frame is kept in this stack. Examine this if you want to see EVERYTHING.

$arrayref = $trace->anointed

This stack contains all the frames that come from an anointed package.

$arrayref = $trace->level

This stack contains all the frames that match the $Test::Builder::Level variable.

$arrayref = $trace->tools

This stack contains all the frames that are calls to provider tools.

$arrayref = $trace->transitions

This stack contains all the frames that act as transitions between external code and Test::Builder related code.

$arrayref - $trace->todo

This stack contains all the frames that seem to have a $TODO variable available to them. See Test::Builder::Trace::Frame for caveats.

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2014 by Chad Granum <exodist7@gmail.com>

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html