Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::Manual::Tooling::Testing.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Manual::Tooling::Testing 3pm"
61 .TH Test2::Manual::Tooling::Testing 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Manual::Tooling::Testing \- Tutorial on how to test your testing tools.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 Testing your test tools used to be a complex and difficult prospect. The old
71 tools such as Test::Tester and Test::Builder::Tester were limited, and
72 fragile. Test2 on the other hand was designed from the very start to be easily
73 tested! This tutorial shows you how.
74 .SH "THE HOLY GRAIL OF TESTING YOUR TOOLS"
75 .IX Header "THE HOLY GRAIL OF TESTING YOUR TOOLS"
76 The key to making Test2 easily testable (specially when compared to
77 Test::Builder) is the \f(CW\*(C`intercept\*(C'\fR function.
78 .PP
79 .Vb 1
80 \& use Test2::API qw/intercept/;
81 \&
82 \& my $events = intercept {
83 \& ok(1, "pass");
84 \& ok(0, "fail");
85 \&
86 \& diag("A diag");
87 \& };
88 .Ve
89 .PP
90 The intercept function lets you use any test tools you want inside a codeblock.
91 No events or contexts generated within the intercept codeblock will have any
92 effect on the outside testing state. The \f(CW\*(C`intercept\*(C'\fR function completely
93 isolates the tools called within.
94 .PP
95 \&\fBNote:\fR Plugins and things that affect global API state may not be fully
96 isolated. \f(CW\*(C`intercept\*(C'\fR is intended specifically for event isolation.
97 .PP
98 The \f(CW\*(C`intercept\*(C'\fR function will return an arrayref containing all the events
99 that were generated within the codeblock. You can now make any assertions you
100 want about the events you expected your tools to generate.
101 .PP
102 .Vb 6
103 \& [
104 \& bless({...}, \*(AqTest2::Event::Ok\*(Aq), # pass
105 \& bless({...}, \*(AqTest2::Event::Ok\*(Aq), # fail
106 \& bless({...}, \*(AqTest2::Event::Diag\*(Aq), # Failure diagnostics (not always a second event)
107 \& bless({...}, \*(AqTest2::Event::Diag\*(Aq), # custom \*(AqA diag\*(Aq message
108 \& ]
109 .Ve
110 .PP
111 Most test tools eventually produce one or more events. To effectively verify
112 the events you get from intercept you really should read up on how events work
113 Test2::Manual::Anatomy::Event. Once you know about events you can move on to
114 the next section which points you at some helpers.
115 .SH "ADDITIONAL HELPERS"
116 .IX Header "ADDITIONAL HELPERS"
117 .SS Test2::Tools::Tester
118 .IX Subsection "Test2::Tools::Tester"
119 This is the most recent set of tools to help you test your events. To really
120 understand these you should familiarize yourself with
121 Test2::Manual::Anatomy::Event. If you are going to be writing anything more
122 than the most simple of tools you should know how events work.
123 .PP
124 The Test2::Tools::Tester documentation is a good place for further reading.
125 .SS Test2::Tools::HarnessTester
126 .IX Subsection "Test2::Tools::HarnessTester"
127 The Test2::Tools::HarnessTester can export the \f(CWsummarize_events()\fR tool.
128 This tool lets you run your event arrayref through Test2::Harness so that you
129 can get a pass/fail summary.
130 .PP
131 .Vb 1
132 \& my $summary = summarize_events($events);
133 .Ve
134 .PP
135 The summary looks like this:
136 .PP
137 .Vb 8
138 \& {
139 \& plan => $plan_facet, # the plan event facet
140 \& pass => $bool, # true if the events result in a pass
141 \& fail => $bool, # true if the events result in a fail
142 \& errors => $error_count, # Number of error facets seen
143 \& failures => $failure_count, # Number of failing assertions seen
144 \& assertions => $assertion_count, # Total number of assertions seen
145 \& }
146 .Ve
147 .SS Test2::Tools::Compare
148 .IX Subsection "Test2::Tools::Compare"
149 \&\fBDEPRECATED\fR These tools were written before the switch to faceted events.
150 These will still work, but are no longer the recommended way to test your
151 tools.
152 .PP
153 The Test2::Tools::Compare library exports a handful of extras to help test
154 events.
155 .ie n .IP "event $TYPE => ..." 4
156 .el .IP "event \f(CW$TYPE\fR => ..." 4
157 .IX Item "event $TYPE => ..."
158 Use in an array check against \f(CW$events\fR to check for a specific type of event
159 with the properties you specify.
160 .ie n .IP "fail_events $TYPE => ..." 4
161 .el .IP "fail_events \f(CW$TYPE\fR => ..." 4
162 .IX Item "fail_events $TYPE => ..."
163 Use when you expect a failing assertion of \f(CW$TYPE\fR. This will automatically check
164 that the next event following it is a diagnostics message with the default
165 failure text.
166 .Sp
167 \&\fBNote:\fR This is outdated as a single event may now possess both the failing
168 assertion AND the failing text, such events will fail this test.
169 .SH "SEE ALSO"
170 .IX Header "SEE ALSO"
171 Test2::Manual \- Primary index of the manual.
172 .SH SOURCE
173 .IX Header "SOURCE"
174 The source code repository for Test2\-Manual can be found at
175 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
176 .SH MAINTAINERS
177 .IX Header "MAINTAINERS"
178 .IP "Chad Granum <[email protected]>" 4
179 .IX Item "Chad Granum <[email protected]>"
180 .SH AUTHORS
181 .IX Header "AUTHORS"
182 .IP "Chad Granum <[email protected]>" 4
183 .IX Item "Chad Granum <[email protected]>"
184 .SH COPYRIGHT
185 .IX Header "COPYRIGHT"
186 Copyright Chad Granum <[email protected]>.
187 .PP
188 This program is free software; you can redistribute it and/or
189 modify it under the same terms as Perl itself.
190 .PP
191 See \fIhttp://dev.perl.org/licenses/\fR