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 Details

    • LoggerRule

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

  • Method Details

    • 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()