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

```{index} single: Test2::Tools
```

# Test2::Tools

Documentation for Tools.

## DESCRIPTION

Tools are packages that export test functions, typically all related to a
specific aspect of testing. If you have a couple different categories of
exports then you may want to break them into separate modules.

Tools should export testing functions. Loading tools **should not** have side-
effects, or alter the behavior of other tools. If you want to alter behaviors
or create side-effects then you probably want to write a [Test2::Plugin](Plugin.md).

## FAQ

- Why is it called Test2::Tools, and not Test2::Tool?

    This question arises since Tools is the only namespace in the plural. This is
    because each Plugin should be a distinct unit of functionality, but a Tools
    dist can (and usually should) export several tools. A bundle is also typically
    described as a single unit. Nobody would like Test2::Bundles::Foo.

- Should my tools subclass Test2::Tools?

    No. Currently this class is empty. Eventually we may want to add behavior, in
    which case we do not want anyone to already be subclassing it.

## HOW DO I WRITE A 'TOOLS' MODULE?

It is very easy to write tools:

```perl
package Test2::Tools::Mine
use strict;
use warnings;

## All tools should use the context() function.
use Test2::API qw/context/;

our @EXPORTS = qw/ok plan/;
use base 'Exporter';

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

    # All tool functions should start by grabbing a context
    my $ctx = context();

    # The context is the primary interface for generating events
    $ctx->ok($bool, $name);

    # When you are done you release the context
    $ctx->release;

    return $bool ? 1 : 0;
}

sub plan {
    my ($max) = @_;
    my $ctx = context();
    $ctx->plan($max);
    $ctx->release;
}

1;
```

See [Test2::API::Context](API/Context.md) for documentation on what the `$ctx` object can do.

## 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/`

## Modules

- [`Test2::Tools::AsyncSubtest`](Tools/AsyncSubtest.md) - Tools for writing async subtests.
- [`Test2::Tools::Basic`](Tools/Basic.md) - Test2 implementation of the basic testing tools.
- [`Test2::Tools::Class`](Tools/Class.md) - Test2 implementation of the tools for testing classes.
- [`Test2::Tools::ClassicCompare`](Tools/ClassicCompare.md) - Classic (Test::More style) comparison tools.
- [`Test2::Tools::Compare`](Tools/Compare.md) - Tools for comparing deep data structures.
- [`Test2::Tools::Defer`](Tools/Defer.md) - Write tests that get executed at a later time
- [`Test2::Tools::Encoding`](Tools/Encoding.md) - Tools for managing the encoding of [Test2](../Test2.md) based tests.
- [`Test2::Tools::Event`](Tools/Event.md) - Tools for generating test events.
- [`Test2::Tools::Exception`](Tools/Exception.md) - Test2 based tools for checking exceptions
- [`Test2::Tools::Exports`](Tools/Exports.md) - Tools for validating exporters.
- [`Test2::Tools::GenTemp`](Tools/GenTemp.md) - Tool for generating a populated temp directory.
- [`Test2::Tools::Grab`](Tools/Grab.md) - Temporarily intercept all events without adding a scope level.
- [`Test2::Tools::Mock`](Tools/Mock.md) - Class/Instance mocking for Test2.
- [`Test2::Tools::Ref`](Tools/Ref.md) - Tools for validating references.
- [`Test2::Tools::Refcount`](Tools/Refcount.md) - `Test2::Tools::Refcount` - assert reference counts on objects
- [`Test2::Tools::Spec`](Tools/Spec.md) - RSPEC implementation on top of Test2::Workflow
- [`Test2::Tools::Subtest`](Tools/Subtest.md) - Tools for writing subtests
- [`Test2::Tools::Target`](Tools/Target.md) - Alias the testing target package.
- [`Test2::Tools::Tester`](Tools/Tester.md) - Tools to help you test other testing tools.
- [`Test2::Tools::Tiny`](Tools/Tiny.md) - Tiny set of tools for unfortunate souls who cannot use [Test2::Suite](Suite.md).
- [`Test2::Tools::Warnings`](Tools/Warnings.md) - Tools to verify warnings.

```{toctree}
:hidden:
:maxdepth: 1

Tools/AsyncSubtest
Tools/Basic
Tools/Class
Tools/ClassicCompare
Tools/Compare
Tools/Defer
Tools/Encoding
Tools/Event
Tools/Exception
Tools/Exports
Tools/GenTemp
Tools/Grab
Tools/Mock
Tools/Ref
Tools/Refcount
Tools/Spec
Tools/Subtest
Tools/Target
Tools/Tester
Tools/Tiny
Tools/Warnings
```