Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::Manual::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::Testing 3pm"
61 .TH Test2::Manual::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::Testing \- Hub for documentation about writing tests with Test2.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This document outlines all the tutorials and POD that cover writing tests. This
71 section does not cover any Test2 internals, nor does it cover how to write new
72 tools, for that see Test2::Manual::Tooling.
73 .SH "NAMESPACE MAP"
74 .IX Header "NAMESPACE MAP"
75 When writing tests there are a couple namespaces to focus on:
76 .IP Test2::Tools::* 4
77 .IX Item "Test2::Tools::*"
78 This is where toolsets can be found. A toolset exports functions that help you
79 make assertions about your code. Toolsets will only export functions, they
80 should not ever have extra/global effects.
81 .IP Test2::Plugins::* 4
82 .IX Item "Test2::Plugins::*"
83 This is where plugins live. Plugins should not export anything, but instead
84 will introduce or alter behaviors for Test2 in general. These behaviors may be
85 lexically scoped, or they may be global.
86 .IP Test2::Bundle::* 4
87 .IX Item "Test2::Bundle::*"
88 Bundles combine toolsets and plugins together to reduce your boilerplate. First
89 time test writers are encouraged to start with the Test2::V0 bundle (which
90 is an exception to the namespace rule as it does not live under
91 \&\f(CW\*(C`Test2::Bundle::\*(C'\fR). If you find yourself loading several plugins and toolsets
92 over and over again you could benefit from writing your own bundle.
93 .IP Test2::Require::* 4
94 .IX Item "Test2::Require::*"
95 This namespace contains modules that will cause a test to skip if specific
96 conditions are not met. Use this if you have tests that only run on specific
97 perl versions, or require external libraries that may not always be available.
98 .SH "LISTING DEPENDENCIES"
99 .IX Header "LISTING DEPENDENCIES"
100 When you use Test2, specifically things included in Test2::Suite you need
101 to list them in your modules test dependencies. It is important to note that
102 you should list the tools/plugins/bundles you need, you should not simply list
103 Test2::Suite as your dependency. Test2::Suite is a living distribution
104 intended to represent the "current" best practices. As tools, plugins, and
105 bundles evolve, old ones will become discouraged and potentially be moved from
106 Test2::Suite into their own distributions.
107 .PP
108 One goal of Test2::Suite is to avoid breaking backwards compatibility.
109 Another goal is to always improve by replacing bad designs with better ones.
110 When necessary Test2::Suite will break old modules out into separate dists
111 and define new ones, typically with a new bundle. In short, if we feel the need
112 to break something we will do so by creating a new bundle, and discouraging the
113 old one, but we will not break the old one.
114 .PP
115 So for example, if you use Test2::V0, and Dist::Zilla you
116 should have this in your config:
117 .PP
118 .Vb 2
119 \& [Prereqs / TestRequires]
120 \& Test2::V0 = 0.000060
121 .Ve
122 .PP
123 You \fBSHOULD NOT\fR do this:
124 .PP
125 .Vb 2
126 \& [Prereqs / TestRequires]
127 \& Test2::Suite = 0.000060
128 .Ve
129 .PP
130 Because Test2::V0 might not always be part of Test2::Suite.
131 .PP
132 When writing new tests you should often check Test2::Suite to see what the
133 current recommended bundle is.
134 .PP
135 \fIDist::Zilla\fR
136 .IX Subsection "Dist::Zilla"
137 .PP
138 .Vb 2
139 \& [Prereqs / TestRequires]
140 \& Test2::V0 = 0.000060
141 .Ve
142 .PP
143 \fIExtUtils::MakeMaker\fR
144 .IX Subsection "ExtUtils::MakeMaker"
145 .PP
146 .Vb 7
147 \& my %WriteMakefileArgs = (
148 \& ...,
149 \& "TEST_REQUIRES" => {
150 \& "Test2::V0" => "0.000060"
151 \& },
152 \& ...
153 \& );
154 .Ve
155 .PP
156 \fIModule::Install\fR
157 .IX Subsection "Module::Install"
158 .PP
159 .Vb 1
160 \& test_requires \*(AqTest2::V0\*(Aq => \*(Aq0.000060\*(Aq;
161 .Ve
162 .PP
163 \fIModule::Build\fR
164 .IX Subsection "Module::Build"
165 .PP
166 .Vb 7
167 \& my $build = Module::Build\->new(
168 \& ...,
169 \& test_requires => {
170 \& "Test2::V0" => "0.000060",
171 \& },
172 \& ...
173 \& );
174 .Ve
175 .SH TUTORIALS
176 .IX Header "TUTORIALS"
177 .SS "SIMPLE/INTRODUCTION TUTORIAL"
178 .IX Subsection "SIMPLE/INTRODUCTION TUTORIAL"
179 Test2::Manual::Testing::Introduction is an introduction to writing tests
180 using the Test2 tools.
181 .SS "MIGRATING FROM TEST::BUILDER and TEST::MORE"
182 .IX Subsection "MIGRATING FROM TEST::BUILDER and TEST::MORE"
183 Test2::Manual::Testing::Migrating Is a tutorial for converting old tests
184 that use Test::Builder or Test::More to the newer Test2 way of doing
185 things.
186 .SS "ADVANCED PLANNING"
187 .IX Subsection "ADVANCED PLANNING"
188 Test2::Manual::Testing::Planning is a tutorial on the many ways to set a
189 plan.
190 .SS "TODO TESTS"
191 .IX Subsection "TODO TESTS"
192 Test2::Manual::Testing::Todo is a tutorial for markings tests as TODO.
193 .SS SUBTESTS
194 .IX Subsection "SUBTESTS"
195 COMING SOON.
196 .SS COMPARISONS
197 .IX Subsection "COMPARISONS"
198 COMING SOON.
199 .PP
200 \fISIMPLE COMPARISONS\fR
201 .IX Subsection "SIMPLE COMPARISONS"
202 .PP
203 COMING SOON.
204 .PP
205 \fIADVANCED COMPARISONS\fR
206 .IX Subsection "ADVANCED COMPARISONS"
207 .PP
208 COMING SOON.
209 .SS "TESTING EXPORTERS"
210 .IX Subsection "TESTING EXPORTERS"
211 COMING SOON.
212 .SS "TESTING CLASSES"
213 .IX Subsection "TESTING CLASSES"
214 COMING SOON.
215 .SS TRAPPING
216 .IX Subsection "TRAPPING"
217 COMING SOON.
218 .PP
219 \fITRAPPING EXCEPTIONS\fR
220 .IX Subsection "TRAPPING EXCEPTIONS"
221 .PP
222 COMING SOON.
223 .PP
224 \fITRAPPING WARNINGS\fR
225 .IX Subsection "TRAPPING WARNINGS"
226 .PP
227 COMING SOON.
228 .SS "DEFERRED TESTING"
229 .IX Subsection "DEFERRED TESTING"
230 COMING SOON.
231 .SS "MANAGING ENCODINGS"
232 .IX Subsection "MANAGING ENCODINGS"
233 COMING SOON.
234 .SS "AUTO\-ABORT ON FAILURE"
235 .IX Subsection "AUTO-ABORT ON FAILURE"
236 COMING SOON.
237 .SS "CONTROLLING RANDOM BEHAVIOR"
238 .IX Subsection "CONTROLLING RANDOM BEHAVIOR"
239 COMING SOON.
240 .SS "WRITING YOUR OWN BUNDLE"
241 .IX Subsection "WRITING YOUR OWN BUNDLE"
242 COMING SOON.
243 .SH "TOOLSET DOCUMENTATION"
244 .IX Header "TOOLSET DOCUMENTATION"
245 COMING SOON.
246 .SH "PLUGIN DOCUMENTATION"
247 .IX Header "PLUGIN DOCUMENTATION"
248 COMING SOON.
249 .SH "BUNDLE DOCUMENTATION"
250 .IX Header "BUNDLE DOCUMENTATION"
251 COMING SOON.
252 .SH "REQUIRE DOCUMENTATION"
253 .IX Header "REQUIRE DOCUMENTATION"
254 COMING SOON.
255 .SH "SEE ALSO"
256 .IX Header "SEE ALSO"
257 Test2::Manual \- Primary index of the manual.
258 .SH SOURCE
259 .IX Header "SOURCE"
260 The source code repository for Test2\-Manual can be found at
261 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
262 .SH MAINTAINERS
263 .IX Header "MAINTAINERS"
264 .IP "Chad Granum <[email protected]>" 4
265 .IX Item "Chad Granum <[email protected]>"
266 .SH AUTHORS
267 .IX Header "AUTHORS"
268 .IP "Chad Granum <[email protected]>" 4
269 .IX Item "Chad Granum <[email protected]>"
270 .SH COPYRIGHT
271 .IX Header "COPYRIGHT"
272 Copyright Chad Granum <[email protected]>.
273 .PP
274 This program is free software; you can redistribute it and/or
275 modify it under the same terms as Perl itself.
276 .PP
277 See \fIhttp://dev.perl.org/licenses/\fR