Class ExpectFailure

  • All Implemented Interfaces:
    Platform.JUnitTestRule

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

      • inRuleContext

        private boolean inRuleContext
      • failureExpected

        private boolean failureExpected
      • failure

        private java.lang.AssertionError failure
    • 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

      • 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 java.lang.AssertionError getFailure()
        Returns the captured failure, if one occurred.
      • captureFailure

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

        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

        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​(java.lang.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)