Package org.jvnet.hudson.test

Class LogRecorder

java.lang.Object

org.jvnet.hudson.test.LogRecorder

All Implemented Interfaces:

AutoCloseable

public class LogRecorder
extends Object
implements AutoCloseable

A test utility 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 recording to take effect.

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

See the following example:

 try (LogRecorder recorder = new LogRecorder().record("Foo", Level.INFO).capture(100)) {
     LOGGER.log(Level.INFO, "Log Message");
     assertThat(recorder, LogRecorder.recorded(equalTo("Log Message")));
 }
 

Constructor Summary

Constructors

Constructor	Description
LogRecorder()	Initializes the recorder, by default not recording anything.

Method Summary

Modifier and Type	Method	Description
LogRecorder	capture(int maximum)	Initializes log record capture, in addition to merely printing it.
void	close()
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.
LogRecorder	quiet()	Don't emit logs to the console, only record.
LogRecorder	record(Class<?> clazz, Level level)	Same as record(String, Level) but calls Class.getName() for you first.
LogRecorder	record(String name, Level level)	Same as record(Logger, Level) but calls Logger.getLogger(String) for you first.
LogRecorder	record(Logger logger, Level level)	Start listening to a logger.
static org.hamcrest.Matcher<LogRecorder>	recorded(Level level, org.hamcrest.Matcher<String> message)	Creates a Matcher that matches if the LogRecorder has a LogRecord at the specified Level and with a message matching the specified matcher.
static org.hamcrest.Matcher<LogRecorder>	recorded(Level level, org.hamcrest.Matcher<String> message, org.hamcrest.Matcher<Throwable> thrown)	Creates a Matcher that matches if the LogRecorder 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<LogRecorder>	recorded(org.hamcrest.Matcher<String> message)	Creates a Matcher that matches if the LogRecorder has a LogRecord with a message matching the specified matcher.
static org.hamcrest.Matcher<LogRecorder>	recorded(org.hamcrest.Matcher<String> message, org.hamcrest.Matcher<Throwable> thrown)	Creates a Matcher that matches if the LogRecorder has a LogRecord with a message matching the specified matcher and with a Throwable matching the specified matcher.
LogRecorder	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 java.lang.Object

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

Constructor Details

LogRecorder

public LogRecorder()

Initializes the recorder, by default not recording anything.

Method Details

quiet

public LogRecorder quiet()

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

toString

public String toString()

Overrides:

toString in class Object

capture

public LogRecorder 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 recorder, for convenience

record

public LogRecorder record(Logger logger,
 Level level)

Start listening to a logger.

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 recorder, for convenience

record

public LogRecorder record(String name,
 Level level)

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

record

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

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

recordPackage

public LogRecorder 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).

close

public void close()

Specified by:

close in interface AutoCloseable

recorded

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

Creates a Matcher that matches if the LogRecorder 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 LogRecorder 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<LogRecorder> recorded(@CheckForNull
 Level level,
 @NonNull
 org.hamcrest.Matcher<String> message)

Creates a Matcher that matches if the LogRecorder 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 LogRecorder to match. Pass null to match any Level.

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

recorded

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

Creates a Matcher that matches if the LogRecorder 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<LogRecorder> recorded(@NonNull
 org.hamcrest.Matcher<String> message)

Creates a Matcher that matches if the LogRecorder 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()