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

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

# Test2::Manual::Testing

Hub for documentation about writing tests with Test2.

## DESCRIPTION

This document outlines all the tutorials and POD that cover writing tests. This
section does not cover any Test2 internals, nor does it cover how to write new
tools, for that see [Test2::Manual::Tooling](Tooling.md).

## NAMESPACE MAP

When writing tests there are a couple namespaces to focus on:

- Test2::Tools::\*

    This is where toolsets can be found. A toolset exports functions that help you
    make assertions about your code. Toolsets will only export functions, they
    should not ever have extra/global effects.

- Test2::Plugins::\*

    This is where plugins live. Plugins should not export anything, but instead
    will introduce or alter behaviors for Test2 in general. These behaviors may be
    lexically scoped, or they may be global.

- Test2::Bundle::\*

    Bundles combine toolsets and plugins together to reduce your boilerplate. First
    time test writers are encouraged to start with the [Test2::V1](../V1.md) bundle (which
    is an exception to the namespace rule as it does not live under
    `Test2::Bundle::`). If you find yourself loading several plugins and toolsets
    over and over again you could benefit from writing your own bundle.

- Test2::Require::\*

    This namespace contains modules that will cause a test to skip if specific
    conditions are not met. Use this if you have tests that only run on specific
    perl versions, or require external libraries that may not always be available.

## LISTING DEPENDENCIES

When you use [Test2](../../Test2.md), specifically things included in [Test2::Suite](../Suite.md) you need
to list them in your modules test dependencies. It is important to note that
you should list the tools/plugins/bundles you need, you should not simply list
[Test2::Suite](../Suite.md) as your dependency. [Test2::Suite](../Suite.md) is a living distribution
intended to represent the "current" best practices. As tools, plugins, and
bundles evolve, old ones will become discouraged and potentially be moved from
[Test2::Suite](../Suite.md) into their own distributions.

One goal of [Test2::Suite](../Suite.md) is to avoid breaking backwards compatibility.
Another goal is to always improve by replacing bad designs with better ones.
When necessary [Test2::Suite](../Suite.md) will break old modules out into separate dists
and define new ones, typically with a new bundle. In short, if we feel the need
to break something we will do so by creating a new bundle, and discouraging the
old one, but we will not break the old one.

So for example, if you use [Test2::V1](../V1.md), and [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla) you
should have this in your config:

```text
[Prereqs / TestRequires]
Test2::V1 = 0.000060
```

You **SHOULD NOT** do this:

```text
[Prereqs / TestRequires]
Test2::Suite = 0.000060
```

Because [Test2::V1](../V1.md) might not always be part of [Test2::Suite](../Suite.md).

When writing new tests you should often check [Test2::Suite](../Suite.md) to see what the
current recommended bundle is.

### Dist::Zilla

```text
[Prereqs / TestRequires]
Test2::V1 = 0.000060
```

#### ExtUtils::MakeMaker

```perl
my %WriteMakefileArgs = (
  ...,
  "TEST_REQUIRES" => {
    "Test2::V1" => "0.000060"
  },
  ...
);
```

#### Module::Install

```perl
test_requires 'Test2::V1' => '0.000060';
```

#### Module::Build

```perl
my $build = Module::Build->new(
    ...,
    test_requires => {
        "Test2::V1" => "0.000060",
    },
    ...
);
```

## TUTORIALS

### SIMPLE/INTRODUCTION TUTORIAL

[Test2::Manual::Testing::Introduction](Testing/Introduction.md) is an introduction to writing tests
using the [Test2](../../Test2.md) tools.

### MIGRATING FROM TEST::BUILDER and TEST::MORE

[Test2::Manual::Testing::Migrating](Testing/Migrating.md) Is a tutorial for converting old tests
that use [Test::Builder](../../Test/Builder.md) or [Test::More](../../Test/More.md) to the newer [Test2](../../Test2.md) way of doing
things.

### ADVANCED PLANNING

[Test2::Manual::Testing::Planning](Testing/Planning.md) is a tutorial on the many ways to set a
plan.

### TODO TESTS

[Test2::Manual::Testing::Todo](Testing/Todo.md) is a tutorial for markings tests as TODO.

### SUBTESTS

COMING SOON.

### COMPARISONS

COMING SOON.

#### SIMPLE COMPARISONS

COMING SOON.

#### ADVANCED COMPARISONS

COMING SOON.

### TESTING EXPORTERS

COMING SOON.

### TESTING CLASSES

COMING SOON.

### TRAPPING

COMING SOON.

#### TRAPPING EXCEPTIONS

COMING SOON.

#### TRAPPING WARNINGS

COMING SOON.

### DEFERRED TESTING

COMING SOON.

### MANAGING ENCODINGS

COMING SOON.

### AUTO-ABORT ON FAILURE

COMING SOON.

### CONTROLLING RANDOM BEHAVIOR

COMING SOON.

### WRITING YOUR OWN BUNDLE

COMING SOON.

## TOOLSET DOCUMENTATION

COMING SOON.

## PLUGIN DOCUMENTATION

COMING SOON.

## BUNDLE DOCUMENTATION

COMING SOON.

## REQUIRE DOCUMENTATION

COMING SOON.

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

## Modules

- [`Test2::Manual::Testing::Introduction`](Testing/Introduction.md) - Introduction to testing with Test2.
- [`Test2::Manual::Testing::Migrating`](Testing/Migrating.md) - How to migrate existing tests from Test::More to Test2.
- [`Test2::Manual::Testing::Planning`](Testing/Planning.md) - The many ways to set a plan.
- [`Test2::Manual::Testing::Todo`](Testing/Todo.md) - Tutorial for marking tests as TODO.

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

Testing/Introduction
Testing/Migrating
Testing/Planning
Testing/Todo
```