HOME

sh-3ll 1.0
DIR:/home/.cpan/build/Test2-Suite-0.000148-0/blib/man3/
Current File : /home/.cpan/build/Test2-Suite-0.000148-0/blib/man3/Test2::Manual::Testing.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test2::Manual::Testing 3"
.TH Test2::Manual::Testing 3 "2023-03-05" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test2::Manual::Testing \- Hub for documentation about writing tests with Test2.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document outlines all the tutorials and \s-1POD\s0 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.
.SH "NAMESPACE MAP"
.IX Header "NAMESPACE MAP"
When writing tests there are a couple namespaces to focus on:
.IP "Test2::Tools::*" 4
.IX Item "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.
.IP "Test2::Plugins::*" 4
.IX Item "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.
.IP "Test2::Bundle::*" 4
.IX Item "Test2::Bundle::*"
Bundles combine toolsets and plugins together to reduce your boilerplate. First
time test writers are encouraged to start with the Test2::V0 bundle (which
is an exception to the namespace rule as it does not live under
\&\f(CW\*(C`Test2::Bundle::\*(C'\fR). If you find yourself loading several plugins and toolsets
over and over again you could benefit from writing your own bundle.
.IP "Test2::Require::*" 4
.IX Item "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.
.SH "LISTING DEPENDENCIES"
.IX Header "LISTING DEPENDENCIES"
When you use Test2, specifically things included in Test2::Suite 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 as your dependency. Test2::Suite is a living distribution
intended to represent the \*(L"current\*(R" best practices. As tools, plugins, and
bundles evolve, old ones will become discouraged and potentially be moved from
Test2::Suite into their own distributions.
.PP
One goal of Test2::Suite is to avoid breaking backwards compatibility.
Another goal is to always improve by replacing bad designs with better ones.
When necessary Test2::Suite 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.
.PP
So for example, if you use Test2::V0, and Dist::Zilla you
should have this in your config:
.PP
.Vb 2
\&    [Prereqs / TestRequires]
\&    Test2::V0 = 0.000060
.Ve
.PP
You \fB\s-1SHOULD NOT\s0\fR do this:
.PP
.Vb 2
\&    [Prereqs / TestRequires]
\&    Test2::Suite = 0.000060
.Ve
.PP
Because Test2::V0 might not always be part of Test2::Suite.
.PP
When writing new tests you should often check Test2::Suite to see what the
current recommended bundle is.
.PP
\fIDist::Zilla\fR
.IX Subsection "Dist::Zilla"
.PP
.Vb 2
\&    [Prereqs / TestRequires]
\&    Test2::V0 = 0.000060
.Ve
.PP
\fIExtUtils::MakeMaker\fR
.IX Subsection "ExtUtils::MakeMaker"
.PP
.Vb 7
\&    my %WriteMakefileArgs = (
\&      ...,
\&      "TEST_REQUIRES" => {
\&        "Test2::V0" => "0.000060"
\&      },
\&      ...
\&    );
.Ve
.PP
\fIModule::Install\fR
.IX Subsection "Module::Install"
.PP
.Vb 1
\&    test_requires \*(AqTest2::V0\*(Aq => \*(Aq0.000060\*(Aq;
.Ve
.PP
\fIModule::Build\fR
.IX Subsection "Module::Build"
.PP
.Vb 7
\&    my $build = Module::Build\->new(
\&        ...,
\&        test_requires => {
\&            "Test2::V0" => "0.000060",
\&        },
\&        ...
\&    );
.Ve
.SH "TUTORIALS"
.IX Header "TUTORIALS"
.SS "\s-1SIMPLE/INTRODUCTION TUTORIAL\s0"
.IX Subsection "SIMPLE/INTRODUCTION TUTORIAL"
Test2::Manual::Testing::Introduction is an introduction to writing tests
using the Test2 tools.
.SS "\s-1MIGRATING FROM TEST::BUILDER\s0 and \s-1TEST::MORE\s0"
.IX Subsection "MIGRATING FROM TEST::BUILDER and TEST::MORE"
Test2::Manual::Testing::Migrating Is a tutorial for converting old tests
that use Test::Builder or Test::More to the newer Test2 way of doing
things.
.SS "\s-1ADVANCED PLANNING\s0"
.IX Subsection "ADVANCED PLANNING"
Test2::Manual::Testing::Planning is a tutorial on the many ways to set a
plan.
.SS "\s-1TODO TESTS\s0"
.IX Subsection "TODO TESTS"
Test2::Manual::Testing::Todo is a tutorial for markings tests as \s-1TODO.\s0
.SS "\s-1SUBTESTS\s0"
.IX Subsection "SUBTESTS"
\&\s-1COMING SOON.\s0
.SS "\s-1COMPARISONS\s0"
.IX Subsection "COMPARISONS"
\&\s-1COMING SOON.\s0
.PP
\fI\s-1SIMPLE COMPARISONS\s0\fR
.IX Subsection "SIMPLE COMPARISONS"
.PP
\&\s-1COMING SOON.\s0
.PP
\fI\s-1ADVANCED COMPARISONS\s0\fR
.IX Subsection "ADVANCED COMPARISONS"
.PP
\&\s-1COMING SOON.\s0
.SS "\s-1TESTING EXPORTERS\s0"
.IX Subsection "TESTING EXPORTERS"
\&\s-1COMING SOON.\s0
.SS "\s-1TESTING CLASSES\s0"
.IX Subsection "TESTING CLASSES"
\&\s-1COMING SOON.\s0
.SS "\s-1TRAPPING\s0"
.IX Subsection "TRAPPING"
\&\s-1COMING SOON.\s0
.PP
\fI\s-1TRAPPING EXCEPTIONS\s0\fR
.IX Subsection "TRAPPING EXCEPTIONS"
.PP
\&\s-1COMING SOON.\s0
.PP
\fI\s-1TRAPPING WARNINGS\s0\fR
.IX Subsection "TRAPPING WARNINGS"
.PP
\&\s-1COMING SOON.\s0
.SS "\s-1DEFERRED TESTING\s0"
.IX Subsection "DEFERRED TESTING"
\&\s-1COMING SOON.\s0
.SS "\s-1MANAGING ENCODINGS\s0"
.IX Subsection "MANAGING ENCODINGS"
\&\s-1COMING SOON.\s0
.SS "AUTO-ABORT \s-1ON FAILURE\s0"
.IX Subsection "AUTO-ABORT ON FAILURE"
\&\s-1COMING SOON.\s0
.SS "\s-1CONTROLLING RANDOM BEHAVIOR\s0"
.IX Subsection "CONTROLLING RANDOM BEHAVIOR"
\&\s-1COMING SOON.\s0
.SS "\s-1WRITING YOUR OWN BUNDLE\s0"
.IX Subsection "WRITING YOUR OWN BUNDLE"
\&\s-1COMING SOON.\s0
.SH "TOOLSET DOCUMENTATION"
.IX Header "TOOLSET DOCUMENTATION"
\&\s-1COMING SOON.\s0
.SH "PLUGIN DOCUMENTATION"
.IX Header "PLUGIN DOCUMENTATION"
\&\s-1COMING SOON.\s0
.SH "BUNDLE DOCUMENTATION"
.IX Header "BUNDLE DOCUMENTATION"
\&\s-1COMING SOON.\s0
.SH "REQUIRE DOCUMENTATION"
.IX Header "REQUIRE DOCUMENTATION"
\&\s-1COMING SOON.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Manual \- Primary index of the manual.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Manual can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH "AUTHORS"
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2018 Chad Granum <exodist@cpan.org>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR