Test::...og4perl(3pm)

💅 test log4perl, but make it a whole vibe 💅

hi bestie 🫶 you've landed on the manual page for Test::...og4perl(3pm) — and yes, the title really is chopped off like that, that's canon, i don't make the rules 🙈. The module living inside it is Test::Log::Log4perl, and it's here to help you test your Log::Log4perl logging. Let's get into it 💖

---

🌸 NAME 🌸

Test::Log::Log4perl — test log4perl. that's the name. short, sweet, iconic 👑

---

✨ SYNOPSIS ✨

okay so here's the whole flow, copy-paste ready:

# setup l4p
use Log::Log4Perl;
# do your normal Log::Log4Perl setup here
use Test::Log::Log4perl;

# get the loggers
my $logger  = Log::Log4perl->get_logger("Foo::Bar");
my $tlogger = Test::Log::Log4perl->get_logger("Foo::Bar");

# test l4p
Test::Log::Log4perl->start();

# declare we're going to log something
$tlogger->error("This is a test");

# log that something
$logger->error("This is a test");

# test that those things matched
Test::Log::Log4perl->end("Test that that logs okay");

# we also have a simplified version:
{
  my $foo = Test::Log::Log4perl->expect(['foo.bar.quux', warn => qr/hello/ ]);
  # ... do something that should log 'hello'
}
# $foo goes out of scope; this triggers the test.

---

🦋 DESCRIPTION 🦋

so the whole point of this module is: you want to test that you're logging the right thing with Log::Log4perl. It checks that we get what — and only what — we expect your code to log. no extra, no missing. vibe check passed or failed, nothing in between ✨

The basic process is genuinely simple, fr fr. Inside your test script you grab one or more loggers from Test::Log::Log4perl with the get_logger method, exactly like you would with Log::Log4perl. Those loggers are where you declare what you think the code you're about to test should be logging.

# declare a bunch of test loggers
my $tlogger = Test::Log::Log4perl->get_logger("Foo::Bar");

Then, for every test you wanna run, you start the module up.

# start the test
Test::Log::Log4perl->start();

This is the glow-up moment: it diverts all subsequent attempts Log::Log4perl makes to log stuff, and records them internally instead of passing them through to the Log4perl appenders like normal. it's giving interception 💅

Then you declare, using the loggers we made earlier, what you hope Log4perl is gonna be asked to log. Same syntax as Test::Log::Log4perl uses — except if you want, you can throw regular expressions in there too 👑

$tlogger->debug("fish");
$tlogger->warn(qr/bar/);

Then you run the code you're testing, obviously.

# call some code that hopefully will call the log4perl methods
# 'debug' with "fish" and 'warn' with something that contains 'bar'
some_code();

And finally you tell Test::Log::Log4perl that you're done and it should do the comparisons. the moment of truth 😭

# start the test
Test::Log::Log4perl->end("test name");

🎀 Methods 🎀

• get_logger($category) — hands you a brand new instance of Test::Log::Log4perl that you can use to log expected messages in the category you passed in. slay.
• Test::Log::Log4perl->expect(%start_args, ['dotted.path', 'warn' => qr(this), 'warn' => qr(that)], ..) — class convenience method. you use it like this:

{ # start local scope
  my $foo = Test::Log::Log4perl->expect(['foo.bar.quux', warn => qr/hello/ ]);
  # ... do something that should log 'hello'
} # $foo goes out of scope; this triggers the test.

• start — class method. Start logging. When you call it, it temporarily redirects all logging from the standard logging locations over to the internal logging routine, and it stays like that until end gets called. It takes parameters that change the behavior of this test (and only this test). more on that below 👇
• debug(@what)
• info(@what)
• warn(@what)
• error(@what)
• fatal(@what) — instance methods. String of things that you're expecting to log, at the level you're expecting them, in what class.
• end()
• end($name) — Ends the test and compares what we've got against what we expected. Also switches logging back from being captured to going wherever it was originally directed in the config. bye capture mode, hello normalcy 🌈

---

🙈 Ignoring All Logging Messages 🙈

Sometimes you're testing something that generates a whole load of spurious log messages that you just want to ignore without testing their contents — and you do not want to have to go reconfigure your log file. The simplest way to do it is:

use Test::Log::Log4perl;
Test::Log::Log4perl->suppress_logging;

All logging functions stop working. and this is important bestie, listen: Do not alter the Logging classes (for example, by changing the config file and using Log4perl's init_and_watch functionality) after this call has been made. just... don't. 🙅

This function will be effectively a no-op if the environmental variable NO_SUPPRESS_LOGGING is set to a true value (so if your code is behaving weirdly you can turn all the logging back on from the command line without changing any of the code). lowkey the emergency exit door 🚪

---

💜 Selectively Ignoring Logging Messages By Priority 💜

Completely ignoring all messages is a bad idea, ngl. What you probably want is to ignore some of the trivial messages you don't care about, and then just test that there aren't any unexpected messages of a set priority.

You can temporarily ignore any logging messages that are made by passing parameters to the start routine:

# for this test, just ignore DEBUG, INFO, and WARN
Test::Log::Log4perl->start( ignore_priority => "warn" );

# you can use the levels constants to do the same thing
use Log::Log4perl qw(:levels);
Test::Log::Log4perl->start( ignore_priority => $WARN );

You might want to ignore all logging events at all (this can be used as a quick way to not test the actual log messages, but just ignore the output):

# for this test, ignore everything
Test::Log::Log4perl->start( ignore_priority => "everything" );

# contary to readability, the same thing (try not to write this)
use Log::Log4perl qw(:levels);
Test::Log::Log4perl->start( ignore_priority => $OFF );

Or you might want to not ignore anything (which is the default, unless you've played with the method calls mentioned below):

# for this test, ignore nothing
Test::Log::Log4perl->start( ignore_priority => "nothing" );

# contary to readability, the same thing (try not to write this)
use Log::Log4perl qw(:levels);
Test::Log::Log4perl->start( ignore_priority => $ALL );

You can also permanently affect what things are ignored with the ignore_priority method call. This persists between tests and isn't automatically reset after each call to start. so it's the main character, it stays ✨

# ignore DEBUG, INFO and WARN for all future tests
Test::Log::Log4perl->ignore_priority("warn");

# you can use the levels constants to do the same thing
use Log::Log4perl qw(:levels);
Test::Log::Log4perl->ignore_priority($WARN);

# ignore everything (no log messages will be logged)
Test::Log::Log4perl->ignore_priority("everything");

# ignore nothing (messages will be logged reguardless of priority)
Test::Log::Log4perl->ignore_priority("nothing");

Obviously, you may temporarily override whatever permanent. 💅

---

💀 BUGS 💀

• Logging methods don't return the number of appenders they've written to (or rather, they do, as it's always zero.) yeah. it's always zero. 💀
• Changing the config file (if you're watching it) while this is testing / suppressing everything will probably break everything. As will creating new appenders, etc... proceed with caution bestie, this one's giving chaos 😭

---

👑 AUTHOR 👑

Chia-liang Kao <clkao@clkao.org>
Mark Fowler <mark@twoshortplanks.com>

---

🌈 COPYRIGHT 🌈

Copyright 2010 Chia-liang Kao all rights reserved.
Copyright 2005 Fotango Ltd all rights reserved.

Licensed under the same terms as Perl itself.

---

and that's the whole page, bestie 🫶 this was Test::...og4perl(3pm), rendered for you by perl v5.36.0 on 2022-12-08 — go forth and test your logs, you absolute icon 💖✨🎀