Package org.robolectric.junit.rules

Class ExpectedLogMessagesRule

java.lang.Object
org.robolectric.junit.rules.ExpectedLogMessagesRule
All Implemented Interfaces:
org.junit.rules.TestRule
public final class ExpectedLogMessagesRule
extends Object
implements org.junit.rules.TestRule
Allows tests to assert about the presence of log messages, and turns logged errors that are not explicitly expected into test failures.

Null Expectations

It is permitted to pass null for any expected value or matcher (i.e. for expected tags, messages or throwables) and this cause the expectation to ignore that attribute during matching. For example: 


 // Matches any INFO level log statement with the specified tag.
 logged.expectLogMessage(Log.INFO, "tag", null);
 // Matches any INFO level log statement with the message "expected", regardless of the tag.
 logged.expectLogMessage(Log.INFO, null, "message");
 

 
However in general it is not recommended to use this behaviour, since it can cause tests to
 pass when they should have failed.

 
Matchers Vs Expected Values


 
Using a {code Matcher} which can support substring matching and other non-trivial behaviour
 can be a good way to avoid brittle tests. However there is a  difference between the behaviour of
 methods which accept Hamcrest matchers and those which only accept expected value (e.g. 
 String or Pattern).

 If an expected value is used to match a log statement, then duplicate expectations will be
 removed:

 

 logged.expectLogMessage(Log.INFO, "tag", "exact message");
 // This call has no effect and only 1 log statements is expected.
 logged.expectLogMessage(Log.INFO, "tag", "exact message");
 

 
When using a Matcher in any parameter, the existence of duplicate expectations can no
 longer be determined, so de-duplication does not occur:

 

 logged.expectLogMessage(Log.INFO, "tag", Matchers.equalTo("exact message"));
 // This adds a 2nd expectation, so 2 log statements with the same value must be present.
 logged.expectLogMessage(Log.INFO, "tag", Matchers.equalTo("exact message"));
 

 
This means that you may not be able to trivially convert from using one style of expectation
 to the other. In general it is preferable to match the number of expectations to the number of
 expected log messages (i.e. using the Matcher APIs) but some existing tests may rely on
 the older de-duplication behaviour.

  • Constructor Details

  • Method Details

    • apply

      public org.junit.runners.model.Statement apply​(org.junit.runners.model.Statement base, org.junit.runner.Description description)
      Specified by:
      apply in interface org.junit.rules.TestRule

    • expectLogMessage

      public void expectLogMessage​(int level, String tag, org.hamcrest.Matcher<String> messageMatcher)
      Adds an expected log statement. If this log is not printed during test execution, the test case will fail.

      This will also match any log statement which contains a throwable as well. For verifying the throwable, please see #expectLogMessageWithThrowable(int, String, Matcher, Matcher).

      Do not use this to suppress failures. Use this to test that expected error cases in your code cause log messages to be printed.

      See class level documentation for a note about using Matchers.

    • expectLogMessage

      public void expectLogMessage​(int level, String tag, String message)
      Adds an expected log statement. If this log is not printed during test execution, the test case will fail.

      This will also match any log statement which contains a throwable as well. For verifying the throwable, please see expectLogMessageWithThrowable(int, String, String, Throwable).

      Do not use this to suppress failures. Use this to test that expected error cases in your code cause log messages to be printed.

    • expectLogMessagePattern

      public void expectLogMessagePattern​(int level, String tag, Pattern messagePattern)
      Adds an expected log statement using a regular expression. If this log is not printed during test execution, the test case will fail. When possible, log output should be made determinstic and expectLogMessage(int, String, String) used instead.

      This will also match any log statement which contain a throwable as well. For verifying the throwable, please see expectLogMessagePatternWithThrowableMatcher(int, java.lang.String, java.util.regex.Pattern, org.hamcrest.Matcher<java.lang.Throwable>).

      Do not use this to suppress failures. Use this to test that expected error cases in your code cause log messages to be printed.

    • expectLogMessageWithThrowable

      public void expectLogMessageWithThrowable​(int level, String tag, org.hamcrest.Matcher<String> messagMatcher, org.hamcrest.Matcher<Throwable> throwableMatcher)
      Adds an expected log statement with extra check of Throwable. If this log is not printed during test execution, the test case will fail. Do not use this to suppress failures. Use this to test that expected error cases in your code cause log messages to be printed.

      See class level documentation for a note about using Matchers.

    • expectLogMessageWithThrowable

      public void expectLogMessageWithThrowable​(int level, String tag, String message, Throwable throwable)
      Adds an expected log statement with extra check of Throwable. If this log is not printed during test execution, the test case will fail. Do not use this to suppress failures. Use this to test that expected error cases in your code cause log messages to be printed.

    • expectLogMessagePatternWithThrowableMatcher

      public void expectLogMessagePatternWithThrowableMatcher​(int level, String tag, Pattern messagePattern, org.hamcrest.Matcher<Throwable> throwableMatcher)
      Adds an expected log statement using a regular expression, with an extra check of Matcher. If this log is not printed during test execution, the test case will fail. When possible, log output should be made deterministic and expectLogMessage(int, String, String) used instead.

      See class level documentation for a note about using Matchers.

    • expectLogMessageWithThrowableMatcher

      public void expectLogMessageWithThrowableMatcher​(int level, String tag, String message, org.hamcrest.Matcher<Throwable> throwableMatcher)
      Adds an expected log statement with extra check of Matcher. If this log is not printed during test execution, the test case will fail. Do not use this to suppress failures. Use this to test that expected error cases in your code cause log messages to be printed.

      See class level documentation for a note about using Matchers.

    • expectErrorsForTag

      public void expectErrorsForTag​(String tag)
      Blanket suppress test failures due to errors from a tag. If this tag is not printed at Log.ERROR during test execution, the test case will fail (unless ignoreMissingLoggedTags(boolean) is used).

      Avoid using this method when possible. Prefer to assert on the presence of a specific message using expectLogMessage(int, java.lang.String, org.hamcrest.Matcher<java.lang.String>) in test cases that *intentionally* trigger an error.

    • ignoreMissingLoggedTags

      public void ignoreMissingLoggedTags​(boolean shouldIgnore)
      If set true, tests that call expectErrorsForTag(String) but do not log errors for the given tag will not fail. By default this is false.

      Avoid using this method when possible. Prefer tests that print (or do not print) log messages deterministically.