Custom Equality (BiPredicate) Comparator - resolves #3678

cookieMr · joel-costigliola · commit e1b0a4e39c6f · 2024-12-18T23:31:00.000+01:00
diff --git a/assertj-core/src/main/java/org/assertj/core/api/AbstractAssert.java b/assertj-core/src/main/java/org/assertj/core/api/AbstractAssert.java
@@ -31,6 +31,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.function.BiPredicate;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -717,6 +718,20 @@ public SELF usingComparator(Comparator<? super ACTUAL> customComparator, String
     return myself;
   }
 
+  /** {@inheritDoc} */
+  @Override
+  @CheckReturnValue
+  public SELF usingEquals(BiPredicate<? super ACTUAL, ? super ACTUAL> predicate) {
+    return usingEquals(predicate, null);
+  }
+
+  /** {@inheritDoc} */
+  @Override
+  @CheckReturnValue
+  public SELF usingEquals(BiPredicate<? super ACTUAL, ? super ACTUAL> predicate, String customEqualsDescription) {
+    return usingComparator((o1, o2) -> predicate.test(o1, o2) ? 0 : -1, customEqualsDescription);
+  }
+
   /** {@inheritDoc} */
   @Override
   @CheckReturnValue
diff --git a/assertj-core/src/main/java/org/assertj/core/api/Assert.java b/assertj-core/src/main/java/org/assertj/core/api/Assert.java
@@ -15,6 +15,7 @@
 import java.util.Comparator;
 import java.util.Date;
 import java.util.List;
+import java.util.function.BiPredicate;
 import java.util.function.Consumer;
 
 import org.assertj.core.presentation.Representation;
@@ -23,11 +24,10 @@
 /**
  * Base contract of all assertion objects: the minimum functionality that any assertion object should provide.
  *
- * @param <SELF> the "self" type of this assertion class. Please read &quot;<a href="http://bit.ly/1IZIRcY"
- *          target="_blank">Emulating
- *          'self types' using Java Generics to simplify fluent API implementation</a>&quot; for more details.
+ * @param <SELF>   the "self" type of this assertion class. Please read &quot;<a href="http://bit.ly/1IZIRcY"
+ *                 target="_blank">Emulating
+ *                 'self types' using Java Generics to simplify fluent API implementation</a>&quot; for more details.
  * @param <ACTUAL> the type of the "actual" value.
- *
  * @author Yvonne Wang
  * @author Alex Ruiz
  * @author Nicolas François
@@ -89,7 +89,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
 
   /**
    * Verifies that the actual value is not {@code null}.
-  * <p>
+   * <p>
    * Example:
    * <pre><code class='java'> // assertions succeed
    * assertThat(&quot;abc&quot;).isNotNull();
@@ -166,7 +166,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * @param values the given array to search the actual value in.
    * @return {@code this} assertion object.
    * @throws NullPointerException if the given array is {@code null}.
-   * @throws AssertionError if the actual value is not present in the given array.
+   * @throws AssertionError       if the actual value is not present in the given array.
    */
   SELF isIn(Object... values);
 
@@ -188,7 +188,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * @param values the given array to search the actual value in.
    * @return {@code this} assertion object.
    * @throws NullPointerException if the given array is {@code null}.
-   * @throws AssertionError if the actual value is present in the given array.
+   * @throws AssertionError       if the actual value is present in the given array.
    */
   SELF isNotIn(Object... values);
 
@@ -210,7 +210,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * @param values the given iterable to search the actual value in.
    * @return {@code this} assertion object.
    * @throws NullPointerException if the given collection is {@code null}.
-   * @throws AssertionError if the actual value is not present in the given iterable.
+   * @throws AssertionError       if the actual value is not present in the given iterable.
    */
   SELF isIn(Iterable<?> values);
 
@@ -232,7 +232,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * @param values the given iterable to search the actual value in.
    * @return {@code this} assertion object.
    * @throws NullPointerException if the given iterable is {@code null}.
-   * @throws AssertionError if the actual value is present in the given iterable.
+   * @throws AssertionError       if the actual value is present in the given iterable.
    */
   SELF isNotIn(Iterable<?> values);
 
@@ -248,29 +248,64 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * assertThat(frodo).usingComparator(raceComparator).isEqualTo(sam);</code></pre>
    *
    * @param customComparator the comparator to use for the incoming assertion checks.
