Class FailureMetadata
- java.lang.Object
-
- com.google.common.truth.FailureMetadata
-
public final class FailureMetadata extends java.lang.Object
An opaque, immutable object containing state from the previous calls in the fluent assertion chain. It appears primarily as a parameter toSubject
constructors (andSubject.Factory
methods), which should pass it to the superclass constructor and not otherwise use or store it. In particular, users should not attempt to callSubject
constructors orSubject.Factory
methods directly. Instead, they should use the appropriate factory method:- If you're writing a test:
Truth.assertAbout(Subject.Factory)
.that(...)
- If you're creating a derived subject from within another subject:
check(...).about(...).that(...)
- If you're testing your subject to verify that assertions fail when they should:
ExpectFailure
(One exception: Implementations of
CustomSubjectBuilder
do directly call constructors, using theirCustomSubjectBuilder.metadata()
method to get an instance to pass to the constructor.) - If you're writing a test:
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
FailureMetadata.OldAndNewValuesAreSimilar
Whether the value of the original subject and the value of the derived subject are "similar enough" that we don't need to display both.private static class
FailureMetadata.Step
The data from a call to either (a) aSubject
constructor or (b)Subject.check()
.
-
Field Summary
Fields Modifier and Type Field Description private com.google.common.collect.ImmutableList<LazyMessage>
messages
private com.google.common.collect.ImmutableList<FailureMetadata.Step>
steps
private FailureStrategy
strategy
-
Constructor Summary
Constructors Constructor Description FailureMetadata(FailureStrategy strategy, com.google.common.collect.ImmutableList<LazyMessage> messages, com.google.common.collect.ImmutableList<FailureMetadata.Step> steps)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private FailureMetadata
derive(com.google.common.collect.ImmutableList<LazyMessage> messages, com.google.common.collect.ImmutableList<FailureMetadata.Step> steps)
private com.google.common.collect.ImmutableList<Fact>
description()
Returns a description of the final actual value, if it appears "interesting" enough to show.private void
doFail(java.lang.AssertionError failure)
(package private) void
fail(com.google.common.collect.ImmutableList<Fact> facts)
(package private) void
failEqualityCheck(com.google.common.collect.ImmutableList<Fact> headFacts, com.google.common.collect.ImmutableList<Fact> tailFacts, java.lang.String expected, java.lang.String actual)
(package private) static FailureMetadata
forFailureStrategy(FailureStrategy failureStrategy)
private java.lang.Throwable
rootCause()
Returns the firstThrowable
in the chain of actual values.private com.google.common.collect.ImmutableList<Fact>
rootUnlessThrowable()
Returns the root actual value, if we know it's "different enough" from the final actual value.(package private) FailureMetadata
updateForCheckCall()
(package private) FailureMetadata
updateForCheckCall(FailureMetadata.OldAndNewValuesAreSimilar valuesAreSimilar, com.google.common.base.Function<java.lang.String,java.lang.String> descriptionUpdate)
(package private) FailureMetadata
updateForSubject(Subject subject)
Returns a new instance that includes the given subject in its chain of values.(package private) FailureMetadata
withMessage(java.lang.String format, java.lang.Object[] args)
Returns a new instance whose failures will contain the given message.
-
-
-
Field Detail
-
strategy
private final FailureStrategy strategy
-
messages
private final com.google.common.collect.ImmutableList<LazyMessage> messages
-
steps
private final com.google.common.collect.ImmutableList<FailureMetadata.Step> steps
-
-
Constructor Detail
-
FailureMetadata
FailureMetadata(FailureStrategy strategy, com.google.common.collect.ImmutableList<LazyMessage> messages, com.google.common.collect.ImmutableList<FailureMetadata.Step> steps)
-
-
Method Detail
-
forFailureStrategy
static FailureMetadata forFailureStrategy(FailureStrategy failureStrategy)
-
updateForSubject
FailureMetadata updateForSubject(Subject subject)
Returns a new instance that includes the given subject in its chain of values. Truth users do not need to call this method directly; Truth automatically accumulates context, starting from the initial that(...) call and continuing into any chained calls, likeThrowableSubject.hasMessageThat()
.
-
updateForCheckCall
FailureMetadata updateForCheckCall()
-
updateForCheckCall
FailureMetadata updateForCheckCall(FailureMetadata.OldAndNewValuesAreSimilar valuesAreSimilar, com.google.common.base.Function<java.lang.String,java.lang.String> descriptionUpdate)
-
withMessage
FailureMetadata withMessage(java.lang.String format, java.lang.Object[] args)
Returns a new instance whose failures will contain the given message. The way for Truth users to set a message ischeck(...).withMessage(...).that(...)
(for calls from within aSubject
) orTruth.assertWithMessage(java.lang.String)
(for most other calls).
-
failEqualityCheck
void failEqualityCheck(com.google.common.collect.ImmutableList<Fact> headFacts, com.google.common.collect.ImmutableList<Fact> tailFacts, java.lang.String expected, java.lang.String actual)
-
fail
void fail(com.google.common.collect.ImmutableList<Fact> facts)
-
doFail
private void doFail(java.lang.AssertionError failure)
-
derive
private FailureMetadata derive(com.google.common.collect.ImmutableList<LazyMessage> messages, com.google.common.collect.ImmutableList<FailureMetadata.Step> steps)
-
description
private com.google.common.collect.ImmutableList<Fact> description()
Returns a description of the final actual value, if it appears "interesting" enough to show. The description is considered interesting if the chain of derived subjects ends with at least one derivation that we have a name for. It's also considered interesting in the absence of derived subjects if we inferred a name for the root actual value from the bytecode.We don't want to say: "value of string: expected [foo] but was [bar]" (OK, we might still decide to say this, but for now, we don't.)
We do want to say: "value of throwable.getMessage(): expected [foo] but was [bar]"
We also want to say: "value of getLogMessages(): expected not to be empty"
To support that,
descriptionIsInteresting
tracks whether we've been given context throughcheck
calls that include names or, initially, whether we inferred a name for the root actual value from the bytecode.If we're missing a naming function halfway through, we have to reset: We don't want to claim that the value is "foo.bar.baz" when it's "foo.bar.somethingelse.baz." We have to go back to "object.baz." (But note that
rootUnlessThrowable()
will still provide the value of the root foo to the user as long as we had at least one naming function: We might not know the root's exact relationship to the final object, but we know it's some object "different enough" to be worth displaying.)
-
rootUnlessThrowable
private com.google.common.collect.ImmutableList<Fact> rootUnlessThrowable()
Returns the root actual value, if we know it's "different enough" from the final actual value.We don't want to say: "expected [foo] but was [bar]. string: [bar]"
We do want to say: "expected [foo] but was [bar]. myObject: MyObject[string=bar, i=0]"
To support that,
seenDerivation
tracks whether we've seen multiple actual values, which is equivalent to whether we've seen multiple Subject instances or, more informally, whether the user is making a chained assertion.There's one wrinkle: Sometimes chaining doesn't add information. This is often true with "internal" chaining, like when StreamSubject internally creates an IterableSubject to delegate to. The two subjects' string representations will be identical (or, in some cases, _almost_ identical), so there is no value in showing both. In such cases, implementations can call the no-arg
checkNoNeedToDisplayBothValues()
, which setsvaluesAreSimilar
, instructing this method that that particular chain link "doesn't count." (Note also that there are some edge cases that we're not sure how to handle yet, for which we might introduce additionalcheck
-like methods someday.)
-
rootCause
private java.lang.Throwable rootCause()
Returns the firstThrowable
in the chain of actual values. Typically, we'll have a root cause only if the assertion chain contains aThrowableSubject
.
-
-