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

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

# Test2::Todo

TODO extension for Test2.

## DESCRIPTION

This is an object that lets you create and manage TODO states for tests. This
is an extension, not a plugin or a tool. This library can be used by plugins
and tools to manage todo states.

If you simply want to write a todo test then you should look at the `todo`
function provided by [Test2::Tools::Basic](Tools/Basic.md).

## SYNOPSIS

```perl
use Test2::Todo;

## Start the todo
my $todo = Test2::Todo->new(reason => 'Fix later');

## Will be considered todo, so suite still passes
ok(0, "oops");

## End the todo
$todo->end;

## TODO has ended, this test will actually fail.
ok(0, "oops");
```

## CONSTRUCTION OPTIONS

- reason (required)

    The reason for the todo, this can be any defined value.

- hub (optional)

    The hub to which the TODO state should be applied. If none is provided then the
    current global hub is used.

## INSTANCE METHODS

- $todo->end

    End the todo state.

## CLASS METHODS

- $count = Test2::Todo->hub\_in\_todo($hub)

    If the hub has any todo objects this will return the total number of them. If
    the hub has no todo objects it will return 0.

## OTHER NOTES

### How it works

When an instance is created a filter sub is added to the [Test2::Hub](Hub.md). This
filter will set the `todo` and `diag_todo` attributes on all events as they
come in. When the instance is destroyed, or `end()` is called, the filter is
removed.

When a new hub is pushed (such as when a subtest is started) the new hub will
inherit the filter, but it will only set `diag_todo`, it will not set `todo`
on events in child hubs.

### $todo->end is called at destruction

If your `$todo` object falls out of scope and gets garbage collected, the todo
will end.

### Can I use multiple instances?

Yes. The most recently created one that is still active will win.

## SOURCE

The source code repository for Test2-Suite 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/`