Test2:...::Todo(3perl)

✨ Test2::Manual::Testing::Todo ✨

hey bestie 💖 welcome to the Test2::Manual::Testing::Todo page from the Perl Programmers Reference Guide — this is the tutorial for marking tests as TODO, and yes we're also gonna peek under the hood at how TODO actually works. iykyk. 🎀

---

🌸 NAME 🌸

Test2::Manual::Testing::Todo — the tutorial for marking tests as TODO. periodt. 💅

---

🦋 DESCRIPTION 🦋

okay so, this tutorial walks you through marking tests as TODO, and it also spills the tea on how TODO works under the hood. both things, bestie. no cap. ✨

---

💅 THE TOOL 💅

first up, you gotta pull in the tool:

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

🎀 TODO BLOCK 🎀

this form is low-magic and honestly iconic for it. every test inside the block gets marked todo, and tests outside the block are not todo. and the best part?? you don't have to do any variable management. zero. none. 🫶

the one little flaw (not me being honest 🙈): it adds a couple levels to the stack, which can break some high-magic tests. 💀

overall though? this is the preferred form unless you've got a special case that needs the variable form. periodt.

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

⭐ TODO VARIABLE ⭐

this form keeps the todo scope alive for the entire life of the variable. super useful for tests that are sensitive to scope changes. it also closely emulates the Test::More style, which localized the $TODO package variable — nostalgic fr fr. 🥹

and the moment that variable gets destroyed (set it to undef, scope ends, whatever) the TODO state ends too. bye bestie 👋

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

---

🌈 MANUAL TODO EVENTS 🌈

sometimes you wanna do it yourself, and that's valid:

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;
}

so here's the lore 🧚 the Test2::Event::Ok event has a todo field, and that's where the todo reason goes. it also has the pass and effective_pass fields:

• the pass field is the actual pass/fail value.
• the effective_pass field is what decides whether the event counts as an actual failure — and when you're doing todo, you should always set it to true. 💯

---

👑 HOW THE TODO TOOLS WORK UNDER THE HOOD 👑

okay bestie, the secret lore 🫢 — the Test2::Todo library grabs the current Test2::Hub instance and adds a filter to it.

that filter does two things:

• it sets the todo and effective_pass fields on any Test2::Event::Ok events that pass through the hub.
• it also converts Test2::Event::Diag events into Test2::Event::Note events.

slay. it's giving main character energy for a filter honestly. 💅✨

---

🍓 SEE ALSO 🍓

• Test2::Manual — the primary index of the manual. start there bestie 📚

---

💜 SOURCE 💜

the source code repository for Test2-Manual lives 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/

---

okay that's the whole page bestie 🫶 this was perl v5.44.0, dated 2026-10-17, and the page was Test2:...::Todo(3perl) — now go mark something TODO and slay ✨💅🎀