<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Manual/Testing/Todo.md. Do not edit. -->

```{index} single: Test2::Manual::Testing::Todo
```

# Test2::Manual::Testing::Todo

Tutorial for marking tests as TODO.

## DESCRIPTION

This tutorial covers the process of marking tests as TODO. It also describes
how TODO works under the hood.

## THE TOOL

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

### TODO BLOCK

This form is low-magic. 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.

```perl
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. This closely emulates the
[Test::More](../../../Test/More.md) style which localized the `$TODO` package variable. Once the
variable is destroyed (set it to undef, scope end, etc) the TODO state ends.

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

## MANUAL TODO EVENTS

```perl
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/Ok.md) 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 tot true with
todo).

## HOW THE TODO TOOLS WORK UNDER THE HOOD

The [Test2::Todo](../../Todo.md) library gets the current [Test2::Hub](../../Hub.md) instance and adds a
filter. The filter that is added will set the `todo` and `effective_pass` fields on
any [Test2::Event::Ok](../../Event/Ok.md) events that pass through the hub. The filter also
converts [Test2::Event::Diag](../../Event/Diag.md) events into [Test2::Event::Note](../../Event/Note.md) events.

## SEE ALSO

[Test2::Manual](../../Manual.md) - 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/`