1Test2::Manual::Anatomy:U:sEenrdTCooEnntdr(i3b)uted PerlTDeosctu2m:e:nMtaantuiaoln::Anatomy::EndToEnd(3)
2
6 Test2::Manual::EndToEnd - Overview of Test2 from load to finish.
7
9 This is a high level overview of everything from loading Test2 through
10 the end of a test script.
11
13 use Test2::API qw/context/;
14 A singleton instance of Test2::API::Instance is created.
16 You have no access to this, it is an implementation detail.
17 Several API functions are defined that use the singleton instance.
19 You can import these functions, or use them directly.
20 Then what?
22 It waits...
23 The API intentionally does as little as possible. At this point
25 something can still change the formatter, load Test2::IPC, or have
26 other global effects that need to be done before the first
27 Test2::API::Context is created. Once the first Test2::API::Context
28 is created the API will finish initialization.
29 See "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?" for more information.
31
33 This section covers the basic workflow all tools such as "ok()" must
34 follow.
35 sub ok($$) {
37 my ($bool, $name) = @_;
38 my $ctx = context();
40 my $event = $ctx->send_event('Ok', pass => $bool, name => $name);
42 ...
44 $ctx->release;
46 return $bool;
47 }
48 ok(1, "1 is true");
50 A tool function is run.
52 ok(1, "1 is true");
53 The tool acquires a context object.
55 my $ctx = context();
56 See "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?" for more information.
58 The tool uses the context object to create, send, and return events.
60 See "WHAT HAPPENS WHEN I SEND AN EVENT?" for more information.
61 my $event = $ctx->send_event('Ok', pass => $bool, name => $name);
63 When done the tool MUST release the context.
65 See "WHAT HAPPENS WHEN I RELEASE A CONTEXT?" for more information.
66 $ctx->release();
68 The tool returns.
70 return $bool;
71
73 my $ctx = context();
74 These actions may not happen exactly in this order, but that is an
76 implementation detail. For the purposes of this document this order is
77 used to help the reader understand the flow.
78 $!, $@, $? and $^E are captured and preserved.
80 Test2 makes a point to preserve the values of $!, $@, $? and $^E
81 such that the test tools do not modify these variables
82 unexpectedly. They are captured first thing so that they can be
83 restored later.
84 The API state is changed to 'loaded'.
86 The 'loaded' state means that test tools have already started
87 running. This is important as some plugins need to take effect
88 before any tests are run. This state change only happens the first
89 time a context is acquired, and may trigger some hooks defined by
90 plugins to run.
91 The current hub is found.
93 A context attaches itself to the current Test2::Hub. If there is no
94 current hub then the root hub will be initialized. This will also
95 initialize the hub stack if necessary.
96 Context acquire hooks fire.
98 It is possible to create global, or hub-specific hooks that fire
99 whenever a context is acquired, these hooks will fire now. These
100 hooks fire even if there is an existing context.
101 Any existing context is found.
103 If the current hub already has a context then a clone of it will be
104 used instead of a completely new context. This is important because
105 it allows nested tools to inherit the context used by parent tools.
106 Stack depth is measured.
108 Test2 makes a point to catch mistakes in how the context is used.
109 The stack depth is used to accomplish this. If there is an existing
110 context the depth will be checked against the one found here. If
111 the old context has the same stack depth, or a shallower one, it
112 means a tool is misbehaving and did not clean up the context when
113 it was done, in which case the old context will be cleaned up, and
114 a warning issued.
115 A new context is created (if no existing context was found)
117 If there is no existing context, a new one will be created using
118 the data collected so far.
119 Context init hooks fire (if no existing context was found)
121 If a new context was created, context-creation hooks will fire.
122 $!, $@, $?, and $^E are restored.
124 We make sure $!, $@, $?, and $^E are unchanged at this point so
125 that changes we made will not effect anything else. This is done in
126 case something inside the context construction accidentally changed
127 these vars.
128 The context is returned.
130 You have a shiney new context object, or a clone of the existing
131 context.
132
134 my $event = $ctx->send_event('Ok', pass => $bool, name => $name);
135 The Test2::Event::Ok module is loaded.
137 The "send_event()" method will automatically load any Event package
138 necessary. Normally "send_event()" will assume the first argument
139 is an event class without the "Test2::Event::" prefix, which it
140 will add for you. If you want to use an event class that is in a
141 different namespace you can prefix the class name with a "+" to
142 tell the tool that you are giving a fully qualified class name:
143 my $event = $ctx->send_event('+Fully::Qualified::Event', pass => $bool, name => $name);
145 A new instance of Test2::Event::Ok is created.
147 The event object is instantiated using the provided parameters.
148 The event object is sent to the hub.
150 The hub takes over from here.
151 The hub runs the event through any filters.
153 Filters are able to modify or remove events. Filters are run first,
154 before the event can modify global test state.
155 The global test state is updated to reflect the event.
157 If the event effects test count then the count will be incremented.
158 If the event causes failure then the failure count will be
159 incremented. There are a couple other ways the global state can be
160 effected as well.
161 The event is sent to the formatter
163 After the state is changed the hub will send the event to the
164 formatter for rendering. This is where TAP is normally produced.
165 The event is sent to all listeners.
167 There can be any number of listeners that take action when events
168 are processed, this happens now.
169
171 $ctx->release;
172 The current context clone is released.
174 If your tool is nested inside another, then releasing will simply
175 destroy the copy of the context, nothing else will happen.
176 If this was the canonical context, it will actually release
178 When a context is created it is considered 'canon'. Any context
179 obtained by a nested tool will be considered a child context linked
180 to the canonical one. Releasing child contexts does not do
181 anything of note (but is still required).
182 Release hooks are called
184 Release hooks are the main motivation behind making the "release()"
185 method, and making it a required action on the part of test tools.
186 These are hooks that we can have called when a tool is complete.
187 This is how plugins like Test2::Plugin::DieOnFail are implemented.
188 If we simply had a destructor call the hooks then we would be
189 unable to write this plugin as a "die" inside of a destructor is
190 useless.
191 The context is cleared
193 The main context data is cleared allowing the next tool to create a
194 new context. This is important as the next tool very likely has a
195 new line number.
196 $!, $@, $?, and $^E are restored
198 When a Test2 tool is complete it will restore $@, $!, $? and $^E to
199 avoid action at a distance.
200
202 done_testing();
203 Any pending IPC events will be culled.
205 If IPC is turned on, a final culling will take place.
206 Follow-up hooks are run
208 The follow-up hooks are a way to run actions when a hub is
209 complete. This is useful for adding cleanup tasks, or final tests
210 to the end of a test.
211 The final plan event is generated and processed.
213 The final plan event will be produced using the current test count
214 as the number of tests planned.
215 The current hub is finalized.
217 This will mark the hub is complete, and will not allow new events
218 to be processed.
219
221 Test2 has some behaviors it runs in an "END { ... }" block after tests
222 are done running. This end block does some final checks to warn you if
223 something went wrong. This end block also sets the exit value of the
224 script.
225 API Versions are checked.
227 A warning will be produced if Test::Builder is loaded, but has a
228 different version compared to Test2::API. This situation can happen
229 if you downgrade to an older Test-Simple distribution, and is a bad
230 situation.
231 Any remaining context objects are cleaned up.
233 If there are leftover context objects they will need to be cleaned
234 up. A leftover context is never a good thing, and usually requires
235 a warning. A leftover context could also be the result of an
236 exception being thrown which terminates the script, Test2 is fairly
237 good at noticing this and not warning in these cases as the warning
238 would simply be noise.
239 Child processes are sent a 'waiting' event.
241 If IPC is active, a waiting event is sent to all child processes.
242 The script will wait for all child processes and/or threads to
244 complete.
245 This happens only when IPC is loaded, but Test::Builder is not.
246 This behavior is useful, but would break compatibility for legacy
247 tests.
248 The hub stack is cleaned up.
250 All hubs are finalized starting from the top. Leftover hubs are
251 usually a bad thing, so a warning is produced if any are found.
252 The root hub is finalized.
254 This step is a no-op if "done_testing()" was used. If needed this
255 will mark the root hub as finished.
256 Exit callbacks are called.
258 This is a chance for plugins to modify the final exit value of the
259 script.
260 The scripts exit value ($?) is set.
262 If the test encountered any failures this will be set to a non-zero
263 value. If possible this will be set to the number of failures, or
264 255 if the number is larger than 255 (the max value allowed).
265 Broken module diagnostics
267 Test2 is aware of many modules which were broken by Test2's
268 release. At this point the script will check if any known-broken
269 modules were loaded, and warn you if they were.
270 Note: This only happens if there were test failures. No broken
272 module warnings are produced on a success.
273
275 Test2::Manual - Primary index of the manual.
276
278 The source code repository for Test2-Manual can be found at
279 https://github.com/Test-More/Test2-Suite/.
280
282 Chad Granum <exodist@cpan.org>
283
285 Chad Granum <exodist@cpan.org>
286
288 Copyright 2018 Chad Granum <exodist@cpan.org>.
289 This program is free software; you can redistribute it and/or modify it
291 under the same terms as Perl itself.
292 See http://dev.perl.org/licenses/
294perl v5.36.0 2022-07-22Test2::Manual::Anatomy::EndToEnd(3)