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::Tooling::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::Tooling::Testing 3"
.TH Test2::Manual::Tooling::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::Tooling::Testing \- Tutorial on how to test your testing tools.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Testing your test tools used to be a complex and difficult prospect. The old
tools such as Test::Tester and Test::Builder::Tester were limited, and
fragile. Test2 on the other hand was designed from the very start to be easily
tested! This tutorial shows you how.
.SH "THE HOLY GRAIL OF TESTING YOUR TOOLS"
.IX Header "THE HOLY GRAIL OF TESTING YOUR TOOLS"
The key to making Test2 easily testable (specially when compared to
Test::Builder) is the \f(CW\*(C`intercept\*(C'\fR function.
.PP
.Vb 1
\&    use Test2::API qw/intercept/;
\&
\&    my $events = intercept {
\&        ok(1, "pass");
\&        ok(0, "fail");
\&
\&        diag("A diag");
\&    };
.Ve
.PP
The intercept function lets you use any test tools you want inside a codeblock.
No events or contexts generated within the intercept codeblock will have any
effect on the outside testing state. The \f(CW\*(C`intercept\*(C'\fR function completely
isolates the tools called within.
.PP
\&\fBNote:\fR Plugins and things that effect global \s-1API\s0 state may not be fully
isolated. \f(CW\*(C`intercept\*(C'\fR is intended specifically for event isolation.
.PP
The \f(CW\*(C`intercept\*(C'\fR function will return an arrayref containing all the events
that were generated within the codeblock. You can now make any assertions you
want about the events you expected your tools to generate.
.PP
.Vb 6
\&    [
\&        bless({...}, \*(AqTest2::Event::Ok\*(Aq),   # pass
\&        bless({...}, \*(AqTest2::Event::Ok\*(Aq),   # fail
\&        bless({...}, \*(AqTest2::Event::Diag\*(Aq), # Failure diagnostics (not always a second event)
\&        bless({...}, \*(AqTest2::Event::Diag\*(Aq), # custom \*(AqA diag\*(Aq message
\&    ]
.Ve
.PP
Most test tools eventually produce one or more events. To effectively verify
the events you get from intercept you really should read up on how events work
Test2::Manual::Anatomy::Event. Once you know about events you can move on to
the next section which points you at some helpers.
.SH "ADDITIONAL HELPERS"
.IX Header "ADDITIONAL HELPERS"
.SS "Test2::Tools::Tester"
.IX Subsection "Test2::Tools::Tester"
This is the most recent set of tools to help you test your events. To really
understand these you should familiarize yourself with
Test2::Manual::Anatomy::Event. If you are going to be writing anything more
than the most simple of tools you should know how events work.
.PP
The Test2::Tools::Tester documentation is a good place for further reading.
.SS "Test2::Tools::HarnessTester"
.IX Subsection "Test2::Tools::HarnessTester"
The Test2::Tools::HarnessTester can export the \f(CW\*(C`summarize_events()\*(C'\fR tool.
This tool lets you run your event arrayref through Test2::Harness so that you
can get a pass/fail summary.
.PP
.Vb 1
\&    my $summary = summarize_events($events);
.Ve
.PP
The summary looks like this:
.PP
.Vb 8
\&    {
\&        plan       => $plan_facet,         # the plan event facet
\&        pass       => $bool,               # true if the events result in a pass
\&        fail       => $bool,               # true if the events result in a fail
\&        errors     => $error_count,        # Number of error facets seen
\&        failures   => $failure_count,      # Number of failing assertions seen
\&        assertions => $assertion_count,    # Total number of assertions seen
\&    }
.Ve
.SS "Test2::Tools::Compare"
.IX Subsection "Test2::Tools::Compare"
\&\fB\s-1DEPRECATED\s0\fR These tools were written before the switch to faceted events.
These will still work, but are no longer the recommended way to test your
tools.
.PP
The Test2::Tools::Compare library exports a handful of extras to help test
events.
.ie n .IP "event $TYPE => ..." 4
.el .IP "event \f(CW$TYPE\fR => ..." 4
.IX Item "event $TYPE => ..."
Use in an array check against \f(CW$events\fR to check for a specific type of event
with the properties you specify.
.ie n .IP "fail_events $TYPE => ..." 4
.el .IP "fail_events \f(CW$TYPE\fR => ..." 4
.IX Item "fail_events $TYPE => ..."
Use when you expect a failing assertion of \f(CW$TYPE\fR. This will automatically check
that the next event following it is a diagnostics message with the default
failure text.
.Sp
\&\fBNote:\fR This is outdated as a single event may now possess both the failing
assertion \s-1AND\s0 the failing text, such events will fail this test.
.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