Document assertObjectEquals()

Author: sebastianbergmann

src/assertions.rst

@@ -1014,6 +1014,104 @@ Please read "`What Every Computer Scientist Should Know About Floating-Point Ari
     FAILURES!
     Tests: 1, Assertions: 1, Failures: 1.
 
+.. _appendixes.assertions.assertObjectEquals:
+
+assertObjectEquals()
+####################
+
+``assertObjectEquals(object $expected, object $actual, string $method = 'equals', string $message = ''])``
+
+Reports an error identified by ``$message`` if ``$actual`` is not equal to ``$expected`` according to ``$actual->$method($expected)``.
+
+It is a bad practice to use ``assertEquals()`` (and its inverse, ``assertNotEquals()``) on objects without registering a custom comparator that customizes how objects are compared. Unfortunately, though, implementing custom comparators for each and every object you want to assert in your tests is inconvenient at best.
+
+The most common use case for custom comparators are Value Objects. These objects usually have an ``equals(self $other): bool`` method (or a method just like that but with a different name) for comparing two instances of the Value Object's type. ``assertObjectEquals()`` makes custom comparison of objects convenient for this common use case:
+
+.. code-block:: php
+    :caption: Usage of assertObjectEquals()
+    :name: appendixes.assertions.assertObjectEquals.example
+
+    <?php declare(strict_types=1);
+    use PHPUnit\Framework\TestCase;
+
+    final class SomethingThatUsesEmailTest extends TestCase
+    {
+        public function testSomething(): void
+        {
+            $a = new Email('[email protected]');
+            $b = new Email('[email protected]');
+            $c = new Email('[email protected]');
+
+            // This passes
+            $this->assertObjectEquals($a, $b);
+
+            // This fails
+            $this->assertObjectEquals($a, $c);
+        }
+    }
+
+.. code-block:: php
+    :caption: Email value object with equals() method
+    :name: appendixes.assertions.Email.example
+
+    <?php declare(strict_types=1);
+    final class Email
+    {
+        private string $email;
+
+        public function __construct(string $email)
+        {
+            $this->ensureIsValidEmail($email);
+
+            $this->email = $email;
+        }
+
+        public function asString(): string
+        {
+            return $this->email;
+        }
+
+        public function equals(self $other): bool
+        {
+            return $this->asString() === $other->asString();
+        }
+
+        private function ensureIsValidEmail(string $email): void
+        {
+            // ...
+        }
+    }
+
+.. parsed-literal::
+
+    $ phpunit EqualsTest
+    PHPUnit |version|.0 by Sebastian Bergmann and contributors.
+
+    F                                                                   1 / 1 (100%)
+
+    Time: 00:00.017, Memory: 4.00 MB
+
+    There was 1 failure:
+
+    1) SomethingThatUsesEmailTest::testSomething
+    Failed asserting that two objects are equal.
+    The objects are not equal according to Email::equals().
+
+    /home/sb/SomethingThatUsesEmailTest.php:16
+
+    FAILURES!
+    Tests: 1, Assertions: 2, Failures: 1.
+
+Please note:
+
+* A method with name ``$method`` must exist on the ``$actual`` object
+* The method must accept exactly one argument
+* The respective parameter must have a declared type
+* The ``$expected`` object must be compatible with this declared type
+* The method must have a declared ``bool`` return type
+
+If any of the aforementioned assumptions is not fulfilled or if ``$actual->$method($expected)`` returns ``false`` then the assertion fails.
+
 .. _appendixes.assertions.assertFalse:
 
 assertFalse()