-   * @throws NullPointerException if the given comparator is {@code null}.
    * @return {@code this} assertion object.
+   * @throws NullPointerException if the given comparator is {@code null}.
    */
   SELF usingComparator(Comparator<? super ACTUAL> customComparator);
 
   /**
    * Use the given custom comparator instead of relying on actual type A equals method for incoming assertion checks.
    * <p>
-   * The custom comparator is bound to assertion instance, meaning that if a new assertion instance is created, the default
+   * The custom comparator is bound to the current assertion chain, meaning that if a new assertion instance is created, the default
    * comparison strategy will be used.
    * <p>
    * Examples :
    * <pre><code class='java'> // frodo and sam are instances of Character with Hobbit race (obviously :).
    * // raceComparator implements Comparator&lt;Character&gt;
    * assertThat(frodo).usingComparator(raceComparator, "Hobbit Race Comparator").isEqualTo(sam);</code></pre>
    *
-   * @param customComparator the comparator to use for the incoming assertion checks.
+   * @param customComparator            the comparator to use for the incoming assertion checks.
    * @param customComparatorDescription comparator description to be used in assertion error messages
-   * @throws NullPointerException if the given comparator is {@code null}.
    * @return {@code this} assertion object.
+   * @throws NullPointerException if the given comparator is {@code null}.
    */
   SELF usingComparator(Comparator<? super ACTUAL> customComparator, String customComparatorDescription);
 
+  /**
+   * Uses the given custom {@link BiPredicate} instead of relying on actual type A {@code equals} method
+   * for incoming assertion checks.
+   * <p>
+   * The custom equals is bound to the current assertion chain, meaning that if a new assertion instance is created, the default
+   * comparison strategy will be used.
+   * <p>
+   * Examples:
+   * <pre><code class='java'> // frodo and sam are instances of Character of Hobbit race (obviously :).
+   * assertThat(frodo).usingEquals((f, s) -> f.race() == s.race()).isEqualTo(sam);</code></pre>
+   *
+   * @param predicate the predicate to use for the incoming assertion checks.
+   * @return {@code this} assertion object.
+   * @throws NullPointerException if the given biPredicate is {@code null}.
+   */
+  SELF usingEquals(BiPredicate<? super ACTUAL, ? super ACTUAL> predicate);
+
+  /**
+   * Uses the given custom {@link BiPredicate} instead of relying on actual type A {@code equals} method
+   * for incoming assertion checks. The given description is present in the assertion error if the assertion fails.
+   * <p>
+   * The custom equals is bound to the current assertion chain, meaning that if a new assertion instance is created, the default
+   * comparison strategy will be used.
+   * <p>
+   * Examples:
+   * <pre><code class='java'> // frodo and sam are instances of Character of Hobbit race (obviously :).
+   * assertThat(frodo).usingEquals((f, s) -> f.race() == s.race(), "comparing race").isEqualTo(sam);</code></pre>
+   *
+   * @param predicate               the predicate to use for the incoming assertion checks.
+   * @param customEqualsDescription comparator description to be used in assertion error messages
+   * @return {@code this} assertion object.
+   * @throws NullPointerException if the given comparator is {@code null}.
+   */
+  SELF usingEquals(BiPredicate<? super ACTUAL, ? super ACTUAL> predicate, String customEqualsDescription);
+
   /**
    * Revert to standard comparison for the incoming assertion checks.
    * <p>
@@ -301,12 +336,10 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param <ASSERT>                the type of the resulting {@code Assert}.
    * @param instanceOfAssertFactory the factory which verifies the type and creates the new {@code Assert}.
-   * @throws NullPointerException if the given factory is {@code null}.
    * @return the narrowed {@code Assert} instance.
-   *
+   * @throws NullPointerException if the given factory is {@code null}.
    * @see InstanceOfAssertFactory
    * @see InstanceOfAssertFactories
-   *
    * @since 3.13.0
    */
   <ASSERT extends AbstractAssert<?, ?>> ASSERT asInstanceOf(InstanceOfAssertFactory<?, ASSERT> instanceOfAssertFactory);
@@ -327,8 +360,8 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * @param type the type to check the actual value against.
    * @return this assertion object.
    * @throws NullPointerException if the given type is {@code null}.
