1Test2::AsyncSubtest(3)User Contributed Perl DocumentationTest2::AsyncSubtest(3)
2
3
4

NAME

6       Test2::AsyncSubtest - Object representing an async subtest.
7

DESCRIPTION

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
15       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

SYNOPSIS

20           use Test2::AsyncSubtest;
21
22           my $ast = Test2::AsyncSubtest->new(name => foo);
23
24           $ast->run(sub {
25               ok(1, "Event in parent" );
26           });
27
28           ok(1, "Event outside of subtest");
29
30           $ast->run_fork(sub {
31               ok(1, "Event in child process");
32           });
33
34           ...
35
36           $ast->finish;
37
38           done_testing;
39

CONSTRUCTION

41           my $ast = Test2::AsyncSubtest->new( ... );
42
43       name => $name (required)
44           Name of the subtest. This construction argument is required.
45
46       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
51       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
56       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

METHODS

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
68       $arrayref = $ast->children
69           Get an arrayref of child processes/threads. Numerical items are
70           PIDs, blessed items are threads instances.
71
72       $arrayref = $ast->events
73           Get an arrayref of events that have been sent to the subtests hub.
74
75       $bool = $ast->finished
76           True if "finished()" has already been called.
77
78       $hub = $ast->hub
79           The hub created for the subtest.
80
81       $int = $ast->id
82           Attach/Detach counter. Used internally, not useful to users.
83
84       $str = $ast->name
85           Name of the subtest.
86
87       $pid = $ast->pid
88           PID in which the subtest was created.
89
90       $tid = $ast->tid
91           Thread ID in which the subtest was created.
92
93       $hub = $ast->send_to
94           Hub to which the final subtest event should be sent.
95
96       $arrayref = $ast->stack
97           Stack of async subtests at the time this one was created. This is
98           mainly for internal use.
99
100       $trace = $ast->trace
101           Test2::Util::Trace instance used for error reporting.
102
103   INTERFACE
104       $ast->attach($id)
105           Attach a subtest in a child/process to the original.
106
107           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
111       $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
116           This must only be called in the original process/thread.
117
118       $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
123       $ast->detach
124           Detach from the parent in a child process/thread. This should be
125           called just before the child exits.
126
127       $ast->finish
128       $ast->finish(%options)
129           Finish the subtest, wait on children, and send the final subtest
130           event.
131
132           This must only be called in the original process/thread.
133
134           Note: This calls "$ast->wait".
135
136           These are the options:
137
138           collapse => 1
139               This intelligently allows a subtest to be empty.
140
141               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
145               If there are no events at all the subtest will be collapsed
146               into an Test2::Event::Ok event.
147
148           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
153           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
157           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
162       $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
168           It is recommended that you use "$ast->run_fork(sub { ... })"
169           instead.
170
171       $bool = $ast->pending
172           True if there are child processes, threads, or subtests that depend
173           on this one.
174
175       $bool = $ast->ready
176           This is essentially "!$ast->pending".
177
178       $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
183       $pid = $ast->run_fork(sub { ... })
184           Same as "$ast->run()", except that the codeblock is run in a child
185           process.
186
187           You do not need to directly call "wait($pid)", that will be done
188           for you when "$ast->wait", or "$ast->finish" are called.
189
190       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
196           Same as "$ast->run()", except that the codeblock is run in a child
197           thread.
198
199           You do not need to directly call "$thr->join", that is done for you
200           when "$ast->wait", or "$ast->finish" are called.
201
202       $passing = $ast->start
203           Push the subtest hub onto the stack. Returns the current pass/fail
204           status of the subtest.
205
206       $ast->stop
207           Pop the subtest hub off the stack. Returns the current pass/fail
208           status of the subtest.
209
210       $ast->wait
211           Wait on all threads/processes that were started using "$ast->fork",
212           "$ast->run_fork", or "$ast->run_thread".
213

SOURCE

215       The source code repository for Test2-AsyncSubtest can be found at
216       https://github.com/Test-More/Test2-Suite/.
217

MAINTAINERS

219       Chad Granum <exodist@cpan.org>
220

AUTHORS

222       Chad Granum <exodist@cpan.org>
223
225       Copyright 2018 Chad Granum <exodist7@gmail.com>.
226
227       This program is free software; you can redistribute it and/or modify it
228       under the same terms as Perl itself.
229
230       See http://dev.perl.org/licenses/
231
232
233
234perl v5.34.0                      2022-03-08            Test2::AsyncSubtest(3)
Impressum