Debian Codegraph @

upstream/debian-unstable/man3/Test2.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 3perl"
58 .TH Test2 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 \- Framework for writing test tools that all work together.
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 Test2 is a new testing framework produced by forking Test::Builder,
68 completely refactoring it, adding many new features and capabilities.
69 .SS "WHAT IS NEW?"
70 .IX Subsection "WHAT IS NEW?"
71 .IP "Easier to test new testing tools." 4
72 .IX Item "Easier to test new testing tools."
73 From the beginning Test2 was built with introspection capabilities. With
74 Test::Builder it was difficult at best to capture test tool output for
75 verification. Test2 Makes it easy with \f(CWTest2::API::intercept()\fR.
76 .IP "Better diagnostics capabilities." 4
77 .IX Item "Better diagnostics capabilities."
78 Test2 uses an Test2::API::Context object to track filename, line number, and
79 tool details. This object greatly simplifies tracking for where errors should
80 be reported.
81 .IP "Event driven." 4
82 .IX Item "Event driven."
83 Test2 based tools produce events which get passed through a processing system
84 before being output by a formatter. This event system allows for rich plugin
85 and extension support.
86 .IP "More complete API." 4
87 .IX Item "More complete API."
88 Test::Builder only provided a handful of methods for generating lines of TAP.
89 Test2 took inventory of everything people were doing with Test::Builder that
90 required hacking it up. Test2 made public API functions for nearly all the
91 desired functionality people didn't previously have.
92 .IP "Support for output other than TAP." 4
93 .IX Item "Support for output other than TAP."
94 Test::Builder assumed everything would end up as TAP. Test2 makes no such
95 assumption. Test2 provides ways for you to specify alternative and custom
96 formatters.
97 .IP "Subtest implementation is more sane." 4
98 .IX Item "Subtest implementation is more sane."
99 The Test::Builder implementation of subtests was certifiably insane. Test2 uses
100 a stacked event hub system that greatly improves how subtests are implemented.
101 .IP "Support for threading/forking." 4
102 .IX Item "Support for threading/forking."
103 Test2 support for forking and threading can be turned on using Test2::IPC.
104 Once turned on threading and forking operate sanely and work as one would
105 expect.
106 .SH "GETTING STARTED"
107 .IX Header "GETTING STARTED"
108 If you are interested in writing tests using new tools then you should look at
109 Test2::Suite. Test2::Suite is a separate cpan distribution that contains
110 many tools implemented on Test2.
111 .PP
112 If you are interested in writing new tools you should take a look at
113 Test2::API first.
114 .SH "NAMESPACE LAYOUT"
115 .IX Header "NAMESPACE LAYOUT"
116 This describes the namespace layout for the Test2 ecosystem. Not all the
117 namespaces listed here are part of the Test2 distribution, some are implemented
118 in Test2::Suite.
119 .SS Test2::Tools::
120 .IX Subsection "Test2::Tools::"
121 This namespace is for sets of tools. Modules in this namespace should export
122 tools like \f(CWok()\fR and \f(CWis()\fR. Most things written for Test2 should go here.
123 Modules in this namespace \fBMUST NOT\fR export subs from other tools. See the
124 "Test2::Bundle::" namespace if you want to do that.
125 .SS Test2::Plugin::
126 .IX Subsection "Test2::Plugin::"
127 This namespace is for plugins. Plugins are modules that change or enhance the
128 behavior of Test2. An example of a plugin is a module that sets the encoding to
129 utf8 globally. Another example is a module that causes a bail-out event after
130 the first test failure.
131 .SS Test2::Bundle::
132 .IX Subsection "Test2::Bundle::"
133 This namespace is for bundles of tools and plugins. Loading one of these may
134 load multiple tools and plugins. Modules in this namespace should not implement
135 tools directly. In general modules in this namespace should load tools and
136 plugins, then re-export things into the consumers namespace.
137 .SS Test2::Require::
138 .IX Subsection "Test2::Require::"
139 This namespace is for modules that cause a test to be skipped when conditions
140 do not allow it to run. Examples would be modules that skip the test on older
141 perls, or when non-essential modules have not been installed.
142 .SS Test2::Formatter::
143 .IX Subsection "Test2::Formatter::"
144 Formatters live under this namespace. Test2::Formatter::TAP is the only
145 formatter currently. It is acceptable for third party distributions to create
146 new formatters under this namespace.
147 .SS Test2::Event::
148 .IX Subsection "Test2::Event::"
149 Events live under this namespace. It is considered acceptable for third party
150 distributions to add new event types in this namespace.
151 .SS Test2::Hub::
152 .IX Subsection "Test2::Hub::"
153 Hub subclasses (and some hub utility objects) live under this namespace. It is
154 perfectly reasonable for third party distributions to add new hub subclasses in
155 this namespace.
156 .SS Test2::IPC::
157 .IX Subsection "Test2::IPC::"
158 The IPC subsystem lives in this namespace. There are not many good reasons to
159 add anything to this namespace, with exception of IPC drivers.
160 .PP
161 \fITest2::IPC::Driver::\fR
162 .IX Subsection "Test2::IPC::Driver::"
163 .PP
164 IPC drivers live in this namespace. It is fine to create new IPC drivers and to
165 put them in this namespace.
166 .SS Test2::Util::
167 .IX Subsection "Test2::Util::"
168 This namespace is for general utilities used by testing tools. Please be
169 considerate when adding new modules to this namespace.
170 .SS Test2::API::
171 .IX Subsection "Test2::API::"
172 This is for Test2 API and related packages.
173 .SS Test2::
174 .IX Subsection "Test2::"
175 The Test2:: namespace is intended for extensions and frameworks. Tools,
176 Plugins, etc should not go directly into this namespace. However extensions
177 that are used to build tools and plugins may go here.
178 .PP
179 In short: If the module exports anything that should be run directly by a test
180 script it should probably NOT go directly into \f(CW\*(C`Test2::XXX\*(C'\fR.
181 .SH "SEE ALSO"
182 .IX Header "SEE ALSO"
183 Test2::API \- Primary API functions.
184 .PP
185 Test2::API::Context \- Detailed documentation of the context object.
186 .PP
187 Test2::IPC \- The IPC system used for threading/fork support.
188 .PP
189 Test2::Formatter \- Formatters such as TAP live here.
190 .PP
191 Test2::Event \- Events live in this namespace.
192 .PP
193 Test2::Hub \- All events eventually funnel through a hub. Custom hubs are how
194 \&\f(CWintercept()\fR and \f(CWrun_subtest()\fR are implemented.
195 .SH "CONTACTING US"
196 .IX Header "CONTACTING US"
197 Many Test2 developers and users lurk on <irc://irc.perl.org/#perl\-qa> and
198 <irc://irc.perl.org/#toolchain>. We also have a slack team that can be joined
199 by anyone with an \f(CW\*(C`@cpan.org\*(C'\fR email address <https://perl\-test2.slack.com/>
200 If you do not have an \f(CW\*(C`@cpan.org\*(C'\fR email you can ask for a slack invite by
201 emailing Chad Granum <[email protected]>.
202 .SH SOURCE
203 .IX Header "SOURCE"
204 The source code repository for Test2 can be found at
205 <https://github.com/Test\-More/test\-more/>.
206 .SH MAINTAINERS
207 .IX Header "MAINTAINERS"
208 .IP "Chad Granum <[email protected]>" 4
209 .IX Item "Chad Granum <[email protected]>"
210 .SH AUTHORS
211 .IX Header "AUTHORS"
212 .PD 0
213 .IP "Chad Granum <[email protected]>" 4
214 .IX Item "Chad Granum <[email protected]>"
215 .PD
216 .SH COPYRIGHT
217 .IX Header "COPYRIGHT"
218 Copyright 2020 Chad Granum <[email protected]>.
219 .PP
220 This program is free software; you can redistribute it and/or
221 modify it under the same terms as Perl itself.
222 .PP
223 See <https://dev.perl.org/licenses/>