NAME

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

DESCRIPTION

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

SYNOPSIS

    use Trace::Mask::Test qw/test_tracer/;

    test_tracer(
        name => 'my tracer',
        trace => \&trace,
        type  => 'return',
        convert => sub {
            my $stack = shift;
            ...
            return $stack;
        },
    );

EXPORTS

NA()

Placeholder value for use in test_tracer to represent fields the tracer does not provide.

($ok, $result, $expect) = test_tracer(trace => \&trace, convert => \&convert, name => "my test")

($ok, $result, $expect) = test_tracer(trace => \&trace, convert => \&convert, name => "my test", %tests)

This will verify that a tracer follows the specification. This will run every test in the test list below with both the specified tracer and the refewrence tracer, it will then compare the results.

In scalar context the sub returns a true or false indicating if the test passed or failed. In List context the sub will return the boolen $ok value, the arrayref produced from your stack, and the arrayref produced by the reference tracer. This behavior gives you the ability to debug the final structures, and manually compare them.

name => "..."

Specify a name for your test.

trace => \&trace

This should be your tracer, or a subroutine that calls it. This subroutine is called in scalar context. This can return the trace in any form you want so long as it is returned in a scalar.

convert => \&convert

This will be given the scalar your tracer returns as its only input argument. This sub should convert the trace to a standard form for comparison.

    convert => sub {
        my ($trace) = @_;
        ...
        return [
            [[$package1, NA(), $line1, $subname1, ...], \@args]
            [[$package2, $file2, $line2, $subname2, ...], \@args]
        ]
    },

The standard return is an arrayref with an arrayref for each stack frame. Each frame arrayref should itself contain 2 arrayrefs. The first arrayref should contain the fields caller() would return for that level. The second arrayref should contain arguments that the function was called with. You can use the ref returned from NA() in place of any value that cannot be obtained from your stack trace results. In addition it only checks values you have specified, if you only list the first 4 fields from caller then only the first 4 are checked.

type => 'return'

The trace function will return a trace in a scalar, use that as our trace.

type => 'exception'

The trace function will throw an exception, intercept it and use the exception as the trace.

type => 'warning'

The trace function will issue a warning, intecept it using a $SIG{__WARN__} override, then use the warning as our trace.

Note: If your tracer issues more than 1 warning and exception will be thrown.

Note: Since this uses a $SIG{__WARN__}, it cannot be used to check traces that require a custom $SIG{__WARN__} override. See the 'sigwarn' type below if you are testing a tool that rewrites warnings.

type => 'sigwarn'

The trace function will issue a warning, but a custom $SIG{__WARN__} needs to modify it before we see it. This will NOT override $SIG{__WARN__}, instead it will intercept all output to STDERR when it calls your tracer.

%tests

If you do not specify any tests then all will be run. If you only want to run a subset of tests then you can list them with a true value.

    test_tracer(
        name    => "foo",
        type    => 'return',
        trace   => \&trace,
        convert => sub { ... },

        test_stack_hide            => 1,
        test_stack_shift           => 1,
        test_stack_stop            => 1,
        test_stack_no_start        => 1,
        test_stack_alter           => 1,
        test_stack_shift_and_hide  => 1,
        test_stack_shift_short     => 1,
        test_stack_hide_short      => 1,
        test_stack_shift_and_alter => 1,
        test_stack_full_combo      => 1,
    );

OPTIONAL EXPORTS / TESTS

test_stack_hide(\&callback)

test_stack_shift(\&callback)

test_stack_stop(\&callback)

test_stack_no_start(\&callback)

test_stack_alter(\&callback)

test_stack_shift_and_hide(\&callback)

test_stack_shift_short(\&callback)

test_stack_hide_short(\&callback)

test_stack_shift_and_alter(\&callback)

test_stack_full_combo(\&callback)

SOURCE

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

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2015 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