1Test::Log::Log4perl(3)User Contributed Perl DocumentationTest::Log::Log4perl(3)
2
3
4

NAME

6       Test::Log::Log4perl - test log4perl
7

SYNOPSIS

9         # setup l4p
10         use Log::Log4Perl;
11         # do your normal Log::Log4Perl setup here
12         use Test::Log::Log4perl;
13
14         # get the loggers
15         my $logger  = Log::Log4perl->get_logger("Foo::Bar");
16         my $tlogger = Test::Log::Log4perl->get_logger("Foo::Bar");
17
18         # test l4p
19         Test::Log::Log4perl->start();
20
21         # declare we're going to log something
22         $tlogger->error("This is a test");
23
24         # log that something
25         $logger->error("This is a test");
26
27         # test that those things matched
28         Test::Log::Log4perl->end("Test that that logs okay");
29
30         # 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

DESCRIPTION

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
42       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
48         # declare a bunch of test loggers
49         my $tlogger = Test::Log::Log4perl->get_logger("Foo::Bar");
50
51       Then, for each test you want to do you need to start up the module.
52
53         # start the test
54         Test::Log::Log4perl->start();
55
56       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
60       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
65         $tlogger->debug("fish");
66         $tlogger->warn(qr/bar/);
67
68       You then need to run your code that you're testing.
69
70         # 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
74       We finally need to tell Test::Log4Perl that we're done and it should do
75       the comparisons.
76
77         # start the test
78         Test::Log::Log4perl->end("test name");
79
80   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
85       Test::Log::Log4perl->expect(%start_args, ['dotted.path', 'warn' =>
86       qr(this), 'warn' => qr(that)], ..)
87           Class convenience method. Used like this:
88
89             { # 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
94       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
101       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
109       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
115   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
121         use Test::Log::Log4perl;
122         Test::Log::Log4perl->suppress_logging;
123
124       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
128       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
133   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
139       You can temporarily ignore any logging messages that are made by
140       passing parameters to the "start" routine
141
142         # for this test, just ignore DEBUG, INFO, and WARN
143         Test::Log::Log4perl->start( ignore_priority => "warn" );
144
145         # 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
149       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
153         # for this test, ignore everything
154         Test::Log::Log4perl->start( ignore_priority => "everything" );
155
156         # 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
160       Or you might want to not ignore anything (which is the default, unless
161       you've played with the method calls mentioned below:)
162
163         # for this test, ignore nothing
164         Test::Log::Log4perl->start( ignore_priority => "nothing" );
165
166         # 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
170       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
174         # ignore DEBUG, INFO and WARN for all future tests
175         Test::Log::Log4perl->ignore_priority("warn");
176
177         # 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
181         # ignore everything (no log messages will be logged)
182         Test::Log::Log4perl->ignore_priority("everything");
183
184         # ignore nothing (messages will be logged reguardless of priority)
185         Test::Log::Log4perl->ignore_priority("nothing");
186
187       Obviously, you may temporarily override whatever permanent.
188

BUGS

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
193       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

AUTHOR

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
205         Licensed under the same terms as Perl itself.
206
207
208
209perl v5.30.1                      2020-01-30            Test::Log::Log4perl(3)
Impressum