Class Correspondence.TolerantNumericEquality

  • Enclosing class:
    Correspondence<A,​E>

    private static final class Correspondence.TolerantNumericEquality
    extends Correspondence<java.lang.Number,​java.lang.Number>
    • Field Detail

      • tolerance

        private final double tolerance
    • Constructor Detail

      • TolerantNumericEquality

        private TolerantNumericEquality​(double tolerance)
    • Method Detail

      • compare

        public boolean compare​(java.lang.Number actual,
                               java.lang.Number expected)
        Description copied from class: Correspondence
        Returns whether or not the actual value is said to correspond to the expected value for the purposes of this test.

        Exception handling

        Throwing a RuntimeException from this method indicates that this Correspondence 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

        
         static final Correspondence<String, String> CASE_INSENSITIVE_EQUALITY =
             Correspondence.from(String::equalsIgnoreCase, "equals ignoring case"
         }
        whose compare method throws NullPointerException if the actual value is null. The assertion
        
         assertThat(asList(null, "xyz", "abc", "def"))
             .comparingElementsUsing(CASE_INSENSITIVE_EQUALITY)
             .containsExactly("ABC", "DEF", "GHI", "JKL");
         
        may fail saying that the actual iterable contains unexpected values null and xyz and is missing values corresponding to GHI and JKL, which is what it would do if the compare method returned false instead of throwing, and additionally mention the exception. (This is more helpful than allowing the NullPointerException to propagate to the caller, or than failing with only a description of the exception.)

        However, the assertions

        
         assertThat(asList(null, "xyz", "abc", "def"))
             .comparingElementsUsing(CASE_INSENSITIVE_EQUALITY)
             .doesNotContain("MNO");
         
        and
        
         assertThat(asList(null, "xyz", "abc", "def"))
             .comparingElementsUsing(CASE_INSENSITIVE_EQUALITY)
             .doesNotContain(null);
         
        must both fail citing the exception, even though they would pass if the 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 class Correspondence<java.lang.Number,​java.lang.Number>
      • toString

        public java.lang.String 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 by Correspondence.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 class Correspondence<java.lang.Number,​java.lang.Number>