Merge pull request #100 from bbatsche/callback-verifier

Callback Verifier

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,5 +1,5 @@
 name: Bug Report
-description: Report an issue with BeBat\Verify
+description: Report an issue with BeBat/Verify
 title: "[Bug]: "
 labels: ["bug"]
 body:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,5 +1,5 @@
 name: Feature Request
-description: Propose a new feature for BeBat\Verify
+description: Propose a new feature for BeBat/Verify
 title: "[Feature]: "
 labels: ["feature"]
 body:

.github/ISSUE_TEMPLATE/PULL_REQUEST_TEMPLATE.md → .github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,5 @@
 <!--
-    Thank you for your contribution to BeBat\Verify!
+    Thank you for your contribution to BeBat/Verify!
 
     Complete this template and the project maintainers will do
     their best to review your pull request in a timely manner.

CHANGELOG.md

@@ -6,6 +6,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/bbatsche/Verify/compare/3.1.1...master)
 
+### Added
+
+- `property()` and `propertyName()` methods - [#98][PR98]
+- `passCallback()` method to use a callback function to do validation - [#100][PR100]
+- (Dev) Pull request & issue templates - [#98][PR98]
+- (Dev) Test coverage for PHP 8.2 and PHPUnit 10 - [#98][PR98]
+- (Dev) Contribution guidelines and security policy - [#98][PR98]
+
+### Changed
+
+### Deprecated
+
+- `attribute()` and `attributeName()` methods (use `property()` and `propertyName()` instead) - [#98][PR98]
+- Using `attribute()` / `property()` with a class name as the subject [#98][PR98]
+- `staticAttribute()` method (this functionality will be removed in the next major version) - [#98][PR98]
+
+### Fixed
+
+- Passing the constraint factory along when calling `withVerifier()` - [#98][PR98]
+- `list()` assertion now uses correct PHPUnit constraint - [#98][PR98]
+- (Dev) PHPUnit test configuration - [#98][PR98]
+
 ## [3.1.1](https://github.com/bbatsche/Verify/compare/3.1.0...3.1.1) - 2022-11-09
 
 ### Fixed
@@ -103,3 +125,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [PR85]: https://github.com/bbatsche/Verify/pull/85 "Cleanup (3.1)"
 [PR86]: https://github.com/bbatsche/Verify/pull/86 "Method Assertions"
 [PR93]: https://github.com/bbatsche/Verify/pull/93 "Reset Return Value"
+[PR98]: https://github.com/bbatsche/Verify/pull/98 "Deprecate Attribute"
+[PR100]: https://github.com/bbatsche/Verify/pull/100 "Callback Verifier"

docs/assertions.rst

@@ -89,6 +89,16 @@ Truthiness
 
     verify($subject)->is()->empty();
 
+:php:`passCallback()`
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+    :caption: Assert that subject will pass a callback function
+
+    verify($subject)->will()->passCallback(function ($value): bool {
+        return isPrime($value);
+    });
+
 Type
 ----
 
@@ -556,6 +566,16 @@ Contents & Equality
 
     verify_file($link)->has()->linkTarget('/some/other/file');
 
+:php:`passCallback()`
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+    :caption: Assert that the file's contents will pass a callback function
+
+    verify_file($file)->will()->passCallback(function($content): bool {
+        return complexValidationChecks($content);
+    });
+
 Permissions
 -----------
 

phpstan.neon.dist

@@ -9,6 +9,7 @@ parameters:
   checkMissingIterableValueType: true
   ignoreErrors:
     - '/Call to function is_object\(\) with object will always evaluate to true/'
+    - '/Parameter \#1 \$callback of method BeBat\\Verify\\API\\Base::passCallback\(\) expects callable\(mixed\): bool/'
     -
       message: '/Call to an undefined method BeBat\\Verify\\API\\Base::equalTo/'
       path: %currentWorkingDirectory%/test/BaseUnitTest.php

src/API/Base.php

@@ -151,6 +151,18 @@ final public function constraint(Constraint $constraint): self
         return $this->performAssertion($constraint, $this->getActualValue());
     }
 
+    /**
+     * Assert SUT will or will not pass a given callback.
+     *
+     * @param callable(mixed $actual): bool $callback
+     *
+     * @return static
+     */
+    final public function passCallback(callable $callback): self
+    {
+        return $this->constraint($this->constraintFactory()->callback($callback));
+    }
+
     /**
      * Inject a custom Assert instance.
      *

src/Constraint/Factory.php

@@ -27,11 +27,9 @@ public function anything(): PHPUnitConstraint\IsAnything
     }
 
     /**
-     * @template CallbackInput of mixed
+     * @param callable(mixed $callback): bool $callback
      *
-     * @param callable(CallbackInput $callback): bool $callback
-     *
-     * @return PHPUnitConstraint\Callback<CallbackInput>
+     * @return PHPUnitConstraint\Callback<mixed>
      */
     public function callback(callable $callback): PHPUnitConstraint\Callback
     {

test/FileFunctionalTest.php

@@ -22,6 +22,18 @@ final class FileFunctionalTest extends TestCase
     /** @var string */
     private $fixtureDir = __DIR__ . '/_fixtures';
 
+    public function testCallbackAssertion(): void
+    {
+        verify_file($this->fixtureDir . '/File1')->will()
+            ->passCallback(static function (string $actual): bool {
+                return metaphone($actual) === '0SSMFL';
+            })
+            ->and()->willNot()
+            ->passCallback(static function (string $actual): bool {
+                return metaphone($actual) === 'FOOBAR';
+            });
+    }
+
     public function testContainsAssertion(): void
     {
         verify_file($this->fixtureDir . '/File1')->will()->contain('My File')

test/ValueFunctionalTest.php

@@ -24,6 +24,17 @@ final class ValueFunctionalTest extends TestCase
     /** @var string */
     private $fixtureDir = __DIR__ . '/_fixtures';
 
+    public function isPrime(int $num): bool
+    {
+        for ($i = 2; $i < $num / ($i - 1); ++$i) {
+            if ($num % $i === 0) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
     public function testArrayAssertions(): void
     {
         $object1 = new ExampleChild();
@@ -63,6 +74,12 @@ public function testBooleanAssertions(): void
             ->and()->isNot()->null();
     }
 
+    public function testCallableAssertion(): void
+    {
+        verify(7)->will()->passCallback([$this, 'isPrime']);
+        verify(169)->willNot()->passCallback([$this, 'isPrime']);
+    }
+
     /**
      * @requires PHPUnit < 10
      */