Class Correspondence.FromBinaryPredicate<A,E>
- Enclosing class:
- Correspondence<A,
E>
-
Nested Class Summary
Nested classes/interfaces inherited from class com.google.common.truth.Correspondence
Correspondence.BinaryPredicate<A,
E>, Correspondence.DiffFormatter<A, E>, Correspondence.ExceptionStore -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final String
private final Correspondence.BinaryPredicate<A,
E> -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
FromBinaryPredicate
(Correspondence.BinaryPredicate<A, E> correspondencePredicate, String description) -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returns whether or not theactual
value is said to correspond to theexpected
value for the purposes of this test.toString()
Returns a description of the correspondence, suitable to fill the gap in a failure message of the form"<some actual element> is an element that ... <some expected element>"
.Methods inherited from class com.google.common.truth.Correspondence
describeForIterable, describeForMapValues, equals, formatDiff, formattingDiffsUsing, from, hashCode, safeCompare, safeFormatDiff, tolerance, transforming, transforming
-
Field Details
-
predicate
-
description
-
-
Constructor Details
-
FromBinaryPredicate
private FromBinaryPredicate(Correspondence.BinaryPredicate<A, E> correspondencePredicate, String description)
-
-
Method Details
-
compare
Description copied from class:Correspondence
Returns whether or not theactual
value is said to correspond to theexpected
value for the purposes of this test.Exception handling
Throwing a
RuntimeException
from this method indicates that thisCorrespondence
cannot compare the given values. Any assertion which encounters such an exception during the course of evaluating its condition must not pass. However, an assertion is not required to invoke this method for every pair of values in its input just in order to check for exceptions, if it is able to evaluate its condition without doing so.Conventions for handling exceptions
(N.B. This section is only really of interest when implementing assertion methods that call
Correspondence.compare(A, E)
, not to users making such assertions in their tests.)The only requirement on an assertion is that, if it encounters an exception from this method, it must not pass. The simplest implementation choice is simply to allow the exception to propagate. However, it is normally more helpful to catch the exception and instead fail with a message which includes more information about the assertion in progress and the nature of the failure.
By convention, an assertion may catch and store the exception and continue evaluating the condition as if the method had returned false instead of throwing. If the assertion's condition does not hold with this alternative behaviour, it may choose to fail with a message that gives details about how the condition does not hold, additionally mentioning that assertions were encountered and giving details about one of the stored exceptions. (See the first example below.) If the assertion's condition does hold with this alternative behaviour, the requirement that the assertion must not pass still applies, so it should fail with a message giving details about one of the stored exceptions. (See the second and third examples below.)
This behaviour is only a convention and should only be implemented when it makes sense to do so. In particular, in an assertion that has multiple stages, it may be better to only continue evaluation to the end of the current stage, and fail citing a stored exception at the end of the stage, rather than accumulating exceptions through the multiple stages.
Examples of exception handling
Suppose that we have the correspondence
whosestatic final Correspondence<String, String> CASE_INSENSITIVE_EQUALITY = Correspondence.from(String::equalsIgnoreCase, "equals ignoring case"
}compare
method throwsNullPointerException
if the actual value is null. The assertion
may fail saying that the actual iterable contains unexpected valuesassertThat(asList(null, "xyz", "abc", "def")) .comparingElementsUsing(CASE_INSENSITIVE_EQUALITY) .containsExactly("ABC", "DEF", "GHI", "JKL");
null
andxyz
and is missing values corresponding toGHI
andJKL
, which is what it would do if thecompare
method returned false instead of throwing, and additionally mention the exception. (This is more helpful than allowing theNullPointerException
to propagate to the caller, or than failing with only a description of the exception.)However, the assertions
andassertThat(asList(null, "xyz", "abc", "def")) .comparingElementsUsing(CASE_INSENSITIVE_EQUALITY) .doesNotContain("MNO");
must both fail citing the exception, even though they would pass if theassertThat(asList(null, "xyz", "abc", "def")) .comparingElementsUsing(CASE_INSENSITIVE_EQUALITY) .doesNotContain(null);
compare
method returned false. (Note that, in the latter case at least, it is likely that the test author's intention was not for the test to pass with these values.)- Specified by:
compare
in classCorrespondence<A,
E>
-
toString
Description copied from class:Correspondence
Returns a description of the correspondence, suitable to fill the gap in a failure message of the form"<some actual element> is an element that ... <some expected element>"
. Note that this is a fragment of a verb phrase which takes a singular subject.Example 1: For a
Correspondence<String, Integer>
that tests whether the actual string parses to the expected integer, this would return"parses to"
to result in a failure message of the form"<some actual string> is an element that parses to <some expected integer>"
.Example 2: For the
Correspondence<Number, Number>
returns byCorrespondence.tolerance(double)
this returns"is a finite number within " + tolerance + " of"
to result in a failure message of the form"<some actual number> is an element that is a finite number within 0.0001 of <some expected number>"
.- Specified by:
toString
in classCorrespondence<A,
E>
-