Package com.google.common.truth

Class ExpectFailure

java.lang.Object

com.google.common.truth.ExpectFailure

All Implemented Interfaces:

Platform.JUnitTestRule, org.junit.rules.TestRule

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.

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.

Field Summary

Fields

Modifier and Type	Field	Description
private java.lang.AssertionError	failure
private boolean	failureExpected
private boolean	inRuleContext
private FailureStrategy	strategy

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)
static TruthFailureSubject	assertThat(java.lang.AssertionError actual)	Creates a subject for asserting about the given AssertionError, usually one produced by Truth.
private void	captureFailure(java.lang.AssertionError captured)	Captures the provided failure, or throws an AssertionError if a failure had previously been captured.
(package private) void	ensureFailureCaught()	Ensures a failure is caught if it's expected (i.e., whenTesting() is called) and throws error if not.
(package private) void	enterRuleContext()	Enters rule context to be ready to capture failures.
static java.lang.AssertionError	expectFailure(ExpectFailure.StandardSubjectBuilderCallback assertionCallback)	Static alternative that directly returns the triggered failure.
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.
java.lang.AssertionError	getFailure()	Returns the captured failure, if one occurred.
(package private) void	leaveRuleContext()	Leaves rule context and verify if a failure has been caught if it's expected.
StandardSubjectBuilder	whenTesting()	Returns a test verb 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

Field Detail

strategy

private final FailureStrategy strategy

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

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

Specified by:

apply in interface org.junit.rules.TestRule