Added fulfills to enable custom truth tests

Author: ExeQue

README.md

@@ -259,6 +259,7 @@ The following additional assertions are available:
 | `enumValueExists($value, string $enumClass, string $message = '')`    | Check that a value is a value in an enum                             |
 | `keysExists($value, array $keys, string $message = '')`               | Check that a value has all the specified keys (array or ArrayAccess) |
 | `nullOr($value, callable $callback)`                                  | Execute the callback if the value is not null                        |
+| `fulfills($value, callable $callback, string $message = '')`          | Check that a value fulfills a custom condition                       |
 
 ## Development
 

src/Base.php

@@ -17,9 +17,9 @@
  */
 class Base extends WebmozartAssert
 {
-    protected static function reportInvalidArgument($message): void
+    protected static function reportInvalidArgument($message, ?InvalidArgumentException $previous = null): void
     {
-        throw new InvalidArgumentException($message);
+        throw new InvalidArgumentException($message, previous: $previous);
     }
 
     /**
@@ -264,7 +264,7 @@ public static function keysExists($value, array $keys, string $message = ''): vo
         foreach ($keys as $key) {
             try {
                 self::keyExists($value, $key);
-            } catch (InvalidArgumentException) {
+            } catch (InvalidArgumentException $exception) {
                 $normalizer = fn (array $keys) => implode(
                     ', ',
                     array_map(
@@ -282,8 +282,39 @@ public static function keysExists($value, array $keys, string $message = ''): vo
                         $expected,
                         $actual,
                     ),
+                    $exception
                 );
             }
         }
     }
+
+    /**
+     * @param mixed $value
+     * @param callable $callback
+     * @param string $message
+     * @return void
+     */
+    public static function fulfills($value, callable $callback, string $message = ''): void
+    {
+        $defaultMessage = 'Value does not fulfill the given condition.';
+
+        $previous = null;
+        try {
+            $match = $callback($value);
+        } catch (InvalidArgumentException $exception) {
+            $match = $exception;
+            $previous = $exception;
+        }
+
+        if ($match instanceof InvalidArgumentException) {
+            $defaultMessage .= ' ' . $match->getMessage();
+        }
+
+        if ($match !== true) {
+            static::reportInvalidArgument(
+                $message ?: $defaultMessage,
+                $previous
+            );
+        }
+    }
 }

src/Concerns/Mixin.php

@@ -1345,6 +1345,78 @@ public function allNullOrFloat($message = ''): static
 
     // endregion [ Base::float ]
 
+    // region [ Base::fulfills ]
+
+    /**
+     * @param callable $callback
+     * @param string $message
+     *
+     * @see Base::fulfills
+     */
+    public function fulfills($callback, $message = ''): static
+    {
+        $this->used = true;
+
+        Base::fulfills($this->value, ...func_get_args());
+
+        return $this;
+    }
+
+    /**
+     * @param callable $callback
+     * @param string $message
+     *
+     * @see Base::nullOrFulfills
+     */
+    public function nullOrFulfills($callback, $message = ''): static
+    {
+        $this->used = true;
+
+        if ($this->value === null) {
+            return $this;
+        }
+
+        Base::fulfills($this->value, ...func_get_args());
+
+        return $this;
+    }
+
+    /**
+     * @param callable $callback
+     * @param string $message
+     *
+     * @see Base::allFulfills
+     */
+    public function allFulfills($callback, $message = ''): static
+    {
+        $this->used = true;
+
+        $args = func_get_args();
+
+        return $this->each(
+            fn (self $assert) => $assert->fulfills(...$args)
+        );
+    }
+
+    /**
+     * @param callable $callback
+     * @param string $message
+     *
+     * @see Base::allNullOrFulfills
+     */
+    public function allNullOrFulfills($callback, $message = ''): static
+    {
+        $this->used = true;
+
+        $args = func_get_args();
+
+        return $this->each(
+            fn (self $assert) => $assert->nullOrFulfills(...$args)
+        );
+    }
+
+    // endregion [ Base::fulfills ]
+
     // region [ Base::greaterThan ]
 
     /**

tests/Unit/Extensions/FulfillsTest.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+use ExeQue\FluentAssert\Assert;
+use ExeQue\FluentAssert\Exceptions\InvalidArgumentException;
+
+it('can fulfill a condition', function () {
+
+    Assert::for('hello')
+        ->fulfills(fn (string $value) => $value === 'hello')
+        ->fulfills(fn (string $value) => strlen($value) === 5);
+
+    $this->expectNotToPerformAssertions();
+});
+
+it('fails if condition is not fulfilled', function () {
+    expect(
+        fn () => Assert::for('hello')
+        ->fulfills(fn (string $value) => $value === 'world', 'Value is not "world"'),
+    )->toThrow(InvalidArgumentException::class, 'Value is not "world"');
+});
+
+it('fails if a sub assertion is not fulfilled', function () {
+    expect(
+        fn () => Assert::for('hello')
+        ->fulfills(function (string $value) {
+            Assert::for($value)->same('world', 'Value is not "world"');
+
+            return true;
+        }),
+    )->toThrow(InvalidArgumentException::class, 'Value is not "world"');
+});