TEST2::ASYNCSUBTEST(3perl)

📦
version 5.44.0 · 8 versions
, in arch rolling

💖 Test2::AsyncSubtest — the perl manual page, bestie edition 🦋

okay so you're reading the Test2::AsyncSubtest page from the Perl Programmers Reference Guide. It's giving async subtest energy, and honestly? iconic. Let's go. ✨

🌸 NAME 🌸

Test2::AsyncSubtest — the object that represents an async subtest. that's it, that's the whole vibe. 💅

✨ DESCRIPTION ✨

so like, regular subtests? they have a limited scope. they start, events get generated, then they slam shut and yeet out a Test2::Event::Subtest event. lowkey a problem if you want your subtest to keep receiving events while OTHER events are also being generated, right? 🙈

this class implements subtests that stay open until you decide to close them. main character energy, honestly.

this is mainly useful for tools that start a subtest in one process and then spawn children. in many cases it is nice to let the parent process continue instead of waiting on the children. no cap. 🧚

💜 SYNOPSIS 💜

use Test2::AsyncSubtest;

my $ast = Test2::AsyncSubtest->new(name => foo);

$ast->run(sub {
    ok(1, "Event in parent" );
});

ok(1, "Event outside of subtest");

$ast->run_fork(sub {
    ok(1, "Event in child process");
});

...

$ast->finish;

done_testing;

🎀 CONSTRUCTION 🎀

my $ast = Test2::AsyncSubtest->new( ... );
  • name => $name (required!!) — name of the subtest. this construction argument is required, fr fr, you cannot skip it.
  • send_to => $hub (optional) — the hub to which the final subtest event should be sent. it has to be an instance of Test2::Hub or a subclass of it. if you don't specify one, the current top hub gets used. 👑
  • trace => $trace (optional) — the file/line that errors should be blamed on. must be an instance of Test2::Util::Trace. if none is specified, the file/line where the constructor was called is used. so it snitches on exactly where you called it, periodt. 🫶
  • hub => $hub (optional) — use this to specify a hub the subtest should use. by default a new hub is generated for you. this must be an instance of Test2::AsyncSubtest::Hub.

🔥 METHODS 🔥

🌈 SIMPLE ACCESSORS 🌈

  • $bool = $ast->active — true if the subtest is active. and it's active if its hub appears in the global hub stack. this is true when $ast->run(...) us running. yes, the original really says "us running", i'm just the messenger bestie 😭
  • $arrayref = $ast->children — get an arrayref of child processes/threads. numerical items are PIDs, blessed items are threads instances.
  • $arrayref = $ast->events — get an arrayref of events that have been sent to the subtests hub.
  • $bool = $ast->finished — true if finished() has already been called. been there, done that, closed that.
  • $hub = $ast->hub — the hub created for the subtest.
  • $int = $ast->id — attach/detach counter. used internally, not useful to users. like, stay out of it 💅
  • $str = $ast->name — name of the subtest.
  • $pid = $ast->pid — PID in which the subtest was created.
  • $tid = $ast->tid — thread ID in which the subtest was created.
  • $hub = $ast->send_to — the hub to which the final subtest event should be sent.
  • $arrayref = $ast->stack — stack of async subtests at the time this one was created. mainly for internal use, so don't get too nosy 👀
  • $trace = $ast->trace — the Test2::Util::Trace instance used for error reporting.

🦋 INTERFACE 🦋

  • $ast->attach($id) — attach a subtest in a child/process to the original.
Note: my $id = $ast->cleave must have been called in the parent process/thread BEFORE the child was started, and the id it returns must be used in the call to $ast->attach($id)
  • $id = $ast->cleave — prepare a slot for a child process/thread to attach. this must be called BEFORE the child process or thread is started. the ID returned gets used by attach().
this must only be called in the original process/thread. no exceptions bestie.
  • $ctx = $ast->context — get a Test2::API::Context instance that can be used to send events to the context in which the hub was created. this is not a canonical context, so you should NOT call $ctx->release on it. don't do it. i'm serious. 😤
  • $ast->detach — detach from the parent in a child process/thread. this should be called just before the child exits. say your goodbyes 🫡
  • $ast->finish — finish the subtest, wait on children, and send the final subtest event.
  • $ast->finish(%options) — same thing but with options, and these are they:
This must only be called in the original process/thread.
Note: This calls $ast->wait.

the options, bestie, are:

  • collapse => 1 — this intelligently allows a subtest to be empty. if no events bump the test count, then the subtest no final plan will be added, and the subtest will not be considered a failure (normally an empty subtest is a failure, wild right?). if there are no events at all, the subtest gets collapsed into a Test2::Event::Ok event. slay 💖
  • silent => 1 — this prevents finish from generating a final Test2::Event::Subtest event. this effectively ends the subtest without it affecting the parent subtest (or top level test). quiet quitting, but for tests.
  • no_plan => 1 — this prevents a final plan from being added to the subtest for you when none is directly specified.
  • skip => "reason" — this issues a Test2::Event::Skip instead of a subtest. it will throw an exception if any events have been seen, or if state implies events have occurred. so like, don't be sneaky.
  • $out = $ast->fork — this is a slightly higher level interface to fork. running it forks your code in-place just like fork(). it returns a pid in the parent, and a Test2::Util::Guard instance in the child. an exception gets thrown if fork fails.
it is recommended that you use $ast->run_fork(sub { ... }) instead.
  • $bool = $ast->pending — true if there are child processes, threads, or subtests that depend on this one. so needy 💀
  • $bool = $ast->ready — this is essentially !$ast->pending.
  • $ast->run(sub { ... }) — run the provided codeblock inside the subtest. this pushes the subtest hub onto the stack, runs the code, then pops the hub off the stack. push, pop, done. ✨
  • $pid = $ast->run_fork(sub { ... }) — same as $ast->run(), except the codeblock runs in a child process. you do not need to directly call wait($pid) — that gets done for you when $ast->wait or $ast->finish are called. we handle it, bestie 🫶
  • my $thr = $ast->run_thread(sub { ... }); — DISCOURAGED. threads cause problems, like genuinely. this method remains for anyone who REALLY wants it, but it is no longer supported. tests for this functionality do not even run unless the AUTHOR_TESTING or T2_DO_THREAD_TESTS env vars are enabled.

same as $ast->run(), except the codeblock runs in a child thread.

you do not need to directly call $thr->join — that is done for you when $ast->wait or $ast->finish are called.

  • $passing = $ast->start — push the subtest hub onto the stack. returns the current pass/fail status of the subtest.
  • $ast->stop — pop the subtest hub off the stack. returns the current pass/fail status of the subtest.
  • $ast->wait — wait on all threads/processes that were started using $ast->fork, $ast->run_fork, or $ast->run_thread. sit down and wait, babe 🍓

📚 SOURCE 📚

the source code repository for Test2-AsyncSubtest can be found at https://github.com/Test-More/test-more/.

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

🌟 AUTHORS 🌟

Chad Granum <exodist@cpan.org>

Copyright Chad Granum <exodist7@gmail.com>.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

see http://dev.perl.org/licenses/

and that's the whole page babes — this was perl v5.44.0, dated 2026-10-17, Test2::AsyncSubtest(3perl). go forth and async your subtests responsibly. mwah 💋✨🎀

📦 where this page comes from