Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
AssertObjectEquals trait: polyfill the Assert::assertObjectEquals() m…
…ethod
PHPUnit 9.4.0 introduced the new `Assert::assertObjectEquals()` method.
This commit:
* Adds two traits with the same name.
One to polyfill the method when not available in PHPUnit.
The other to allow for `use`-ing the trait in PHPUnit versions in which the method is already natively available.
* Adds an `InvalidComparisonMethodException` exception class.
_PHPUnit natively throws a range of different exceptions._
_The polyfill included in this library throws one exception type - the `InvalidComparisonMethodException` - with a range of different messages._
* Logic to the custom autoloader which will load the correct trait depending on the PHPUnit version used.
* Adds tests.
As the polyfill contains logic to match the PHPUnit native implementation as closely as possible, while still being PHP and PHPUnit cross-version compatible, extensive unit tests have been added to ensure the behaviour of the polyfill matches that of the original function, with the exception of the _return type verification_.
As return types were not available in PHP prior to PHP 7.0, the return type verification as done in the PHPUnit native implementation, has been replaced by a verification that the _returned value_ is of the required type.
This provides the same safeguard as the PHPUnit native implementation, but in a PHP cross-version compatible manner.
Note: the method uses `static::` to call the PHPUnit native functionality. This allows for existing method overloads in a child class of the PHPUnit native `TestCase` to be respected.
Includes:
* Adding information on the new polyfill to the README.
* Adding the new polyfill to the existing `TestCases` classes.
* Adding a few select exceptions to the PHPCS ruleset for the fixtures used in the tests.
Refs:
* sebastianbergmann/phpunit#4467
* sebastianbergmann/phpunit#4707
* sebastianbergmann/phpunit@1dba8c3
* sebastianbergmann/phpunit@6099c5e- Loading branch information
Showing
18 changed files
with
1,361 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| <?php | ||
|
|
||
| namespace Yoast\PHPUnitPolyfills\Exceptions; | ||
|
|
||
| use Exception; | ||
|
|
||
| /** | ||
| * Exception used for all errors throw by the polyfill for the `assertObjectEquals()` assertion. | ||
| * | ||
| * PHPUnit natively throws a range of different exceptions. | ||
| * The polyfill throws just one exception type with different messages. | ||
| */ | ||
| final class InvalidComparisonMethodException extends Exception { | ||
|
|
||
| /** | ||
| * Convert the Exception object to a string message. | ||
| * | ||
| * @return string | ||
| */ | ||
| public function __toString() { | ||
| return $this->getMessage() . \PHP_EOL; | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,234 @@ | ||
| <?php | ||
|
|
||
| namespace Yoast\PHPUnitPolyfills\Polyfills; | ||
|
|
||
| use ReflectionClass; | ||
| use ReflectionException; | ||
| use ReflectionNamedType; | ||
| use ReflectionObject; | ||
| use ReflectionType; | ||
| use TypeError; | ||
| use Yoast\PHPUnitPolyfills\Exceptions\InvalidComparisonMethodException; | ||
|
|
||
| /** | ||
| * Polyfill the Assert::assertObjectEquals() methods. | ||
| * | ||
| * Introduced in PHPUnit 9.4.0. | ||
| * | ||
| * The polyfill implementation closely matches the PHPUnit native implementation with the exception | ||
| * of the return type check and the names of the thrown exceptions. | ||
| * | ||
| * @link https://github.com/sebastianbergmann/phpunit/issues/4467 | ||
| * @link https://github.com/sebastianbergmann/phpunit/issues/4707 | ||
| * @link https://github.com/sebastianbergmann/phpunit/commit/1dba8c3a4b2dd04a3ff1869f75daaeb6757a14ee | ||
| * @link https://github.com/sebastianbergmann/phpunit/commit/6099c5eefccfda860c889f575d58b5fe6cc10c83 | ||
| */ | ||
| trait AssertObjectEquals { | ||
|
|
||
| /** | ||
| * Asserts that two objects are considered equal based on a custom object comparison | ||
| * using a comparator method in the target object. | ||
| * | ||
| * The custom comparator method is expected to have the following method | ||
| * signature: `equals(self $other): bool` (or similar with a different method name). | ||
| * | ||
| * Basically, the assertion checks the following: | ||
| * - A method with name $method must exist on the $actual object. | ||
| * - The method must accept exactly one argument and this argument must be required. | ||
| * - This parameter must have a classname-based declared type. | ||
| * - The $expected object must be compatible with this declared type. | ||
| * - The method must have a declared bool return type. (JRF: not verified in this implementation) | ||
| * - `$actual->$method($expected)` returns boolean true. | ||
| * | ||
| * @param object $expected Expected value. | ||
| * @param object $actual The value to test. | ||
| * @param string $method The name of the comparator method within the object. | ||
| * @param string $message Optional failure message to display. | ||
| * | ||
| * @return void | ||
| * | ||
| * @throws TypeError When any of the passed arguments do not meet the required type. | ||
| * @throws InvalidComparisonMethodException When the comparator method does not comply with the requirements. | ||
| */ | ||
| public static function assertObjectEquals( $expected, $actual, $method = 'equals', $message = '' ) { | ||
| /* | ||
| * Parameter input validation. | ||
| * In PHPUnit this is done via PHP native type declarations. Emulating this for the polyfill. | ||
| */ | ||
| if ( \is_object( $expected ) === false ) { | ||
| throw new TypeError( | ||
| \sprintf( | ||
| 'Argument 1 passed to assertObjectEquals() must be an object, %s given', | ||
| \gettype( $expected ) | ||
| ) | ||
| ); | ||
| } | ||
|
|
||
| if ( \is_object( $actual ) === false ) { | ||
| throw new TypeError( | ||
| \sprintf( | ||
| 'Argument 2 passed to assertObjectEquals() must be an object, %s given', | ||
| \gettype( $actual ) | ||
| ) | ||
| ); | ||
| } | ||
|
|
||
| if ( \is_scalar( $method ) === false ) { | ||
| throw new TypeError( | ||
| \sprintf( | ||
| 'Argument 3 passed to assertObjectEquals() must be of the type string, %s given', | ||
| \gettype( $method ) | ||
| ) | ||
| ); | ||
| } | ||
| else { | ||
| $method = (string) $method; | ||
| } | ||
|
|
||
| /* | ||
| * Comparator method validation. | ||
| */ | ||
| $reflObject = new ReflectionObject( $actual ); | ||
|
|
||
| if ( $reflObject->hasMethod( $method ) === false ) { | ||
| throw new InvalidComparisonMethodException( | ||
| \sprintf( | ||
| 'Comparison method %s::%s() does not exist.', | ||
| \get_class( $actual ), | ||
| $method | ||
| ) | ||
| ); | ||
| } | ||
|
|
||
| $reflMethod = $reflObject->getMethod( $method ); | ||
|
|
||
| /* | ||
| * As the next step, PHPUnit natively would validate the return type, | ||
| * but as return type declarations is a PHP 7.0+ feature, the polyfill | ||
| * skips this check in favour of checking the type of the actual | ||
| * returned value. | ||
| * | ||
| * Also see the upstream discussion about this: | ||
| * {@link https://github.com/sebastianbergmann/phpunit/issues/4707} | ||
| */ | ||
|
|
||
| /* | ||
| * Comparator method parameter requirements validation. | ||
| */ | ||
| if ( $reflMethod->getNumberOfParameters() !== 1 | ||
| || $reflMethod->getNumberOfRequiredParameters() !== 1 | ||
| ) { | ||
| throw new InvalidComparisonMethodException( | ||
| \sprintf( | ||
| 'Comparison method %s::%s() does not declare exactly one parameter.', | ||
| \get_class( $actual ), | ||
| $method | ||
| ) | ||
| ); | ||
| } | ||
|
|
||
| $noDeclaredTypeError = \sprintf( | ||
| 'Parameter of comparison method %s::%s() does not have a declared type.', | ||
| \get_class( $actual ), | ||
| $method | ||
| ); | ||
|
|
||
| $notAcceptableTypeError = \sprintf( | ||
| '%s is not an accepted argument type for comparison method %s::%s().', | ||
| \get_class( $expected ), | ||
| \get_class( $actual ), | ||
| $method | ||
| ); | ||
|
|
||
| $reflParameter = $reflMethod->getParameters()[0]; | ||
|
|
||
| if ( \method_exists( $reflParameter, 'hasType' ) ) { | ||
| // PHP >= 7.0. | ||
| $hasType = $reflParameter->hasType(); | ||
| if ( $hasType === false ) { | ||
| throw new InvalidComparisonMethodException( $noDeclaredTypeError ); | ||
| } | ||
|
|
||
| $type = $reflParameter->getType(); | ||
| if ( \class_exists( 'ReflectionNamedType' ) ) { | ||
| // PHP >= 7.1. | ||
| if ( ( $type instanceof ReflectionNamedType ) === false ) { | ||
| throw new InvalidComparisonMethodException( $noDeclaredTypeError ); | ||
| } | ||
|
|
||
| $typeName = $type->getName(); | ||
| } | ||
| else { | ||
| /* | ||
| * PHP 7.0. | ||
| * Checking for `ReflectionType` will not throw an error on union types, | ||
| * but then again union types are not supported on PHP 7.0. | ||
| */ | ||
| if ( ( $type instanceof ReflectionType ) === false ) { | ||
| throw new InvalidComparisonMethodException( $noDeclaredTypeError ); | ||
| } | ||
|
|
||
| $typeName = (string) $type; | ||
| } | ||
| } | ||
| else { | ||
| // PHP < 7.0. | ||
| try { | ||
| /* | ||
| * Using `ReflectionParameter::getClass()` will trigger an autoload of the class, | ||
| * but that's okay as for a valid class type that would be triggered on the | ||
| * function call to the $method (at the end of this assertion) anyway. | ||
| */ | ||
| $hasType = $reflParameter->getClass(); | ||
| } catch ( ReflectionException $e ) { | ||
| // Class with a type declaration for a non-existent class. | ||
| throw new InvalidComparisonMethodException( $notAcceptableTypeError ); | ||
| } | ||
|
|
||
| if ( ( $hasType instanceof ReflectionClass ) === false ) { | ||
| // Array or callable type. | ||
| throw new InvalidComparisonMethodException( $noDeclaredTypeError ); | ||
| } | ||
|
|
||
| $typeName = $hasType->name; | ||
| } | ||
|
|
||
| /* | ||
| * Validate that the $expected object complies with the declared parameter type. | ||
| */ | ||
| if ( $typeName === 'self' ) { | ||
| $typeName = \get_class( $actual ); | ||
| } | ||
|
|
||
| if ( ( $expected instanceof $typeName ) === false ) { | ||
| throw new InvalidComparisonMethodException( $notAcceptableTypeError ); | ||
| } | ||
|
|
||
| /* | ||
| * Execute the comparator method. | ||
| */ | ||
| $result = $actual->{$method}( $expected ); | ||
|
|
||
| if ( \is_bool( $result ) === false ) { | ||
| throw new InvalidComparisonMethodException( | ||
| \sprintf( | ||
| '%s::%s() does not return a boolean value.', | ||
| \get_class( $actual ), | ||
| $method | ||
| ) | ||
| ); | ||
| } | ||
|
|
||
| $msg = \sprintf( | ||
| 'Failed asserting that two objects are equal. The objects are not equal according to %s::%s()', | ||
| \get_class( $actual ), | ||
| $method | ||
| ); | ||
|
|
||
| if ( $message !== '' ) { | ||
| $msg = $message . \PHP_EOL . $msg; | ||
| } | ||
|
|
||
| static::assertTrue( $result, $msg ); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| <?php | ||
|
|
||
| namespace Yoast\PHPUnitPolyfills\Polyfills; | ||
|
|
||
| /** | ||
| * Empty trait for use with PHPUnit >= 9.4.0 in which this polyfill is not needed. | ||
| */ | ||
| trait AssertObjectEquals {} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.