-   * @throws AssertionError if the actual value is {@code null}.
-   * @throws AssertionError if the actual value is not an instance of the given type.
+   * @throws AssertionError       if the actual value is {@code null}.
+   * @throws AssertionError       if the actual value is not an instance of the given type.
    */
   SELF isInstanceOf(Class<?> type);
 
@@ -357,14 +390,14 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * // not a Jedi !
    * assertThat("foo").isInstanceOfSatisfying(Jedi.class, jediRequirements);</code></pre>
    *
-   * @param <T> the generic type to check the actual value against.
-   * @param type the type to check the actual value against.
+   * @param <T>          the generic type to check the actual value against.
+   * @param type         the type to check the actual value against.
    * @param requirements the requirements expressed as a {@link Consumer}.
    * @return this assertion object.
    * @throws NullPointerException if the given type is {@code null}.
    * @throws NullPointerException if the given Consumer is {@code null}.
-   * @throws AssertionError if the actual value is {@code null}.
-   * @throws AssertionError if the actual value is not an instance of the given type.
+   * @throws AssertionError       if the actual value is {@code null}.
+   * @throws AssertionError       if the actual value is not an instance of the given type.
    */
   <T> SELF isInstanceOfSatisfying(Class<T> type, Consumer<T> requirements);
 
@@ -383,8 +416,8 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param types the types to check the actual value against.
    * @return this assertion object.
-   * @throws AssertionError if the actual value is {@code null}.
-   * @throws AssertionError if the actual value is not an instance of any of the given types.
+   * @throws AssertionError       if the actual value is {@code null}.
+   * @throws AssertionError       if the actual value is not an instance of any of the given types.
    * @throws NullPointerException if the given array of types is {@code null}.
    * @throws NullPointerException if the given array of types contains {@code null}s.
    */
@@ -406,8 +439,8 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * @param type the type to check the actual value against.
    * @return this assertion object.
    * @throws NullPointerException if the given type is {@code null}.
-   * @throws AssertionError if the actual value is {@code null}.
-   * @throws AssertionError if the actual value is an instance of the given type.
+   * @throws AssertionError       if the actual value is {@code null}.
+   * @throws AssertionError       if the actual value is an instance of the given type.
    */
   SELF isNotInstanceOf(Class<?> type);
 
@@ -426,8 +459,8 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param types the types to check the actual value against.
    * @return this assertion object.
-   * @throws AssertionError if the actual value is {@code null}.
-   * @throws AssertionError if the actual value is an instance of any of the given types.
+   * @throws AssertionError       if the actual value is {@code null}.
+   * @throws AssertionError       if the actual value is an instance of any of the given types.
    * @throws NullPointerException if the given array of types is {@code null}.
    * @throws NullPointerException if the given array of types contains {@code null}s.
    */
@@ -448,7 +481,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param other the object to check type against.
    * @return this assertion object.
-   * @throws AssertionError if {@code actual} has not the same type as the given object.
+   * @throws AssertionError       if {@code actual} has not the same type as the given object.
    * @throws NullPointerException if the actual value is null.
    * @throws NullPointerException if the given object is null.
    */
@@ -483,7 +516,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * assertThat(wrapper).hasToString("FooWrapper[foo=%s]", foo); </code></pre>
    *
    * @param expectedStringTemplate the format string to use.
-   * @param args the arguments to interpolate into the format string.
+   * @param args                   the arguments to interpolate into the format string.
    * @return this assertion object.
    * @throws AssertionError if {@code actual.toString()} result is not equal to the given {@code String}.
    * @throws AssertionError if actual is {@code null}.
@@ -520,7 +553,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * assertThat(wrapper).doesNotHaveToString("FooBarWrapper[%s]", foo);</code></pre>
    *
    * @param expectedStringTemplate the format string to use.
-   * @param args the arguments to interpolate into the format string.
+   * @param args                   the arguments to interpolate into the format string.
    * @return this assertion object.
    * @throws AssertionError if {@code actual.toString()} result is equal to the given {@code String}.
    * @throws AssertionError if actual is {@code null}.
@@ -543,7 +576,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param other the object to check type against.
    * @return this assertion object.
