Package org.jvnet.hudson.test

Class LoggerRule

java.lang.Object

org.junit.rules.ExternalResource

org.jvnet.hudson.test.LoggerRule

All Implemented Interfaces:

org.junit.rules.TestRule

public class LoggerRule
extends org.junit.rules.ExternalResource

A test rule which allows you to easily enable one or more loggers for the duration of a test. Call record(Class, Level) or another overload for the rule to take effect.

By default messages are merely printed to test output. If you also want to examine them, call capture(int).

To print and/or capture messages during Jenkins startup, you may compose this with a JenkinsRule using a RuleChain; or use as a ClassRule.

Constructor Summary

Constructors

Constructor	Description
LoggerRule()	Initializes the rule, by default not recording anything.

Method Summary

Modifier and Type	Method	Description
protected void	after()
LoggerRule	capture(int maximum)	Initializes log record capture, in addition to merely printing it.
List<String>	getMessages()	Returns a read-only view of current messages.
List<LogRecord>	getRecords()	Obtains all log records collected so far during this test case.
LoggerRule	quiet()	Don't emit logs to the console, only record.
LoggerRule	record(Class<?> clazz, Level level)	Same as record(String, Level) but calls Class.getName() for you first.
LoggerRule	record(String name, Level level)	Same as record(Logger, Level) but calls Logger.getLogger(String) for you first.
LoggerRule	record(Logger logger, Level level)	Start listening to a logger.
static org.hamcrest.Matcher<LoggerRule>	recorded(Level level, org.hamcrest.Matcher<String> message)	Creates a Matcher that matches if the LoggerRule has a LogRecord at the specified Level and with a message matching the specified matcher.
static org.hamcrest.Matcher<LoggerRule>	recorded(Level level, org.hamcrest.Matcher<String> message, org.hamcrest.Matcher<Throwable> thrown)	Creates a Matcher that matches if the LoggerRule has a LogRecord at the specified Level, with a message matching the specified matcher, and with a Throwable matching the specified matcher.
static org.hamcrest.Matcher<LoggerRule>	recorded(org.hamcrest.Matcher<String> message)	Creates a Matcher that matches if the LoggerRule has a LogRecord with a message matching the specified matcher.
static org.hamcrest.Matcher<LoggerRule>	recorded(org.hamcrest.Matcher<String> message, org.hamcrest.Matcher<Throwable> thrown)	Creates a Matcher that matches if the LoggerRule has a LogRecord with a message matching the specified matcher and with a Throwable matching the specified matcher.
LoggerRule	recordPackage(Class<?> clazz, Level level)	Same as record(String, Level) but calls Class.getPackage() and getName() for you first.
String	toString()

Methods inherited from class org.junit.rules.ExternalResource

apply, before

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LoggerRule

public LoggerRule()

Initializes the rule, by default not recording anything.

Method Detail

quiet

public LoggerRule quiet()

Don't emit logs to the console, only record.

toString

public String toString()

Overrides:

toString in class Object

capture

public LoggerRule capture(int maximum)

Initializes log record capture, in addition to merely printing it. This allows you to call getRecords() and/or getMessages() later.

Parameters:

maximum - the maximum number of records to keep (any further will be discarded)

Returns:

this rule, for convenience

record

public LoggerRule record(Logger logger,
                         Level level)

Start listening to a logger. Might be called in a Rule initializer, to apply to all test cases in a suite; or only at the start of selected test cases.

Parameters:

logger - some logger

level - something between Level.CONFIG and Level.ALL; using Level.INFO or above is typically senseless, since Java will by default log everything at such levels anyway; unless you wish to inspect visible getRecords(), or wish to suppress console log output for some logger

Returns:

this rule, for convenience

record

public LoggerRule record(String name,
                         Level level)

Same as record(Logger, Level) but calls Logger.getLogger(String) for you first.

record

public LoggerRule record(Class<?> clazz,
                         Level level)

Same as record(String, Level) but calls Class.getName() for you first.

recordPackage

public LoggerRule recordPackage(Class<?> clazz,
                                Level level)

Same as record(String, Level) but calls Class.getPackage() and getName() for you first.

getRecords

public List<LogRecord> getRecords()

Obtains all log records collected so far during this test case. You must have first called capture(int). If more than the maximum number of records were captured, older ones will have been discarded.

getMessages

public List<String> getMessages()

Returns a read-only view of current messages. Formatter.formatMessage(java.util.logging.LogRecord) applied to getRecords() at the time of logging. However, if the message is null, but there is an exception, Throwable.toString() will be used. Does not include logger names, stack traces, times, etc. (these will appear in the test console anyway).

after

protected void after()

Overrides:

after in class org.junit.rules.ExternalResource

recorded

public static org.hamcrest.Matcher<LoggerRule> recorded(@CheckForNull
                                                        Level level,
                                                        @NonNull
                                                        org.hamcrest.Matcher<String> message,
                                                        @CheckForNull
                                                        org.hamcrest.Matcher<Throwable> thrown)

Creates a Matcher that matches if the LoggerRule has a LogRecord at the specified Level, with a message matching the specified matcher, and with a Throwable matching the specified matcher. You must have first called capture(int).

Parameters:

level - The Level of the LoggerRule to match. Pass null to match any Level.

message - the matcher to match against LogRecord.getMessage()

thrown - the matcher to match against LogRecord.getThrown(). Passing null is equivalent to passing Matchers.anything()

recorded

public static org.hamcrest.Matcher<LoggerRule> recorded(@CheckForNull
                                                        Level level,
                                                        @NonNull
                                                        org.hamcrest.Matcher<String> message)

Creates a Matcher that matches if the LoggerRule has a LogRecord at the specified Level and with a message matching the specified matcher. You must have first called capture(int).

Parameters:

level - The Level of the LoggerRule to match. Pass null to match any Level.

message - The matcher to match against LogRecord.getMessage().

recorded

public static org.hamcrest.Matcher<LoggerRule> recorded(@NonNull
                                                        org.hamcrest.Matcher<String> message,
                                                        @CheckForNull
                                                        org.hamcrest.Matcher<Throwable> thrown)

Creates a Matcher that matches if the LoggerRule has a LogRecord with a message matching the specified matcher and with a Throwable matching the specified matcher. You must have first called capture(int).

Parameters:

message - the matcher to match against LogRecord.getMessage()

thrown - the matcher to match against LogRecord.getThrown(). Passing null is equivalent to passing Matchers.anything()

recorded

public static org.hamcrest.Matcher<LoggerRule> recorded(@NonNull
                                                        org.hamcrest.Matcher<String> message)

Creates a Matcher that matches if the LoggerRule has a LogRecord with a message matching the specified matcher. You must have first called capture(int).

Parameters:

message - the matcher to match against LogRecord.getMessage()