Polyfill for equalTo constraint specializations

[mergeMarc]

This PR adds the EqualToSpecializations Trait that adds polyfills for the in PHPUnit 9.0.0 introduced methods equalToCanonicalizing, equalToIgnoringCase and equalToWithDelta.

Since PHPUnit Version 9.0.0 equalTo constraints got their own specializations to replicate the assertEquals specializations. (see sebastianbergmann/phpunit@43c01a4) The usage of equalTo with these parameters never got deprecated and also had no replacement until the functionality was removed (see sebastianbergmann/phpunit@e470a3a).
This means that test cases that want to use equalTo with additional configuration cannot be written to work with both PHPUnit 8 (or older) and PHPUnit 9 without the use of a polyfill.

[jrfnl]

@mergeMarc Thanks for this PR.

For my understanding: is there a particular reason why you are using the equalToCanonicalizing(), equalToIgnoringCase() and equalToWithDelta() methods directly and not using the assert[Not]EqualsCanonicalizing(), assert[Not]EqualsIgnoringCase() assert[Not]EqualsWithDelta() methods ?

The assertion methods are already polyfilled in the Yoast\PHPUnitPolyfills\Polyfills\AssertEqualsSpecializations trait and have been from the start (initial release) of this library.

Note: I'm not adverse to including this, I'd just like to understand the usecase.

[mergeMarc]

I totally understand. I didn't find other people mentioning this issue anywhere so usage is probably not so wide spread.

I need to use it with PHPUnit Mock Objects. To check parameters that are passed to a mocked method call one needs to use a Constraint instead of the usual asserting of a value right away (see docs example).

Example:

In this excerpt of a simple test case I check if my main application uses my "PersistenceInterface" correctly. I need to include the delta here since the DateTime value of my "Day" will always be off by a few milliseconds. If I run the first version in PHPUnit 9 the test will always fail since the delta is not considered (equalTo only accepts one parameter since v9).

PHPUnit < 9

$today = new Day($todayDate, $todaysWeather);
$storage = $this->createMock(PersistenceInterface::class);
$storage->expects($this->once())
            ->method('updateDay')
            ->with($this->equalTo($today, 10));
...

PHPUnit >= 9

$today = new Day($todayDate, $todaysWeather);
$storage = $this->createMock(PersistenceInterface::class);
$storage->expects($this->once())
            ->method('updateDay')
            ->with($this->equalToWithDelta($today, 10));
...

[jrfnl]

@mergeMarc Thanks for that additional information. Makes sense to me and I'm happy to include it.

There are a few more (minor) changes needed for this PR to be complete. I'd be happy to make those or give you feedback to allow you make them. What would you prefer ?

[mergeMarc]

@jrfnl Feel free to commit those changes. I would also be available to make them if they require more work. Thank you.

[jrfnl]

@mergeMarc No, nothing major. I've just pushed the commit and will give you a moment to look it over.

One of us will still need to rebase the PR to make it mergable.

[jrfnl]

Ended up adding two more touch up commits. Will stop looking now ;-) (and will squash on merge or rebase).

[jrfnl]

Rebased on develop to make the PR mergable. No new changes.

[jrfnl]

@mergeMarc Thanks a lot for this PR. Great contribution and well done on the completeness of the PR. This new feature will be included in the next release.