Debian Codegraph @

upstream/debian-unstable/man3/Test2::Suite.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "Test2::Suite 3perl"
58 .TH Test2::Suite 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::Suite \- Distribution with a rich set of tools built upon the Test2
65 framework.
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 Rich set of tools, plugins, bundles, etc built upon the Test2 testing
69 library. If you are interested in writing tests, this is the distribution for
70 you.
71 .SS "WHAT ARE TOOLS, PLUGINS, AND BUNDLES?"
72 .IX Subsection "WHAT ARE TOOLS, PLUGINS, AND BUNDLES?"
73 .IP TOOLS 4
74 .IX Item "TOOLS"
75 Tools are packages that export functions for use in test files. These functions
76 typically generate events. Tools \fBSHOULD NEVER\fR alter behavior of other tools,
77 or the system in general.
78 .IP PLUGINS 4
79 .IX Item "PLUGINS"
80 Plugins are packages that produce effects, or alter behavior of tools. An
81 example would be a plugin that causes the test to bail out after the first
82 failure. Plugins \fBSHOULD NOT\fR export anything.
83 .IP BUNDLES 4
84 .IX Item "BUNDLES"
85 Bundles are collections of tools and plugins. A bundle should load and
86 re-export functions from Tool packages. A bundle may also load and configure
87 any number of plugins.
88 .PP
89 If you want to write something that both exports new functions, and effects
90 behavior, you should write both a Tools distribution, and a Plugin distribution,
91 then a Bundle that loads them both. This is important as it helps avoid the
92 problem where a package exports much-desired tools, but
93 also produces undesirable side effects.
94 .SH "INCLUDED BUNDLES"
95 .IX Header "INCLUDED BUNDLES"
96 .IP Test2::V# 4
97 .IX Item "Test2::V#"
98 These do not live in the bundle namespace as they are the primary ways to use
99 Test2::Suite.
100 .Sp
101 The current latest is Test2::V0.
102 .Sp
103 .Vb 2
104 \& use Test2::V0;
105 \& # strict and warnings are on for you now.
106 \&
107 \& ok(...);
108 \&
109 \& # Note: is does deep checking, unlike the \*(Aqis\*(Aq from Test::More.
110 \& is(...);
111 \&
112 \& ...
113 \&
114 \& done_testing;
115 .Ve
116 .Sp
117 This bundle includes every tool listed in the "INCLUDED TOOLS" section below,
118 except for Test2::Tools::ClassicCompare. This bundle provides most of what
119 anyone writing tests could need. This is also the preferred bundle/toolset of
120 the Test2 author.
121 .Sp
122 See Test2::V0 for complete documentation.
123 .IP Extended 4
124 .IX Item "Extended"
125 \&\fB** Deprecated **\fR See Test2::V0
126 .Sp
127 .Vb 2
128 \& use Test2::Bundle::Extended;
129 \& # strict and warnings are on for you now.
130 \&
131 \& ok(...);
132 \&
133 \& # Note: is does deep checking, unlike the \*(Aqis\*(Aq from Test::More.
134 \& is(...);
135 \&
136 \& ...
137 \&
138 \& done_testing;
139 .Ve
140 .Sp
141 This bundle includes every tool listed in the "INCLUDED TOOLS" section below,
142 except for Test2::Tools::ClassicCompare. This bundle provides most of what
143 anyone writing tests could need. This is also the preferred bundle/toolset of
144 the Test2 author.
145 .Sp
146 See Test2::Bundle::Extended for complete documentation.
147 .IP More 4
148 .IX Item "More"
149 .Vb 3
150 \& use Test2::Bundle::More;
151 \& use strict;
152 \& use warnings;
153 \&
154 \& plan 3; # Or you can use done_testing at the end
155 \&
156 \& ok(...);
157 \&
158 \& is(...); # Note: String compare
159 \&
160 \& is_deeply(...);
161 \&
162 \& ...
163 \&
164 \& done_testing; # Use instead of plan
165 .Ve
166 .Sp
167 This bundle is meant to be a \fImostly\fR drop-in replacement for Test::More.
168 There are some notable differences to be aware of however. Some exports are
169 missing: \f(CW\*(C`eq_array\*(C'\fR, \f(CW\*(C`eq_hash\*(C'\fR, \f(CW\*(C`eq_set\*(C'\fR, \f(CW$TODO\fR, \f(CW\*(C`explain\*(C'\fR, \f(CW\*(C`use_ok\*(C'\fR,
170 \&\f(CW\*(C`require_ok\*(C'\fR. As well it is no longer possible to set the plan at import:
171 \&\f(CW\*(C`use .. tests => 5\*(C'\fR. \f(CW$TODO\fR has been replaced by the \f(CWtodo()\fR
172 function. Planning is done using \f(CW\*(C`plan\*(C'\fR, \f(CW\*(C`skip_all\*(C'\fR, or \f(CW\*(C`done_testing\*(C'\fR.
173 .Sp
174 See Test2::Bundle::More for complete documentation.
175 .IP Simple 4
176 .IX Item "Simple"
177 .Vb 3
178 \& use Test2::Bundle::Simple;
179 \& use strict;
180 \& use warnings;
181 \&
182 \& plan 1;
183 \&
184 \& ok(...);
185 .Ve
186 .Sp
187 This bundle is meant to be a \fImostly\fR drop-in replacement for Test::Simple.
188 See Test2::Bundle::Simple for complete documentation.
189 .SH "INCLUDED TOOLS"
190 .IX Header "INCLUDED TOOLS"
191 .IP Basic 4
192 .IX Item "Basic"
193 Basic provides most of the essential tools previously found in Test::More.
194 However it does not export any tools used for comparison. The basic \f(CW\*(C`pass\*(C'\fR,
195 \&\f(CW\*(C`fail\*(C'\fR, \f(CW\*(C`ok\*(C'\fR functions are present, as are functions for planning.
196 .Sp
197 See Test2::Tools::Basic for complete documentation.
198 .IP Compare 4
199 .IX Item "Compare"
200 This provides \f(CW\*(C`is\*(C'\fR, \f(CW\*(C`like\*(C'\fR, \f(CW\*(C`isnt\*(C'\fR, \f(CW\*(C`unlike\*(C'\fR, and several additional
201 helpers. \fBNote:\fR These are all \fIdeep\fR comparison tools and work like a
202 combination of Test::More's \f(CW\*(C`is\*(C'\fR and \f(CW\*(C`is_deeply\*(C'\fR.
203 .Sp
204 See Test2::Tools::Compare for complete documentation.
205 .IP ClassicCompare 4
206 .IX Item "ClassicCompare"
207 This provides Test::More flavored \f(CW\*(C`is\*(C'\fR, \f(CW\*(C`like\*(C'\fR, \f(CW\*(C`isnt\*(C'\fR, \f(CW\*(C`unlike\*(C'\fR, and
208 \&\f(CW\*(C`is_deeply\*(C'\fR. It also provides \f(CW\*(C`cmp_ok\*(C'\fR.
209 .Sp
210 See Test2::Tools::ClassicCompare for complete documentation.
211 .IP Class 4
212 .IX Item "Class"
213 This provides functions for testing objects and classes, things like \f(CW\*(C`isa_ok\*(C'\fR.
214 .Sp
215 See Test2::Tools::Class for complete documentation.
216 .IP Defer 4
217 .IX Item "Defer"
218 This provides functions for writing test functions in one place, but running
219 them later. This is useful for testing things that run in an altered state.
220 .Sp
221 See Test2::Tools::Defer for complete documentation.
222 .IP Encoding 4
223 .IX Item "Encoding"
224 This exports a single function that can be used to change the encoding of all
225 your test output.
226 .Sp
227 See Test2::Tools::Encoding for complete documentation.
228 .IP Exports 4
229 .IX Item "Exports"
230 This provides tools for verifying exports. You can verify that functions have
231 been imported, or that they have not been imported.
232 .Sp
233 See Test2::Tools::Exports for complete documentation.
234 .IP Mock 4
235 .IX Item "Mock"
236 This provides tools for mocking objects and classes. This is based largely on
237 Mock::Quick, but several interface improvements have been added that cannot
238 be added to Mock::Quick itself without breaking backwards compatibility.
239 .Sp
240 See Test2::Tools::Mock for complete documentation.
241 .IP Ref 4
242 .IX Item "Ref"
243 This exports tools for validating and comparing references.
244 .Sp
245 See Test2::Tools::Ref for complete documentation.
246 .IP Spec 4
247 .IX Item "Spec"
248 This is an RSPEC implementation with concurrency support.
249 .Sp
250 See Test2::Tools::Spec for more details.
251 .IP Subtest 4
252 .IX Item "Subtest"
253 This exports tools for running subtests.
254 .Sp
255 See Test2::Tools::Subtest for complete documentation.
256 .IP Target 4
257 .IX Item "Target"
258 This lets you load the package(s) you intend to test, and alias them into
259 constants/package variables.
260 .Sp
261 See Test2::Tools::Target for complete documentation.
262 .SH "INCLUDED PLUGINS"
263 .IX Header "INCLUDED PLUGINS"
264 .IP BailOnFail 4
265 .IX Item "BailOnFail"
266 The much requested "bail-out on first failure" plugin. When this plugin is
267 loaded, any failure will cause the test to bail out immediately.
268 .Sp
269 See Test2::Plugin::BailOnFail for complete documentation.
270 .IP DieOnFail 4
271 .IX Item "DieOnFail"
272 The much requested "die on first failure" plugin. When this plugin is
273 loaded, any failure will cause the test to die immediately.
274 .Sp
275 See Test2::Plugin::DieOnFail for complete documentation.
276 .IP ExitSummary 4
277 .IX Item "ExitSummary"
278 This plugin gives you statistics and diagnostics at the end of your test in the
279 event of a failure.
280 .Sp
281 See Test2::Plugin::ExitSummary for complete documentation.
282 .IP SRand 4
283 .IX Item "SRand"
284 Use this to set the random seed to a specific seed, or to the current date.
285 .Sp
286 See Test2::Plugin::SRand for complete documentation.
287 .IP UTF8 4
288 .IX Item "UTF8"
289 Turn on utf8 for your testing. This sets the current file to be utf8, it also
290 sets STDERR, STDOUT, and your formatter to all output utf8.
291 .Sp
292 See Test2::Plugin::UTF8 for complete documentation.
293 .SH "INCLUDED REQUIREMENT CHECKERS"
294 .IX Header "INCLUDED REQUIREMENT CHECKERS"
295 .IP AuthorTesting 4
296 .IX Item "AuthorTesting"
297 Using this package will cause the test file to be skipped unless the
298 AUTHOR_TESTING environment variable is set.
299 .Sp
300 See Test2::Require::AuthorTesting for complete documentation.
301 .IP EnvVar 4
302 .IX Item "EnvVar"
303 Using this package will cause the test file to be skipped unless a custom
304 environment variable is set.
305 .Sp
306 See Test2::Require::EnvVar for complete documentation.
307 .IP Fork 4
308 .IX Item "Fork"
309 Using this package will cause the test file to be skipped unless the system is
310 capable of forking (including emulated forking).
311 .Sp
312 See Test2::Require::Fork for complete documentation.
313 .IP RealFork 4
314 .IX Item "RealFork"
315 Using this package will cause the test file to be skipped unless the system is
316 capable of true forking.
317 .Sp
318 See Test2::Require::RealFork for complete documentation.
319 .IP Module 4
320 .IX Item "Module"
321 Using this package will cause the test file to be skipped unless the specified
322 module is installed (and optionally at a minimum version).
323 .Sp
324 See Test2::Require::Module for complete documentation.
325 .IP Perl 4
326 .IX Item "Perl"
327 Using this package will cause the test file to be skipped unless the specified
328 minimum perl version is met.
329 .Sp
330 See Test2::Require::Perl for complete documentation.
331 .IP Threads 4
332 .IX Item "Threads"
333 Using this package will cause the test file to be skipped unless the system has
334 threading enabled.
335 .Sp
336 \&\fBNote:\fR This will not turn threading on for you.
337 .Sp
338 See Test2::Require::Threads for complete documentation.
339 .SH "SEE ALSO"
340 .IX Header "SEE ALSO"
341 See the Test2 documentation for a namespace map. Everything in this
342 distribution uses Test2.
343 .PP
344 Test2::Manual is the Test2 Manual.
345 .SH "CONTACTING US"
346 .IX Header "CONTACTING US"
347 Many Test2 developers and users lurk on <irc://irc.perl.org/#perl>. We also
348 have a slack team that can be joined by anyone with an \f(CW\*(C`@cpan.org\*(C'\fR email
349 address <https://perl\-test2.slack.com/> If you do not have an \f(CW\*(C`@cpan.org\*(C'\fR
350 email you can ask for a slack invite by emailing Chad Granum
351 <[email protected]>.
352 .SH SOURCE
353 .IX Header "SOURCE"
354 The source code repository for Test2\-Suite can be found at
355 \&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
356 .SH MAINTAINERS
357 .IX Header "MAINTAINERS"
358 .IP "Chad Granum <[email protected]>" 4
359 .IX Item "Chad Granum <[email protected]>"
360 .SH AUTHORS
361 .IX Header "AUTHORS"
362 .PD 0
363 .IP "Chad Granum <[email protected]>" 4
364 .IX Item "Chad Granum <[email protected]>"
365 .PD
366 .SH COPYRIGHT
367 .IX Header "COPYRIGHT"
368 Copyright 2018 Chad Granum <[email protected]>.
369 .PP
370 This program is free software; you can redistribute it and/or
371 modify it under the same terms as Perl itself.
372 .PP
373 See \fIhttp://dev.perl.org/licenses/\fR