Class ExpectFailure

java.lang.Object

com.google.common.truth.ExpectFailure

All Implemented Interfaces:

TestRule

public final class ExpectFailure
extends 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 e =
       expectFailure(whenTesting -> whenTesting.that(cancelButton).isVisible());
   assertThat(e).factKeys().containsExactly("expected to be visible");

 ...

 private static AssertionError expectFailure(
     SimpleSubjectBuilderCallback<UiElementSubject, UiElement> assertionCallback) {
   return expectFailureAbout(uiElements(), assertionCallback);
 }
 

ExpectFailure also supports a legacy approach, which we no longer recommend now that all Truth users can use lambdas. That approach is based on the JUnit @Rule system:

 @Rule public final ExpectFailure expectFailure = new ExpectFailure();

 ...

     expectFailure.whenTesting().about(uiElements()).that(cancelButton).isVisible();
     assertThat(expectFailure.getFailure()).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 performs additional checks:
  • It checks that the assertion you're testing uses the supplied FailureStrategy.
  • It checks that the assertion you're testing calls FailureStrategy.fail(java.lang.AssertionError) only once.
• It instructs Truth to generate failure messages without adding lines like "value of: foo()" for assertThat(foo()).... calls that it detects in the test bytecode. Truth doesn't provide guarantees for when such lines will be generated, so tests become more resilient without them.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ExpectFailure.SimpleSubjectBuilderCallback<S extends Subject, A>	A functional interface for expectFailureAbout() to invoke and capture failures.
static interface	ExpectFailure.StandardSubjectBuilderCallback	A functional interface for expectFailure() to invoke and capture failures.

Constructor Summary

Constructors

Constructor	Description
ExpectFailure()	Creates a new instance for use as a @Rule.

Method Summary

Modifier and Type	Method	Description
Statement	apply(Statement base, Description description)
static TruthFailureSubject	assertThat(@Nullable AssertionError actual)	Creates a subject for asserting about the given AssertionError, usually one produced by Truth.
static AssertionError	expectFailure(ExpectFailure.StandardSubjectBuilderCallback assertionCallback)	Captures and returns the failure produced by the assertion in the provided callback, similar to assertThrows():
static <S extends Subject, A> AssertionError	expectFailureAbout(Subject.Factory<S,A> factory, ExpectFailure.SimpleSubjectBuilderCallback<S,A> assertionCallback)	Captures and returns the failure produced by the assertion in the provided callback, similar to assertThrows():
AssertionError	getFailure()	Legacy method that returns the failure captured by whenTesting(), if one occurred.
StandardSubjectBuilder	whenTesting()	Legacy method that returns a subject builder that expects the chained assertion to fail, and makes the failure available via getFailure().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Legacy method that returns a subject builder 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.

getFailure

public AssertionError getFailure()

Legacy method that returns the failure captured by whenTesting(), if one occurred.

expectFailure

@CanIgnoreReturnValue
public static AssertionError expectFailure(ExpectFailure.StandardSubjectBuilderCallback assertionCallback)

Captures and returns the failure produced by the assertion in the provided callback, similar to assertThrows():

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

expectFailureAbout

@CanIgnoreReturnValue
public static <S extends Subject, A> AssertionError expectFailureAbout(Subject.Factory<S,A> factory,
 ExpectFailure.SimpleSubjectBuilderCallback<S,A> assertionCallback)

Captures and returns the failure produced by the assertion in the provided callback, similar to assertThrows():

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

assertThat

public static TruthFailureSubject assertThat(@Nullable AssertionError actual)

Creates a subject for asserting about the given AssertionError, usually one produced by Truth.

apply

@GwtIncompatible("org.junit.rules.TestRule")
public Statement apply(Statement base,
 Description description)

Specified by:

apply in interface TestRule