| When using Truth, if a test subject and the argument to `isEqualTo` are the same |
| instance (for example `assertThat(x).isEqualTo(x)`), then the assertion will |
| always pass. Truth implements `isEqualTo` using [`Objects#equal`] , which tests |
| its arguments for reference equality and returns true without calling `equals()` |
| if both arguments are the same instance. |
| |
| JUnit's `assertEquals` (and similar) methods are implemented in terms of |
| `Object#equals`. However, this is not explicitly documented, so isn't a |
| contractual guarantee of the assertion methods. |
| |
| [`Objects#equals`]: https://guava.dev/releases/21.0/api/docs/com/google/common/base/Objects.html#equal-java.lang.Object-java.lang.Object- |
| |
| To test the implementation of an `equals` method, use |
| [Guava's EqualsTester][javadoc], or explicitly call `equals` as part of the |
| test. |
| |
| In our experience, `assertThat(x).isEqualTo(x)` and similar are *more likely to |
| be typos* than assertions about an `equals` method. This alone is sufficient |
| motivation to choose a dedicated approach for testing `equals` implementations. |
| |
| [javadoc]: https://javadoc.io/doc/com.google.guava/guava-testlib/latest/com/google/common/testing/EqualsTester.html |
