Class ExpectFailure

  • All Implemented Interfaces:
    TestRule

    public final class ExpectFailure
    extends java.lang.Object
    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.

    • Constructor Detail

      • 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 Detail

      • getFailure

        public java.lang.AssertionError getFailure()
        Returns the captured failure, if one occurred.
      • expectFailure

        @CanIgnoreReturnValue
        public static java.lang.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

        @CanIgnoreReturnValue
        public static <S extends Subject,​A> java.lang.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​(@Nullable java.lang.AssertionError actual)
        Creates a subject for asserting about the given AssertionError, usually one produced by Truth.