Trace::Mask::Test(3)

📦
version 0.000008 · 2 versions
, in fedora 43

💖 Trace::Mask::Test(3) 💖

okay bestie, welcome to Trace::Mask::Test — it's a Perl module, it lives in the User Contributed Perl Documentation section of your friendly neighborhood man pages, and it is literally here to help you test tracers. no cap.

✨ NAME ✨

Trace::Mask::Test — tools for testing Trace::Mask compliance. it's giving "quality control but make it cute." 🎀

🌸 DESCRIPTION 🌸

so this package hands you the tools to test your tracers. that's it, that's the vibe. you use it to check that a tracer actually complies with the specifications. compliance check era. 💅

🦋 SYNOPSIS 🦋

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

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

look at that. gorgeous. no notes. ⭐

👑 EXPORTS 👑

  • NA() — placeholder value for use in test_tracer to represent fields the tracer does not provide. it's the "idk, fill it in later" of the tracer world. 🙈
  • ($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. it runs every test in the test list below with both the specified tracer and the refewrence tracer, and then it compares the results. yes, "refewrence" — that's the original spelling, we do not edit the queen. 👑

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. debugging rights, unlocked. 🔥

  • name => "..." — specify a name for your test. give it a little identity. main character energy. 💖
  • trace => \&trace — this should be your tracer, or a subroutine that calls it. this subroutine is called in scalar context. it can return the trace in any form you want so long as it is returned in a scalar. one scalar, any shape, we're flexible.
  • 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. only the checked parts get checked, periodt. ✨

  • 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. sneaky but respectful. 🧚
  • %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,
);

pick your fighters, bestie 💅

🎀 OPTIONAL EXPORTS / TESTS 🎀

here's the whole roster, all taking a \&callback:

  • 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)

the whole squad, together, slaying. 🔥

🌈 SOURCE 🌈

the source code repository for Trace-Mask can be found at http://github.com/exodist/Trace-Mask. go peek, it's iconic. 👑

💜 MAINTAINERS 💜

  • Chad Granum <exodist@cpan.org>

⭐ AUTHORS ⭐

  • Chad Granum <exodist@cpan.org>

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 🫶

💀 POD ERRORS 💀

hey! the above document had some coding errors, which are explained below:

Around line 118:

    Unterminated C<...> sequence

not me calling out the original's typos 💀 but fr fr, we keep the receipts. the doc said it, so we say it.

and that's the whole page, bestie!! 🌸 this little gem comes to you from perl v5.42.0, dated 2025-07-25, and it's Trace::Mask::Test(3) forever and always. go forth and test your tracers, you absolute legend. mwah. 💖🎀🦋✨

📦 where this page comes from