Debian Codegraph @

upstream/debian-unstable/man3/Test2::Manual::Anatomy::EndToEnd.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::Manual::Anatomy::EndToEnd 3perl"
58 .TH Test2::Manual::Anatomy::EndToEnd 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::Manual::EndToEnd \- Overview of Test2 from load to finish.
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 This is a high level overview of everything from loading Test2 through the end
68 of a test script.
69 .SH "WHAT HAPPENS WHEN I LOAD THE API?"
70 .IX Header "WHAT HAPPENS WHEN I LOAD THE API?"
71 .Vb 1
72 \& use Test2::API qw/context/;
73 .Ve
74 .IP "A singleton instance of Test2::API::Instance is created." 4
75 .IX Item "A singleton instance of Test2::API::Instance is created."
76 You have no access to this, it is an implementation detail.
77 .IP "Several API functions are defined that use the singleton instance." 4
78 .IX Item "Several API functions are defined that use the singleton instance."
79 You can import these functions, or use them directly.
80 .IP "Then what?" 4
81 .IX Item "Then what?"
82 It waits...
83 .Sp
84 The API intentionally does as little as possible. At this point something can
85 still change the formatter, load Test2::IPC, or have other global effects
86 that need to be done before the first Test2::API::Context is created. Once
87 the first Test2::API::Context is created the API will finish initialization.
88 .Sp
89 See "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?" for more information.
90 .SH "WHAT HAPPENS WHEN I USE A TOOL?"
91 .IX Header "WHAT HAPPENS WHEN I USE A TOOL?"
92 This section covers the basic workflow all tools such as \f(CWok()\fR must follow.
93 .PP
94 .Vb 2
95 \& sub ok($$) {
96 \& my ($bool, $name) = @_;
97 \&
98 \& my $ctx = context();
99 \&
100 \& my $event = $ctx\->send_event(\*(AqOk\*(Aq, pass => $bool, name => $name);
101 \&
102 \& ...
103 \&
104 \& $ctx\->release;
105 \& return $bool;
106 \& }
107 \&
108 \& ok(1, "1 is true");
109 .Ve
110 .IP "A tool function is run." 4
111 .IX Item "A tool function is run."
112 .Vb 1
113 \& ok(1, "1 is true");
114 .Ve
115 .IP "The tool acquires a context object." 4
116 .IX Item "The tool acquires a context object."
117 .Vb 1
118 \& my $ctx = context();
119 .Ve
120 .Sp
121 See "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?" for more information.
122 .IP "The tool uses the context object to create, send, and return events." 4
123 .IX Item "The tool uses the context object to create, send, and return events."
124 See "WHAT HAPPENS WHEN I SEND AN EVENT?" for more information.
125 .Sp
126 .Vb 1
127 \& my $event = $ctx\->send_event(\*(AqOk\*(Aq, pass => $bool, name => $name);
128 .Ve
129 .IP "When done the tool MUST release the context." 4
130 .IX Item "When done the tool MUST release the context."
131 See "WHAT HAPPENS WHEN I RELEASE A CONTEXT?" for more information.
132 .Sp
133 .Vb 1
134 \& $ctx\->release();
135 .Ve
136 .IP "The tool returns." 4
137 .IX Item "The tool returns."
138 .Vb 1
139 \& return $bool;
140 .Ve
141 .SH "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?"
142 .IX Header "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?"
143 .Vb 1
144 \& my $ctx = context();
145 .Ve
146 .PP
147 These actions may not happen exactly in this order, but that is an
148 implementation detail. For the purposes of this document this order is used to
149 help the reader understand the flow.
150 .IP "$!, $@, $? and $^E are captured and preserved." 4
151 .IX Item "$!, $@, $? and $^E are captured and preserved."
152 Test2 makes a point to preserve the values of $!, $@, $? and $^E such that the test
153 tools do not modify these variables unexpectedly. They are captured first thing
154 so that they can be restored later.
155 .IP "The API state is changed to 'loaded'." 4
156 .IX Item "The API state is changed to 'loaded'."
157 The 'loaded' state means that test tools have already started running. This is
158 important as some plugins need to take effect before any tests are run. This
159 state change only happens the first time a context is acquired, and may trigger
160 some hooks defined by plugins to run.
161 .IP "The current hub is found." 4
162 .IX Item "The current hub is found."
163 A context attaches itself to the current Test2::Hub. If there is no current
164 hub then the root hub will be initialized. This will also initialize the hub
165 stack if necessary.
166 .IP "Context acquire hooks fire." 4
167 .IX Item "Context acquire hooks fire."
168 It is possible to create global, or hub-specific hooks that fire whenever a
169 context is acquired, these hooks will fire now. These hooks fire even if there
170 is an existing context.
171 .IP "Any existing context is found." 4
172 .IX Item "Any existing context is found."
173 If the current hub already has a context then a clone of it will be used
174 instead of a completely new context. This is important because it allows nested
175 tools to inherit the context used by parent tools.
176 .IP "Stack depth is measured." 4
177 .IX Item "Stack depth is measured."
178 Test2 makes a point to catch mistakes in how the context is used. The stack
179 depth is used to accomplish this. If there is an existing context the depth
180 will be checked against the one found here. If the old context has the same
181 stack depth, or a shallower one, it means a tool is misbehaving and did not
182 clean up the context when it was done, in which case the old context will be
183 cleaned up, and a warning issued.
184 .IP "A new context is created (if no existing context was found)" 4
185 .IX Item "A new context is created (if no existing context was found)"
186 If there is no existing context, a new one will be created using the data
187 collected so far.
188 .IP "Context init hooks fire (if no existing context was found)" 4
189 .IX Item "Context init hooks fire (if no existing context was found)"
190 If a new context was created, context-creation hooks will fire.
191 .IP "$!, $@, $?, and $^E are restored." 4
192 .IX Item "$!, $@, $?, and $^E are restored."
193 We make sure $!, $@, $?, and $^E are unchanged at this point so that changes we
194 made will not effect anything else. This is done in case something inside the
195 context construction accidentally changed these vars.
196 .IP "The context is returned." 4
197 .IX Item "The context is returned."
198 You have a shiney new context object, or a clone of the existing context.
199 .SH "WHAT HAPPENS WHEN I SEND AN EVENT?"
200 .IX Header "WHAT HAPPENS WHEN I SEND AN EVENT?"
201 .Vb 1
202 \& my $event = $ctx\->send_event(\*(AqOk\*(Aq, pass => $bool, name => $name);
203 .Ve
204 .IP "The Test2::Event::Ok module is loaded." 4
205 .IX Item "The Test2::Event::Ok module is loaded."
206 The \f(CWsend_event()\fR method will automatically load any Event package necessary.
207 Normally \f(CWsend_event()\fR will assume the first argument is an event class
208 without the \f(CW\*(C`Test2::Event::\*(C'\fR prefix, which it will add for you. If you want to
209 use an event class that is in a different namespace you can prefix the class
210 name with a \f(CW\*(C`+\*(C'\fR to tell the tool that you are giving a fully qualified class
211 name:
212 .Sp
213 .Vb 1
214 \& my $event = $ctx\->send_event(\*(Aq+Fully::Qualified::Event\*(Aq, pass => $bool, name => $name);
215 .Ve
216 .IP "A new instance of Test2::Event::Ok is created." 4
217 .IX Item "A new instance of Test2::Event::Ok is created."
218 The event object is instantiated using the provided parameters.
219 .IP "The event object is sent to the hub." 4
220 .IX Item "The event object is sent to the hub."
221 The hub takes over from here.
222 .IP "The hub runs the event through any filters." 4
223 .IX Item "The hub runs the event through any filters."
224 Filters are able to modify or remove events. Filters are run first, before the
225 event can modify global test state.
226 .IP "The global test state is updated to reflect the event." 4
227 .IX Item "The global test state is updated to reflect the event."
228 If the event effects test count then the count will be incremented. If the
229 event causes failure then the failure count will be incremented. There are a
230 couple other ways the global state can be effected as well.
231 .IP "The event is sent to the formatter" 4
232 .IX Item "The event is sent to the formatter"
233 After the state is changed the hub will send the event to the formatter for
234 rendering. This is where TAP is normally produced.
235 .IP "The event is sent to all listeners." 4
236 .IX Item "The event is sent to all listeners."
237 There can be any number of listeners that take action when events are
238 processed, this happens now.
239 .SH "WHAT HAPPENS WHEN I RELEASE A CONTEXT?"
240 .IX Header "WHAT HAPPENS WHEN I RELEASE A CONTEXT?"
241 .Vb 1
242 \& $ctx\->release;
243 .Ve
244 .IP "The current context clone is released." 4
245 .IX Item "The current context clone is released."
246 If your tool is nested inside another, then releasing will simply destroy the
247 copy of the context, nothing else will happen.
248 .IP "If this was the canonical context, it will actually release" 4
249 .IX Item "If this was the canonical context, it will actually release"
250 When a context is created it is considered 'canon'. Any context obtained by a
251 nested tool will be considered a child context linked to the canonical one.
252 Releasing child contexts does not do anything of note (but is still required).
253 .IP "Release hooks are called" 4
254 .IX Item "Release hooks are called"
255 Release hooks are the main motivation behind making the \f(CWrelease()\fR method,
256 and making it a required action on the part of test tools. These are hooks that
257 we can have called when a tool is complete. This is how plugins like
258 Test2::Plugin::DieOnFail are implemented. If we simply had a destructor call
259 the hooks then we would be unable to write this plugin as a \f(CW\*(C`die\*(C'\fR inside of a
260 destructor is useless.
261 .IP "The context is cleared" 4
262 .IX Item "The context is cleared"
263 The main context data is cleared allowing the next tool to create a new
264 context. This is important as the next tool very likely has a new line number.
265 .IP "$!, $@, $?, and $^E are restored" 4
266 .IX Item "$!, $@, $?, and $^E are restored"
267 When a Test2 tool is complete it will restore $@, $!, $? and $^E to avoid action at
268 a distance.
269 .SH "WHAT HAPPENS WHEN I USE \fBdone_testing()\fP?"
270 .IX Header "WHAT HAPPENS WHEN I USE done_testing()?"
271 .Vb 1
272 \& done_testing();
273 .Ve
274 .IP "Any pending IPC events will be culled." 4
275 .IX Item "Any pending IPC events will be culled."
276 If IPC is turned on, a final culling will take place.
277 .IP "Follow-up hooks are run" 4
278 .IX Item "Follow-up hooks are run"
279 The follow-up hooks are a way to run actions when a hub is complete. This is
280 useful for adding cleanup tasks, or final tests to the end of a test.
281 .IP "The final plan event is generated and processed." 4
282 .IX Item "The final plan event is generated and processed."
283 The final plan event will be produced using the current test count as the
284 number of tests planned.
285 .IP "The current hub is finalized." 4
286 .IX Item "The current hub is finalized."
287 This will mark the hub is complete, and will not allow new events to be
288 processed.
289 .SH "WHAT HAPPENS WHEN A TEST SCRIPT IS DONE?"
290 .IX Header "WHAT HAPPENS WHEN A TEST SCRIPT IS DONE?"
291 Test2 has some behaviors it runs in an \f(CW\*(C`END { ... }\*(C'\fR block after tests are
292 done running. This end block does some final checks to warn you if something
293 went wrong. This end block also sets the exit value of the script.
294 .IP "API Versions are checked." 4
295 .IX Item "API Versions are checked."
296 A warning will be produced if Test::Builder is loaded, but has a different
297 version compared to Test2::API. This situation can happen if you downgrade
298 to an older Test-Simple distribution, and is a bad situation.
299 .IP "Any remaining context objects are cleaned up." 4
300 .IX Item "Any remaining context objects are cleaned up."
301 If there are leftover context objects they will need to be cleaned up. A
302 leftover context is never a good thing, and usually requires a warning. A
303 leftover context could also be the result of an exception being thrown which
304 terminates the script, Test2 is fairly good at noticing this and not warning
305 in these cases as the warning would simply be noise.
306 .IP "Child processes are sent a 'waiting' event." 4
307 .IX Item "Child processes are sent a 'waiting' event."
308 If IPC is active, a waiting event is sent to all child processes.
309 .IP "The script will wait for all child processes and/or threads to complete." 4
310 .IX Item "The script will wait for all child processes and/or threads to complete."
311 This happens only when IPC is loaded, but Test::Builder is not. This behavior
312 is useful, but would break compatibility for legacy tests.
313 .IP "The hub stack is cleaned up." 4
314 .IX Item "The hub stack is cleaned up."
315 All hubs are finalized starting from the top. Leftover hubs are usually a bad
316 thing, so a warning is produced if any are found.
317 .IP "The root hub is finalized." 4
318 .IX Item "The root hub is finalized."
319 This step is a no-op if \f(CWdone_testing()\fR was used. If needed this will mark
320 the root hub as finished.
321 .IP "Exit callbacks are called." 4
322 .IX Item "Exit callbacks are called."
323 This is a chance for plugins to modify the final exit value of the script.
324 .IP "The scripts exit value ($?) is set." 4
325 .IX Item "The scripts exit value ($?) is set."
326 If the test encountered any failures this will be set to a non-zero value. If
327 possible this will be set to the number of failures, or 255 if the number is
328 larger than 255 (the max value allowed).
329 .IP "Broken module diagnostics" 4
330 .IX Item "Broken module diagnostics"
331 Test2 is aware of many modules which were broken by Test2's release. At this
332 point the script will check if any known-broken modules were loaded, and warn
333 you if they were.
334 .Sp
335 \&\fBNote:\fR This only happens if there were test failures. No broken module
336 warnings are produced on a success.
337 .SH "SEE ALSO"
338 .IX Header "SEE ALSO"
339 Test2::Manual \- Primary index of the manual.
340 .SH SOURCE
341 .IX Header "SOURCE"
342 The source code repository for Test2\-Manual can be found at
343 \&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
344 .SH MAINTAINERS
345 .IX Header "MAINTAINERS"
346 .IP "Chad Granum <[email protected]>" 4
347 .IX Item "Chad Granum <[email protected]>"
348 .SH AUTHORS
349 .IX Header "AUTHORS"
350 .PD 0
351 .IP "Chad Granum <[email protected]>" 4
352 .IX Item "Chad Granum <[email protected]>"
353 .PD
354 .SH COPYRIGHT
355 .IX Header "COPYRIGHT"
356 Copyright 2018 Chad Granum <[email protected]>.
357 .PP
358 This program is free software; you can redistribute it and/or
359 modify it under the same terms as Perl itself.
360 .PP
361 See \fIhttp://dev.perl.org/licenses/\fR