-   * @throws AssertionError if {@code actual} has the same type as the given object.
+   * @throws AssertionError       if {@code actual} has the same type as the given object.
    * @throws NullPointerException if the actual value is null.
    * @throws NullPointerException if the given object is null.
    */
@@ -565,7 +598,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param type the type to check the actual value against.
    * @return this assertion object.
-   * @throws AssertionError if the actual is not <b>exactly</b> an instance of given type.
+   * @throws AssertionError       if the actual is not <b>exactly</b> an instance of given type.
    * @throws NullPointerException if the actual value is null.
    * @throws NullPointerException if the given object is null.
    */
@@ -587,7 +620,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param type the type to check the actual value against.
    * @return this assertion object.
-   * @throws AssertionError if the actual is exactly an instance of given type.
+   * @throws AssertionError       if the actual is exactly an instance of given type.
    * @throws NullPointerException if the actual value is null.
    * @throws NullPointerException if the given object is null.
    */
@@ -607,7 +640,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param types the types to check the actual value against.
    * @return this assertion object.
-   * @throws AssertionError if the actual value type is not in given type.
+   * @throws AssertionError       if the actual value type is not in given type.
    * @throws NullPointerException if the actual value is null.
    * @throws NullPointerException if the given types is null.
    */
@@ -627,7 +660,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    *
    * @param types the types to check the actual value against.
    * @return this assertion object.
-   * @throws AssertionError if the actual value type is in given types.
+   * @throws AssertionError       if the actual value type is in given types.
    * @throws NullPointerException if the actual value is null.
    * @throws NullPointerException if the given types is null.
    */
@@ -673,10 +706,9 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
   AbstractCharSequenceAssert<?, String> asString();
 
   /**
-   * @deprecated
-   *             Throws <code>{@link UnsupportedOperationException}</code> if called. It is easy to accidentally call
-   *             <code>equals(Object)</code> instead of <code>{@link #isEqualTo(Object)}</code>.
    * @throws UnsupportedOperationException if this method is called.
+   * @deprecated Throws <code>{@link UnsupportedOperationException}</code> if called. It is easy to accidentally call
+   * <code>equals(Object)</code> instead of <code>{@link #isEqualTo(Object)}</code>.
    */
   @Override
   @Deprecated
@@ -687,7 +719,7 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * <p>
    * Example :
    * <pre><code class='java'> assertThat("Messi").withThreadDumpOnError().isEqualTo("Ronaldo");</code></pre>
-   *
+   * <p>
    * will print a thread dump, something similar to this:
    * <pre>{@code "JDWP Command Reader"
    * 	java.lang.Thread.State: RUNNABLE
@@ -793,13 +825,10 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * assertThat(&quot;The Force&quot;).hasSameHashCodeAs(&quot;Awakens&quot;);</code></pre>
    *
    * @param other the object to check hashCode against.
-   *
    * @return this assertion object.
-   *
-   * @throws AssertionError if the actual object is null.
+   * @throws AssertionError       if the actual object is null.
    * @throws NullPointerException if the other object is null.
-   * @throws AssertionError if the actual object has not the same hashCode as the given object.
-   *
+   * @throws AssertionError       if the actual object has not the same hashCode as the given object.
    * @since 2.9.0
    */
   SELF hasSameHashCodeAs(Object other);
@@ -818,13 +847,10 @@ public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> extends Descr
    * assertThat(new Jedi(&quot;Yoda&quot;, &quot;Blue&quot;)).doesNotHaveSameHashCodeAs(new Jedi(&quot;Yoda&quot;, &quot;Blue&quot;)); </code></pre>
    *
    * @param other the object to check hashCode against.
-   *
    * @return this assertion object.
-   *
-   * @throws AssertionError if the actual object is null.
+   * @throws AssertionError       if the actual object is null.
    * @throws NullPointerException if the other object is null.
-   * @throws AssertionError if the actual object has the same hashCode as the given object.
-   *
+   * @throws AssertionError       if the actual object has the same hashCode as the given object.
    * @since 3.19.0
    */
   SELF doesNotHaveSameHashCodeAs(Object other);
diff --git a/assertj-core/src/test/java/org/assertj/core/api/object/ObjectAssert_usingEquals_Test.java b/assertj-core/src/test/java/org/assertj/core/api/object/ObjectAssert_usingEquals_Test.java
