Test2::Util(3perl)

✨ Test2::Util ✨

okay bestie, welcome to Test2::Util 💖 this lil page lives in the Perl Programmers Reference Guide, and it's basically the toolbox that Test2 and all its friends keep in their backpack 🎒

🌸 NAME 🌸

Test2::Util — Tools used by Test2 and friends. that's it, that's the vibe 🫶

---

🦋 DESCRIPTION 🦋

It's a whole collection of tools that Test2 and friends use. A grab-bag, a little utility pouch, a miscellaneous drawer full of things that make testing not a nightmare. periodt 💅

---

👑 EXPORTS 👑

big news: every single export here is optional. nothing just shows up in your namespace uninvited — you have to specify the subs you want to import. consent-based imports, we love to see it 😌✨

• ($success, $error) = try { ... } — runs that codeblock and hands you back whether it succeeded and the error message. the glow-up here is that it protects $@ and $! — they get restored by the time the run ends, untouched. it also temporarily blocks out $SIG{DIE} handlers while it's doing its thing. protective king 👑
• protect { ... } — kinda like try, except it does NOT catch exceptions. no catching, no saving you from the fall 💀 the whole point is guarding $@ and $! from getting messed with. if the run succeeds, both $@ and $! go right back to whatever they were before. if the run fails, $! still gets restored, but $@ will hold the exception that got thrown. so, y'know, it's giving "I saved what I could" 😭
• CAN_FORK — true if this system can do true fork or pseudo-fork. it's capable, bestie 💪
• CAN_REALLY_FORK — true only if the system can really fork. for systems where fork is emulated, this one's gonna be false. real ones only 🙈
• CAN_THREAD — true if this system can use threads. threading ability check ✅
• USE_THREADS — returns true if threads are enabled, false if they're not. straight to the point, no notes 🎀
• get_tid — gives you the id of the current thread when threads are enabled. when they're not? it just returns 0. gotcha, babe 🌈
• my $file = pkg_to_file($package) — takes a package name and turns it into a filename. glow-up: package → path ✨
• $string = ipc_separator() — hands you the IPC separator. right now it's always the string '~'. that's just the way it is, no cap 💅
• $string = gen_uid() — generates a unique id. and no, it is NOT A UUID, don't come for me 🙈 it's typically the process id, the thread id, the time, and an incrementing integer, all joined up with ipc_separator().

these IDs are unique enough for most purposes. for two identical ids to happen, you'd need 2 processes with the same PID generating IDs at the same time with the same current state of the incrementing integer. across multiple machines that's a perfectly reasonable thing to expect to happen — on one machine, it's quite unlikely. so like, chill 😌

but listen, there are ways it can fail to be unique:

• a process generates an id, calls exec, and does it again after the exec, and the whole thing happens in less than a second
• the system's process ids cycle in less than a second, letting 2 different programs that use this generator run with the same PID in under a second

both of these cases are sufficiently unlikely, so we're fine fr fr 🫶 BUT. if you need universally unique ids, or ids that stay unique under those conditions, go look at Data::UUID. different tool, different job 💖

• ($ok, $err) = do_rename($old_name, $new_name) — renames a file. it's a wrapper around rename() that makes things more reliable cross-platform when you're trying to rename files you recently altered 🧚
• ($ok, $err) = do_unlink($filename) — unlinks a file. same deal, it wraps unlink() so it's more reliable cross-platform when you're unlinking files you recently altered 🍓

---

💀 NOTES && CAVEATS 💀

🌸 5.10.0

Perl 5.10.0 has a bug when it's compiled with newer gcc versions. and this bug is mean — it causes a segfault whenever a new thread is launched. 😭 Test2 will try to detect this, and when it does detect it, it'll note that the system is not capable of forking. so don't blame Test2, blame the bug bestie 💅

🎀 Devel::Cover

Devel::Cover does not support threads. period. so CAN_THREAD will return false if Devel::Cover is loaded before the check is first run. order matters, iykyk 👑

---

⭐ SOURCE ⭐

the source code repository for Test2 is right here, bestie:

<https://github.com/Test-More/test-more/>

---

💖 MAINTAINERS 💖

• Chad Granum <exodist@cpan.org>

---

🌈 AUTHORS 🌈

• Chad Granum <exodist@cpan.org>
• Kent Fredric <kentnl@cpan.org>

---

👑 COPYRIGHT 👑

Copyright Chad Granum <exodist@cpan.org>.

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

See <https://dev.perl.org/licenses/>

---

okay that's the whole page, you ate that 🫶 this was perl v5.44.0, dated 2026-10-17, and yes babe, it's Test2::Util(3perl) — go forth and import responsibly 💅✨