1Test2::Manual::Anatomy:U:sEenrdTCooEnntdr(i3b)uted PerlTDeosctu2m:e:nMtaantuiaoln::Anatomy::EndToEnd(3)
2
3
4

NAME

6       Test2::Manual::EndToEnd - Overview of Test2 from load to finish.
7

DESCRIPTION

9       This is a high level overview of everything from loading Test2 through
10       the end of a test script.
11

WHAT HAPPENS WHEN I LOAD THE API?

13           use Test2::API qw/context/;
14
15       A singleton instance of Test2::API::Instance is created.
16           You have no access to this, it is an implementation detail.
17
18       Several API functions are defined that use the singleton instance.
19           You can import these functions, or use them directly.
20
21       Then what?
22           It waits...
23
24           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
30           See "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?" for more information.
31

WHAT HAPPENS WHEN I USE A TOOL?

33       This section covers the basic workflow all tools such as "ok()" must
34       follow.
35
36           sub ok($$) {
37               my ($bool, $name) = @_;
38
39               my $ctx = context();
40
41               my $event = $ctx->send_event('Ok', pass => $bool, name => $name);
42
43               ...
44
45               $ctx->release;
46               return $bool;
47           }
48
49           ok(1, "1 is true");
50
51       A tool function is run.
52               ok(1, "1 is true");
53
54       The tool acquires a context object.
55               my $ctx = context();
56
57           See "WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?" for more information.
58
59       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
62               my $event = $ctx->send_event('Ok', pass => $bool, name => $name);
63
64       When done the tool MUST release the context.
65           See "WHAT HAPPENS WHEN I RELEASE A CONTEXT?" for more information.
66
67               $ctx->release();
68
69       The tool returns.
70               return $bool;
71

WHAT HAPPENS WHEN I ACQUIRE A CONTEXT?

73           my $ctx = context();
74
75       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
79       $!, $@, $? 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
85       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
92       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
97       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
102       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
107       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
116       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
120       Context init hooks fire (if no existing context was found)
121           If a new context was created, context-creation hooks will fire.
122
123       $!, $@, $?, 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
129       The context is returned.
130           You have a shiney new context object, or a clone of the existing
131           context.
132

WHAT HAPPENS WHEN I SEND AN EVENT?

134           my $event = $ctx->send_event('Ok', pass => $bool, name => $name);
135
136       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
144               my $event = $ctx->send_event('+Fully::Qualified::Event', pass => $bool, name => $name);
145
146       A new instance of Test2::Event::Ok is created.
147           The event object is instantiated using the provided parameters.
148
149       The event object is sent to the hub.
150           The hub takes over from here.
151
152       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
156       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
162       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
166       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

WHAT HAPPENS WHEN I RELEASE A CONTEXT?

171           $ctx->release;
172
173       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
177       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
183       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
192       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
197       $!, $@, $?, and $^E are restored
198           When a Test2 tool is complete it will restore $@, $!, $? and $^E to
199           avoid action at a distance.
200

WHAT HAPPENS WHEN I USE done_testing()?

202           done_testing();
203
204       Any pending IPC events will be culled.
205           If IPC is turned on, a final culling will take place.
206
207       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
212       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
216       The current hub is finalized.
217           This will mark the hub is complete, and will not allow new events
218           to be processed.
219

WHAT HAPPENS WHEN A TEST SCRIPT IS DONE?

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
226       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
232       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
240       Child processes are sent a 'waiting' event.
241           If IPC is active, a waiting event is sent to all child processes.
242
243       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
249       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
253       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
257       Exit callbacks are called.
258           This is a chance for plugins to modify the final exit value of the
259           script.
260
261       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
266       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
271           Note: This only happens if there were test failures. No broken
272           module warnings are produced on a success.
273

SEE ALSO

275       Test2::Manual - Primary index of the manual.
276

SOURCE

278       The source code repository for Test2-Manual can be found at
279       https://github.com/Test-More/Test2-Suite/.
280

MAINTAINERS

282       Chad Granum <exodist@cpan.org>
283

AUTHORS

285       Chad Granum <exodist@cpan.org>
286
288       Copyright 2018 Chad Granum <exodist@cpan.org>.
289
290       This program is free software; you can redistribute it and/or modify it
291       under the same terms as Perl itself.
292
293       See http://dev.perl.org/licenses/
294
295
296
297perl v5.32.0                      2020-12-16Test2::Manual::Anatomy::EndToEnd(3)
Impressum