LEVEL section in Test2::Manual::Tooling::TestBuilder has multiple issues

[wchristian]

In writing tests, not just test tools, it is very common to do something like this:

sub is_file ($struct) {
    local $Test::Builder::Level = $Test::Builder::Level + 1;
    my $file = ".../meep.json";
    is_deeply decode_json( +io($file)->slurp ), $struct;
}

In Test2::Manual::Tooling::TestBuilder under LEVEL, some help for this is provided, however running the code above under Test2 already results in an error because $Test::Builder::Level is not defined.

And in fact, much worse, just directly setting it doesn't do anything, unless Test::Builder is also use'd, so that should be mentioned.

Further, when wanting to eschew Test::Builder entirely, it redirects to Test2::API::Context, which doesn't mention level at all.

It does however link to Test2::API, which mentions level, however only as an argument to context(), at which point it is really hard to understand how one could easily and simply replace the above construct with something Test2-only for the purposes of internal test-writing.

In short: The LEVEL section probably needs a simple self-contained example of how to adjust the failure reporting level up by one or more caller levels ins a single call. :)