Test::Fork(3pm)

💖 Test::Fork 💖

okay so bestie, this is the Test::Fork page from the User Contributed Perl Documentation, and it's literally here to help you test code that forks. no cap. 🦋

---

✨ NAME ✨

Test::Fork — test code which forks 🍓

---

🌸 SYNOPSIS 🌸

use Test::More tests => 4;
use Test::Fork;

fork_ok(2, sub{
    pass("Test in the child process");
    pass("Another test in the child process");
});

pass("Test in the parent");

---

👑 DESCRIPTION 👑

⚠️ THIS IS ALPHA CODE! The implementation is unreliable and the interface is subject to change. 💀 like, for real, do not build your whole empire on this yet.

so here's the vibe: every test has a number attached to it, which makes testing code that forks deeply annoying. coordinating the test number between the parent process and the child processes is complicated, it's giving chaos honestly. Test::Fork hands you a function that smooths over all those complications. you're welcome. 💅

🧚 Functions

each function is exported by default. no imports needed, they just show up. iconic.

fork_ok

my $child_pid = fork_ok( $num_tests, sub {
    ...child test code...
});

runs the child test code you gave it in a forked process. it returns the pid of the forked child process, or false if the fork fails. ✨

$num_tests is how many tests live inside your child test code. think of it as a sub-plan, like a plan but smaller and nested. 🎀

fork_ok() is itself a test, so if the fork fails, it will fail. and heads up: the fork_ok() test does not count towards your $num_tests. it's its own thing, main character energy.

# This is three tests.
fork_ok( 2, sub {
    is $foo, $bar;
    ok Something->method;
});

the children are automatically reaped. 🫶 they're taken care of, don't worry about it.

---

🙈 CAVEATS 🙈

okay so this is the part where we get real. 😭

• the failure of tests in a child process cannot be detected by the parent. so the normal end-of-test reporting that Test::Builder does will not notice failed child tests. they just... slip away. 💀
• Test::Fork turns off test numbering to avoid test counter coordination issues. it turns it back on once the children are done running. on, off, on. slay.
• Test::Fork will wait for all your child processes to complete at the end of the parent process. it's not leaving until everybody's home. 🏠

---

🌈 SEE ALSO 🌈

• Test::MultiFork

---

💜 AUTHOR 💜

Michael G Schwern <schwern@pobox.com>

---

🐛 BUGS and FEEDBACK 🐛

please send all bugs and feature requests to bug-Test-Fork at rt.cpan.org, or use the web interface via <http://rt.cpan.org>.

if you use it, please send feedback. I like getting feedback. 🥺 (and honestly? same energy. feedback is the love language.)

---

📜 COPYRIGHT and LICENSE 📜

Copyright 2007-2008 by Michael G Schwern <schwern@pobox.com>.

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

See http://www.perl.com/perl/misc/Artistic.html

---

and that's the whole page, bestie 💖 this one shipped as perl v5.36.0 on 2022-10-13 — go forth, fork responsibly, and remember: the children are automatically reaped, but your test failures in them are lowkey invisible. periodt. 👑✨