Test2::...g::Todo(3)

✨ NAME ✨

Welcome to the Test2::Manual::Testing::Todo manual page, bestie — it's a whole tutorial for marking tests as TODO. 🎀

💖 DESCRIPTION 💖

Okay so this tutorial covers the process of marking tests as TODO. It also describes how TODO works under the hood. That's the vibe, and it's giving documentation with lore. ✨

🛠️ THE TOOL 🛠️

Use this, no cap:

use Test2::Tools::Basic qw/todo/;

🎀 TODO BLOCK 🎀

This form is low-magic, fr fr. All tests inside the block are marked as todo; tests outside the block are not todo. You do not need to do any variable management. The flaw with this form is that it adds a couple levels to the stack, which can break some high-magic tests. 💀

Overall this is the preferred form unless you have a special case that requires the variable form. 👑

todo "Reason for the todo" => sub {
    ok(0, "fail but todo");
    ...
};

🦋 TODO VARIABLE 🦋

This form maintains the todo scope for the life of the variable. This is useful for tests that are sensitive to scope changes. It closely emulates the Test::More style which localized the $TODO package variable. Once the variable is destroyed (set it to undef, scope end, etc) the TODO state ends. Slay. 💅

my $todo = todo "Reason for the todo";
ok(0, "fail but todo");
...
$todo = undef;

🔥 MANUAL TODO EVENTS 🔥

use Test2::API qw/context/;

sub todo_ok {
    my ($bool, $name, $todo) = @_;

    my $ctx = context();
    $ctx->send_event('Ok', pass => $bool, effective_pass => 1, todo => $todo);
    $ctx->release;

    return $bool;
}

The Test2::Event::Ok event has a todo field which should have the todo reason. The event also has the pass and effective_pass fields. The pass field is the actual pass/fail value. The effective_pass is used to determine if the event is an actual failure (should always be set to true with todo). 🫶

👑 HOW THE TODO TOOLS WORK UNDER THE HOOD 👑

The Test2::Todo library gets the current Test2::Hub instance and adds a filter. The filter that is added will set the todo and effective_pass fields on any Test2::Event::Ok events that pass through the hub. The filter also converts Test2::Event::Diag events into Test2::Event::Note events. Iconic behavior, honestly. 🌈

🌸 SEE ALSO 🌸

• Test2::Manual — Primary index of the manual.

🍓 SOURCE 🍓

The source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/.

💜 MAINTAINERS 💜

• Chad Granum <exodist@cpan.org>

🌺 AUTHORS 🌺

• Chad Granum <exodist@cpan.org>

🎀 COPYRIGHT 🎀

Copyright Chad Granum <exodist@cpan.org>.

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

See http://dev.perl.org/licenses/

---

xoxo, your fav manual page is serving perl v5.42.0, dated 2025-07-28, with footer title Test2::...g::Todo(3) ✨💅🦋