Test::...ispatch(3pm)

💖 Test::Log::Dispatch(3pm) — the manual page, bestie edition 💖

okay so. you're out here logging stuff and you have NO idea if the right stuff is getting logged?? bestie. that's literally what this module is for. it's Test::Log::Dispatch and it lives in your perl docs, section 3pm, and it is the vibe for "did my code log the thing or not".

---

✨ NAME ✨

Test::Log::Dispatch — test what you are logging 🫶

---

🌸 SYNOPSIS 🌸

use Test::More;
use Test::Log::Dispatch;

my $log = Test::Log::Dispatch->new();

# ...
# call something that logs to $log
# ...

# now test to make sure you logged the right things

$log->contains_ok(qr/good log message/, "good message was logged");
$log->does_not_contain_ok(qr/unexpected log message/, "unexpected message was not logged");
$log->empty_ok("no more logs");

# or

my $msgs = $log->msgs;
cmp_deeply($msgs, ['msg1', 'msg2', 'msg3']);

like. look at that. you log, you check, you move on with your life. periodt. 💅

---

🦋 DESCRIPTION 🦋

Test::Log::Dispatch is a Log::Dispatch object that is lowkey also a spy 👀 — it keeps track of everything logged to it, right there in memory, and hands you convenient tests to run against what got logged. no files, no digging, no "wait where did that message go". it's giving observability but make it cute.

---

🎀 CONSTRUCTOR 🎀

the constructor hands you back a Test::Log::Dispatch object, which inherits from Log::Dispatch and contains a single Log::Dispatch::Array output at 'debug' level. one output, debug level, chillin'. ✨

it requires no parameters. zero. none. but if you do pass any, they get forwarded straight to the Log::Dispatch::Array constructor. for example, you can pass a min_level to override the default 'debug'. slay, customise away. 💖

---

💜 METHODS 💜

quick note before we dive in: the test_name is optional in all the *_ok methods, and a reasonable default will be provided. so you don't even have to name your tests if you're feeling feral. 🙈

• contains_ok ($regex[, $test_name]) — tests that a message in the log buffer matches $regex. and on success?? the message gets removed from the log buffer (but any other matches are left untouched, bestie, we're not greedy). 🔥
• does_not_contain_ok ($regex[, $test_name]) — tests that no message in the log buffer matches $regex. if it ain't there, you're golden. 👑
• empty_ok ([$test_name]) — tests that there is no log buffer left. and on failure, the log buffer is cleared to limit further cascading failures — which is honestly so thoughtful of it, one bad test doesn't have to ruin the whole run. 😭
• contains_only_ok ($regex[, $test_name]) — tests that there is a single message in the log buffer and it matches $regex. on success, the message is removed. one message, one match, one slay. ⭐
• clear () — clears the log buffer. fresh start energy. 🧚
• msgs () — returns the current contents of the log buffer as an array reference, where each element is a hash containing a message and level key. so if you want to cmp_deeply the whole thing yourself, go off. 🌈

---

💀 TO DO 💀

the module itself is manifesting these, not me:

• Allow testing of log levels.

(it's on the list, okay, it's on the list.) 🙈

---

🍓 SEE ALSO 🍓

• Log::Dispatch
• Test::Log4perl

---

👑 AUTHOR 👑

Jonathan Swartz

---

💖 COPYRIGHT & LICENSE 💖

Copyright (C) 2009 Jonathan Swartz, all rights reserved.

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

---

okay that's the whole page bestie, no cap, every single flag and method accounted for 🫶

and for the cute sign-off: this page came to you courtesy of perl v5.32.0, dated 2021-01-09, filed under Test::...ispatch(3pm) — yes the header really do be truncating like that, iconic behaviour honestly. 💅✨