1Test::Log::Log4perl(3)User Contributed Perl DocumentationTest::Log::Log4perl(3)
2
6 Test::Log::Log4perl - test log4perl
7
9 # setup l4p
10 use Log::Log4Perl;
11 # do your normal Log::Log4Perl setup here
12 use Test::Log::Log4perl;
13 # get the loggers
15 my $logger = Log::Log4perl->get_logger("Foo::Bar");
16 my $tlogger = Test::Log::Log4perl->get_logger("Foo::Bar");
17 # test l4p
19 Test::Log::Log4perl->start();
20 # declare we're going to log something
22 $tlogger->error("This is a test");
23 # log that something
25 $logger->error("This is a test");
26 # test that those things matched
28 Test::Log::Log4perl->end("Test that that logs okay");
29 # we also have a simplified version:
31 {
32 my $foo = Test::Log::Log4perl->expect(['foo.bar.quux', warn => qr/hello/ ]);
33 # ... do something that should log 'hello'
34 }
35 # $foo goes out of scope; this triggers the test.
36
38 This module can be used to test that you're logging the right thing
39 with Log::Log4perl. It checks that we get what, and only what, we
40 expect logged by your code.
41 The basic process is very simple. Within your test script you get one
43 or more loggers from Test::Log::Log4perl with the "get_logger" method
44 just like you would with Log::Log4perl. You're going to use these
45 loggers to declare what you think the code you're going to test should
46 be logging.
47 # declare a bunch of test loggers
49 my $tlogger = Test::Log::Log4perl->get_logger("Foo::Bar");
50 Then, for each test you want to do you need to start up the module.
52 # start the test
54 Test::Log::Log4perl->start();
55 This diverts all subsequent attempts Log::Log4perl makes to log stuff
57 and records them internally rather than passing them though to the
58 Log4perl appenders as normal.
59 You then need to declare with the loggers we created earlier what we
61 hope Log4perl will be asked to log. This is the same syntax as
62 Test::Log::Log4perl uses, except if you want you can use regular
63 expressions:
64 $tlogger->debug("fish");
66 $tlogger->warn(qr/bar/);
67 You then need to run your code that you're testing.
69 # call some code that hopefully will call the log4perl methods
71 # 'debug' with "fish" and 'warn' with something that contains 'bar'
72 some_code();
73 We finally need to tell Test::Log4Perl that we're done and it should do
75 the comparisons.
76 # start the test
78 Test::Log::Log4perl->end("test name");
79 Methods
81 get_logger($category)
82 Returns a new instance of Test::Log::Log4perl that can be used to
83 log expected messages in the category passed.
84 Test::Log::Log4perl->expect(%start_args, ['dotted.path', 'warn' =>
86 qr(this), 'warn' => qr(that)], ..)
87 Class convenience method. Used like this:
88 { # start local scope
90 my $foo = Test::Log::Log4perl->expect(['foo.bar.quux', warn => qr/hello/ ]);
91 # ... do something that should log 'hello'
92 } # $foo goes out of scope; this triggers the test.
93 start
95 Class method. Start logging. When you call this method it
96 temporarily redirects all logging from the standard logging
97 locations to the internal logging routine until end is called.
98 Takes parameters to change the behavior of this (and only this)
99 test. See below.
100 debug(@what)
102 info(@what)
103 warn(@what)
104 error(@what)
105 fatal(@what)
106 Instance methods. String of things that you're expecting to log,
107 at the level you're expecting them, in what class.
108 end()
110 end($name)
111 Ends the test and compares what we've got with what we expected.
112 Switches logging back from being captured to going to wherever it
113 was originally directed in the config.
114 Ignoring All Logging Messages
116 Sometimes you're going to be testing something that generates a load of
117 spurious log messages that you simply want to ignore without testing
118 their contents, but you don't want to have to reconfigure your log
119 file. The simplest way to do this is to do:
120 use Test::Log::Log4perl;
122 Test::Log::Log4perl->suppress_logging;
123 All logging functions stop working. Do not alter the Logging classes
125 (for example, by changing the config file and use Log4perl's
126 "init_and_watch" functionality) after this call has been made.
127 This function will be effectively a no-op if the environmental variable
129 "NO_SUPPRESS_LOGGING" is set to a true value (so if your code is
130 behaving weirdly you can turn all the logging back on from the command
131 line without changing any of the code)
132 Selectively Ignoring Logging Messages By Priority
134 It's a bad idea to completely ignore all messages. What you probably
135 want to do is ignore some of the trivial messages that you don't care
136 about, and just test that there aren't any unexpected messages of a set
137 priority.
138 You can temporarily ignore any logging messages that are made by
140 passing parameters to the "start" routine
141 # for this test, just ignore DEBUG, INFO, and WARN
143 Test::Log::Log4perl->start( ignore_priority => "warn" );
144 # you can use the levels constants to do the same thing
146 use Log::Log4perl qw(:levels);
147 Test::Log::Log4perl->start( ignore_priority => $WARN );
148 You might want to ignore all logging events at all (this can be used as
150 quick way to not test the actual log messages, but just ignore the
151 output.
152 # for this test, ignore everything
154 Test::Log::Log4perl->start( ignore_priority => "everything" );
155 # contary to readability, the same thing (try not to write this)
157 use Log::Log4perl qw(:levels);
158 Test::Log::Log4perl->start( ignore_priority => $OFF );
159 Or you might want to not ignore anything (which is the default, unless
161 you've played with the method calls mentioned below:)
162 # for this test, ignore nothing
164 Test::Log::Log4perl->start( ignore_priority => "nothing" );
165 # contary to readability, the same thing (try not to write this)
167 use Log::Log4perl qw(:levels);
168 Test::Log::Log4perl->start( ignore_priority => $ALL );
169 You can also permanently effect what things are ignored with the
171 "ignore_priority" method call. This persists between tests and isn't
172 automatically reset after each call to "start".
173 # ignore DEBUG, INFO and WARN for all future tests
175 Test::Log::Log4perl->ignore_priority("warn");
176 # you can use the levels constants to do the same thing
178 use Log::Log4perl qw(:levels);
179 Test::Log::Log4perl->ignore_priority($WARN);
180 # ignore everything (no log messages will be logged)
182 Test::Log::Log4perl->ignore_priority("everything");
183 # ignore nothing (messages will be logged reguardless of priority)
185 Test::Log::Log4perl->ignore_priority("nothing");
186 Obviously, you may temporarily override whatever permanent.
188
190 Logging methods don't return the number of appenders they've written to
191 (or rather, they do, as it's always zero.)
192 Changing the config file (if you're watching it) while this is testing
194 / suppressing everything will probably break everything. As will
195 creating new appenders, etc...
196
198 Chia-liang Kao <clkao@clkao.org>
199 Mark Fowler <mark@twoshortplanks.com>
200
202 Copyright 2010 Chia-liang Kao all rights reserved.
203 Copyright 2005 Fotango Ltd all rights reserved.
204 Licensed under the same terms as Perl itself.
206perl v5.30.0 2019-07-26 Test::Log::Log4perl(3)