Package com.google.common.truth

Class ExpectFailure

java.lang.Object
com.google.common.truth.ExpectFailure
All Implemented Interfaces:
Platform.JUnitTestRule
public final class ExpectFailure extends Object implements Platform.JUnitTestRule
A utility for testing that assertions against a custom Subject fail when they should, plus a utility to assert about parts of the resulting failure messages.

Usage: 


   AssertionError failure =
       expectFailure(whenTesting -> whenTesting.that(cancelButton).isVisible());
   assertThat(failure).factKeys().containsExactly("expected to be visible");

 ...

 private static AssertionError expectFailure(
     ExpectFailure.SimpleSubjectBuilderCallback<UiElementSubject, UiElement> assertionCallback) {
   return ExpectFailure.expectFailureAbout(uiElements(), assertionCallback);
 }
Or, if you can't use lambdas: 
 @Rule public final ExpectFailure expectFailure = new ExpectFailure();

 ...

     expectFailure.whenTesting().about(uiElements()).that(cancelButton).isVisible();
     assertThat(failure).factKeys().containsExactly("expected to be visible");

ExpectFailure is similar to JUnit's assertThrows (JUnit 4, JUnit 5). We recommend it over assertThrows when you're testing a Truth subject because it also checks that the assertion you're testing uses the supplied FailureStrategy and calls FailureStrategy.fail(java.lang.AssertionError) only once.

  • Field Details

    • strategy

      private final FailureStrategy strategy

    • inRuleContext

      private boolean inRuleContext

    • failureExpected

      private boolean failureExpected

    • failure

      private AssertionError failure

  • Constructor Details

    • ExpectFailure

      public ExpectFailure()
      Creates a new instance for use as a @Rule. See the class documentation for details, and consider using the lambda version instead.

  • Method Details

    • whenTesting

      public StandardSubjectBuilder whenTesting()
      Returns a test verb that expects the chained assertion to fail, and makes the failure available via getFailure().

      An instance of ExpectFailure supports only one whenTesting call per test method. The static expectFailure(com.google.common.truth.ExpectFailure.StandardSubjectBuilderCallback) method, by contrast, does not have this limitation.

    • enterRuleContext

      void enterRuleContext()
      Enters rule context to be ready to capture failures.

      This should be rarely used directly, except if this class is as a long living object but not as a JUnit rule, like truth subject tests where for GWT compatible reasons.

    • leaveRuleContext

      void leaveRuleContext()
      Leaves rule context and verify if a failure has been caught if it's expected.

    • ensureFailureCaught

      void ensureFailureCaught()
      Ensures a failure is caught if it's expected (i.e., whenTesting() is called) and throws error if not.

    • getFailure

      public AssertionError getFailure()
      Returns the captured failure, if one occurred.

    • captureFailure

      private void captureFailure(AssertionError captured)
      Captures the provided failure, or throws an AssertionError if a failure had previously been captured.

    • expectFailure

      public static AssertionError expectFailure(ExpectFailure.StandardSubjectBuilderCallback assertionCallback)
      Static alternative that directly returns the triggered failure. This is intended to be used in Java 8+ tests similar to expectThrows():

      AssertionError failure = expectFailure(whenTesting -> whenTesting.that(4).isNotEqualTo(4));

    • expectFailureAbout

      public static <S extends Subject, A> AssertionError expectFailureAbout(Subject.Factory<S,A> factory, ExpectFailure.SimpleSubjectBuilderCallback<S,A> assertionCallback)
      Static alternative that directly returns the triggered failure. This is intended to be used in Java 8+ tests similar to expectThrows():

      AssertionError failure = expectFailureAbout(myTypes(), whenTesting -> whenTesting.that(myType).hasProperty());

    • assertThat

      public static TruthFailureSubject assertThat(AssertionError actual)
      Creates a subject for asserting about the given AssertionError, usually one produced by Truth.

    • apply

      public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)