1Test2::AsyncSubtest(3)User Contributed Perl DocumentationTest2::AsyncSubtest(3)
2
6 Test2::AsyncSubtest - Object representing an async subtest.
7
9 Regular subtests have a limited scope, they start, events are
10 generated, then they close and send an Test2::Event::Subtest event.
11 This is a problem if you want the subtest to keep receiving events
12 while other events are also being generated. This class implements
13 subtests that stay open until you decide to close them.
14 This is mainly useful for tools that start a subtest in one process and
16 then spawn children. In many cases it is nice to let the parent process
17 continue instead of waiting on the children.
18
20 use Test2::AsyncSubtest;
21 my $ast = Test2::AsyncSubtest->new(name => foo);
23 $ast->run(sub {
25 ok(1, "Event in parent" );
26 });
27 ok(1, "Event outside of subtest");
29 $ast->run_fork(sub {
31 ok(1, "Event in child process");
32 });
33 ...
35 $ast->finish;
37 done_testing;
39
41 my $ast = Test2::AsyncSubtest->new( ... );
42 name => $name (required)
44 Name of the subtest. This construction argument is required.
45 send_to => $hub (optional)
47 Hub to which the final subtest event should be sent. This must be
48 an instance of Test2::Hub or a subclass. If none is specified then
49 the current top hub will be used.
50 trace => $trace (optional)
52 File/Line to which errors should be attributed. This must be an
53 instance of Test2::Util::Trace. If none is specified then the
54 file/line where the constructor was called will be used.
55 hub => $hub (optional)
57 Use this to specify a hub the subtest should use. By default a new
58 hub is generated. This must be an instance of
59 Test2::AsyncSubtest::Hub.
60
62 SIMPLE ACCESSORS
63 $bool = $ast->active
64 True if the subtest is active. The subtest is active if its hub
65 appears in the global hub stack. This is true when "$ast->run(...)"
66 us running.
67 $arrayref = $ast->children
69 Get an arrayref of child processes/threads. Numerical items are
70 PIDs, blessed items are threads instances.
71 $arrayref = $ast->events
73 Get an arrayref of events that have been sent to the subtests hub.
74 $bool = $ast->finished
76 True if finished() has already been called.
77 $hub = $ast->hub
79 The hub created for the subtest.
80 $int = $ast->id
82 Attach/Detach counter. Used internally, not useful to users.
83 $str = $ast->name
85 Name of the subtest.
86 $pid = $ast->pid
88 PID in which the subtest was created.
89 $tid = $ast->tid
91 Thread ID in which the subtest was created.
92 $hub = $ast->send_to
94 Hub to which the final subtest event should be sent.
95 $arrayref = $ast->stack
97 Stack of async subtests at the time this one was created. This is
98 mainly for internal use.
99 $trace = $ast->trace
101 Test2::Util::Trace instance used for error reporting.
102 INTERFACE
104 $ast->attach($id)
105 Attach a subtest in a child/process to the original.
106 Note: "my $id = $ast->cleave" must have been called in the parent
108 process/thread before the child was started, the id it returns must
109 be used in the call to "$ast->attach($id)"
110 $id = $ast->cleave
112 Prepare a slot for a child process/thread to attach. This must be
113 called BEFORE the child process or thread is started. The ID
114 returned is used by attach().
115 This must only be called in the original process/thread.
117 $ctx = $ast->context
119 Get an Test2::API::Context instance that can be used to send events
120 to the context in which the hub was created. This is not a
121 canonical context, you should not call "$ctx->release" on it.
122 $ast->detach
124 Detach from the parent in a child process/thread. This should be
125 called just before the child exits.
126 $ast->finish
128 $ast->finish(%options)
129 Finish the subtest, wait on children, and send the final subtest
130 event.
131 This must only be called in the original process/thread.
133 Note: This calls "$ast->wait".
135 These are the options:
137 collapse => 1
139 This intelligently allows a subtest to be empty.
140 If no events bump the test count then the subtest no final plan
142 will be added. The subtest will not be considered a failure
143 (normally an empty subtest is a failure).
144 If there are no events at all the subtest will be collapsed
146 into an Test2::Event::Ok event.
147 silent => 1
149 This will prevent finish from generating a final
150 Test2::Event::Subtest event. This effectively ends the subtest
151 without it effecting the parent subtest (or top level test).
152 no_plan => 1
154 This will prevent a final plan from being added to the subtest
155 for you when none is directly specified.
156 skip => "reason"
158 This will issue an Test2::Event::Skip instead of a subtest.
159 This will throw an exception if any events have been seen, or
160 if state implies events have occurred.
161 $out = $ast->fork
163 This is a slightly higher level interface to fork. Running it will
164 fork your code in-place just like fork(). It will return a pid in
165 the parent, and an Scope::Guard instance in the child. An exception
166 will be thrown if fork fails.
167 It is recommended that you use "$ast->run_fork(sub { ... })"
169 instead.
170 $bool = $ast->pending
172 True if there are child processes, threads, or subtests that depend
173 on this one.
174 $bool = $ast->ready
176 This is essentially "!$ast->pending".
177 $ast->run(sub { ... })
179 Run the provided codeblock inside the subtest. This will push the
180 subtest hub onto the stack, run the code, then pop the hub off the
181 stack.
182 $pid = $ast->run_fork(sub { ... })
184 Same as "$ast->run()", except that the codeblock is run in a child
185 process.
186 You do not need to directly call wait($pid), that will be done for
188 you when "$ast->wait", or "$ast->finish" are called.
189 my $thr = $ast->run_thread(sub { ... });
191 ** DISCOURAGED ** Threads cause problems. This method remains for
192 anyone who REALLY wants it, but it is no longer supported. Tests
193 for this functionality do not even run unless the AUTHOR_TESTING or
194 T2_DO_THREAD_TESTS env vars are enabled.
195 Same as "$ast->run()", except that the codeblock is run in a child
197 thread.
198 You do not need to directly call "$thr->join", that is done for you
200 when "$ast->wait", or "$ast->finish" are called.
201 $passing = $ast->start
203 Push the subtest hub onto the stack. Returns the current pass/fail
204 status of the subtest.
205 $ast->stop
207 Pop the subtest hub off the stack. Returns the current pass/fail
208 status of the subtest.
209 $ast->wait
211 Wait on all threads/processes that were started using "$ast->fork",
212 "$ast->run_fork", or "$ast->run_thread".
213
215 The source code repository for Test2-AsyncSubtest can be found at
216 https://github.com/Test-More/Test2-Suite/.
217
219 Chad Granum <exodist@cpan.org>
220
222 Chad Granum <exodist@cpan.org>
223
225 Copyright 2018 Chad Granum <exodist7@gmail.com>.
226 This program is free software; you can redistribute it and/or modify it
228 under the same terms as Perl itself.
229 See http://dev.perl.org/licenses/
231perl v5.36.0 2023-03-23 Test2::AsyncSubtest(3)