Merge pull request #583 from fabio-ivona/add-failed-expectations-message

[2.x] Add custom message to failed expectations

src/Expectation.php

@@ -14,6 +14,7 @@ use Pest\Exceptions\InvalidExpectationValue;
 use Pest\Expectations\EachExpectation;
 use Pest\Expectations\HigherOrderExpectation;
 use Pest\Expectations\OppositeExpectation;
+use Pest\Matchers\Any;
 use Pest\Support\ExpectationPipeline;
 use PHPUnit\Framework\Assert;
 use PHPUnit\Framework\ExpectationFailedException;
@@ -280,7 +281,7 @@ final class Expectation
     {
         if (! self::hasMethod($method)) {
             /* @phpstan-ignore-next-line */
-            return new HigherOrderExpectation($this, $this->value->$method(...$parameters));
+            return new HigherOrderExpectation($this, call_user_func_array($this->value->$method(...), $parameters));
         }
 
         ExpectationPipeline::for($this->getExpectationClosure($method))
@@ -339,4 +340,12 @@ final class Expectation
             || method_exists(Mixins\Expectation::class, $name)
             || self::hasExtend($name);
     }
+
+    /**
+     * Matches any value.
+     */
+    public function any(): Any
+    {
+        return new Any();
+    }
 }

src/Matchers/Any.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Matchers;
+
+/**
+ * @internal
+ */
+final class Any
+{
+}

src/Mixins/Expectation.php

@@ -9,6 +9,7 @@ use Closure;
 use Error;
 use InvalidArgumentException;
 use Pest\Exceptions\InvalidExpectationValue;
+use Pest\Matchers\Any;
 use Pest\Support\Arr;
 use Pest\Support\NullClosure;
 use PHPUnit\Framework\Assert;
@@ -51,9 +52,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBe(mixed $expected): self
+    public function toBe(mixed $expected, string $message = ''): self
     {
-        Assert::assertSame($expected, $this->value);
+        Assert::assertSame($expected, $this->value, $message);
 
         return $this;
     }
@@ -63,9 +64,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeEmpty(): self
+    public function toBeEmpty(string $message = ''): self
     {
-        Assert::assertEmpty($this->value);
+        Assert::assertEmpty($this->value, $message);
 
         return $this;
     }
@@ -75,9 +76,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeTrue(): self
+    public function toBeTrue(string $message = ''): self
     {
-        Assert::assertTrue($this->value);
+        Assert::assertTrue($this->value, $message);
 
         return $this;
     }
@@ -87,9 +88,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeTruthy(): self
+    public function toBeTruthy(string $message = ''): self
     {
-        Assert::assertTrue((bool) $this->value);
+        Assert::assertTrue((bool) $this->value, $message);
 
         return $this;
     }
@@ -99,9 +100,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeFalse(): self
+    public function toBeFalse(string $message = ''): self
     {
-        Assert::assertFalse($this->value);
+        Assert::assertFalse($this->value, $message);
 
         return $this;
     }
@@ -111,9 +112,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeFalsy(): self
+    public function toBeFalsy(string $message = ''): self
     {
-        Assert::assertFalse((bool) $this->value);
+        Assert::assertFalse((bool) $this->value, $message);
 
         return $this;
     }
@@ -123,9 +124,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeGreaterThan(int|float $expected): self
+    public function toBeGreaterThan(int|float $expected, string $message = ''): self
     {
-        Assert::assertGreaterThan($expected, $this->value);
+        Assert::assertGreaterThan($expected, $this->value, $message);
 
         return $this;
     }
@@ -135,9 +136,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeGreaterThanOrEqual(int|float $expected): self
+    public function toBeGreaterThanOrEqual(int|float $expected, string $message = ''): self
     {
-        Assert::assertGreaterThanOrEqual($expected, $this->value);
+        Assert::assertGreaterThanOrEqual($expected, $this->value, $message);
 
         return $this;
     }
@@ -147,9 +148,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeLessThan(int|float $expected): self
+    public function toBeLessThan(int|float $expected, string $message = ''): self
     {
-        Assert::assertLessThan($expected, $this->value);
+        Assert::assertLessThan($expected, $this->value, $message);
 
         return $this;
     }
@@ -159,9 +160,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeLessThanOrEqual(int|float $expected): self
+    public function toBeLessThanOrEqual(int|float $expected, string $message = ''): self
     {
-        Assert::assertLessThanOrEqual($expected, $this->value);
+        Assert::assertLessThanOrEqual($expected, $this->value, $message);
 
         return $this;
     }
@@ -192,15 +193,15 @@ final class Expectation
      * Asserts that the value starts with $expected.
      *
      * @param  non-empty-string  $expected
-     *@return self<TValue>
+     * @return self<TValue>
      */
-    public function toStartWith(string $expected): self
+    public function toStartWith(string $expected, string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertStringStartsWith($expected, $this->value);
+        Assert::assertStringStartsWith($expected, $this->value, $message);
 
         return $this;
     }
@@ -209,15 +210,15 @@ final class Expectation
      * Asserts that the value ends with $expected.
      *
      * @param  non-empty-string  $expected
-     *@return self<TValue>
+     * @return self<TValue>
      */
-    public function toEndWith(string $expected): self
+    public function toEndWith(string $expected, string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertStringEndsWith($expected, $this->value);
+        Assert::assertStringEndsWith($expected, $this->value, $message);
 
         return $this;
     }
@@ -227,22 +228,22 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toHaveLength(int $number): self
+    public function toHaveLength(int $number, string $message = ''): self
     {
         if (is_string($this->value)) {
-            Assert::assertEquals($number, mb_strlen($this->value));
+            Assert::assertEquals($number, mb_strlen($this->value), $message);
 
             return $this;
         }
 
         if (is_iterable($this->value)) {
-            return $this->toHaveCount($number);
+            return $this->toHaveCount($number, $message);
         }
 
         if (is_object($this->value)) {
             $array = method_exists($this->value, 'toArray') ? $this->value->toArray() : (array) $this->value;
 
-            Assert::assertCount($number, $array);
+            Assert::assertCount($number, $array, $message);
 
             return $this;
         }
@@ -255,13 +256,13 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toHaveCount(int $count): self
+    public function toHaveCount(int $count, string $message = ''): self
     {
         if (! is_countable($this->value) && ! is_iterable($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertCount($count, $this->value);
+        Assert::assertCount($count, $this->value, $message);
 
         return $this;
     }
@@ -271,16 +272,16 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toHaveProperty(string $name, mixed $value = null): self
+    public function toHaveProperty(string $name, mixed $value = new Any(), string $message = ''): self
     {
         $this->toBeObject();
 
         // @phpstan-ignore-next-line
-        Assert::assertTrue(property_exists($this->value, $name));
+        Assert::assertTrue(property_exists($this->value, $name), $message);
 
-        if (func_num_args() > 1) {
+        if (! $value instanceof Any) {
             /* @phpstan-ignore-next-line */
-            Assert::assertEquals($value, $this->value->{$name});
+            Assert::assertEquals($value, $this->value->{$name}, $message);
         }
 
         return $this;
@@ -290,12 +291,12 @@ final class Expectation
      * Asserts that the value contains the provided properties $names.
      *
      * @param  iterable<array-key, string>  $names
-     *@return self<TValue>
+     * @return self<TValue>
      */
-    public function toHaveProperties(iterable $names): self
+    public function toHaveProperties(iterable $names, string $message = ''): self
     {
         foreach ($names as $name) {
-            $this->toHaveProperty($name);
+            $this->toHaveProperty($name, message: $message);
         }
 
         return $this;
@@ -306,9 +307,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toEqual(mixed $expected): self
+    public function toEqual(mixed $expected, string $message = ''): self
     {
-        Assert::assertEquals($expected, $this->value);
+        Assert::assertEquals($expected, $this->value, $message);
 
         return $this;
     }
@@ -324,9 +325,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toEqualCanonicalizing(mixed $expected): self
+    public function toEqualCanonicalizing(mixed $expected, string $message = ''): self
     {
-        Assert::assertEqualsCanonicalizing($expected, $this->value);
+        Assert::assertEqualsCanonicalizing($expected, $this->value, $message);
 
         return $this;
     }
@@ -337,9 +338,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toEqualWithDelta(mixed $expected, float $delta): self
+    public function toEqualWithDelta(mixed $expected, float $delta, string $message = ''): self
     {
-        Assert::assertEqualsWithDelta($expected, $this->value, $delta);
+        Assert::assertEqualsWithDelta($expected, $this->value, $delta, $message);
 
         return $this;
     }
@@ -350,9 +351,9 @@ final class Expectation
      * @param  iterable<int|string, mixed>  $values
      * @return self<TValue>
      */
-    public function toBeIn(iterable $values): self
+    public function toBeIn(iterable $values, string $message = ''): self
     {
-        Assert::assertContains($this->value, $values);
+        Assert::assertContains($this->value, $values, $message);
 
         return $this;
     }
@@ -362,9 +363,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeInfinite(): self
+    public function toBeInfinite(string $message = ''): self
     {
-        Assert::assertInfinite($this->value);
+        Assert::assertInfinite($this->value, $message);
 
         return $this;
     }
@@ -375,9 +376,9 @@ final class Expectation
      * @param  class-string  $class
      * @return self<TValue>
      */
-    public function toBeInstanceOf(string $class): self
+    public function toBeInstanceOf(string $class, string $message = ''): self
     {
-        Assert::assertInstanceOf($class, $this->value);
+        Assert::assertInstanceOf($class, $this->value, $message);
 
         return $this;
     }
@@ -387,9 +388,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeArray(): self
+    public function toBeArray(string $message = ''): self
     {
-        Assert::assertIsArray($this->value);
+        Assert::assertIsArray($this->value, $message);
 
         return $this;
     }
@@ -399,9 +400,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeBool(): self
+    public function toBeBool(string $message = ''): self
     {
-        Assert::assertIsBool($this->value);
+        Assert::assertIsBool($this->value, $message);
 
         return $this;
     }
@@ -411,9 +412,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeCallable(): self
+    public function toBeCallable(string $message = ''): self
     {
-        Assert::assertIsCallable($this->value);
+        Assert::assertIsCallable($this->value, $message);
 
         return $this;
     }
@@ -423,9 +424,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeFloat(): self
+    public function toBeFloat(string $message = ''): self
     {
-        Assert::assertIsFloat($this->value);
+        Assert::assertIsFloat($this->value, $message);
 
         return $this;
     }
@@ -435,9 +436,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeInt(): self
+    public function toBeInt(string $message = ''): self
     {
-        Assert::assertIsInt($this->value);
+        Assert::assertIsInt($this->value, $message);
 
         return $this;
     }
@@ -447,9 +448,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeIterable(): self
+    public function toBeIterable(string $message = ''): self
     {
-        Assert::assertIsIterable($this->value);
+        Assert::assertIsIterable($this->value, $message);
 
         return $this;
     }
@@ -459,9 +460,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeNumeric(): self
+    public function toBeNumeric(string $message = ''): self
     {
-        Assert::assertIsNumeric($this->value);
+        Assert::assertIsNumeric($this->value, $message);
 
         return $this;
     }
@@ -471,9 +472,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeObject(): self
+    public function toBeObject(string $message = ''): self
     {
-        Assert::assertIsObject($this->value);
+        Assert::assertIsObject($this->value, $message);
 
         return $this;
     }
@@ -483,9 +484,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeResource(): self
+    public function toBeResource(string $message = ''): self
     {
-        Assert::assertIsResource($this->value);
+        Assert::assertIsResource($this->value, $message);
 
         return $this;
     }
@@ -495,9 +496,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeScalar(): self
+    public function toBeScalar(string $message = ''): self
     {
-        Assert::assertIsScalar($this->value);
+        Assert::assertIsScalar($this->value, $message);
 
         return $this;
     }
@@ -507,9 +508,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeString(): self
+    public function toBeString(string $message = ''): self
     {
-        Assert::assertIsString($this->value);
+        Assert::assertIsString($this->value, $message);
 
         return $this;
     }
@@ -519,12 +520,12 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeJson(): self
+    public function toBeJson(string $message = ''): self
     {
-        Assert::assertIsString($this->value);
+        Assert::assertIsString($this->value, $message);
 
         // @phpstan-ignore-next-line
-        Assert::assertJson($this->value);
+        Assert::assertJson($this->value, $message);
 
         return $this;
     }
@@ -534,9 +535,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeNan(): self
+    public function toBeNan(string $message = ''): self
     {
-        Assert::assertNan($this->value);
+        Assert::assertNan($this->value, $message);
 
         return $this;
     }
@@ -546,9 +547,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeNull(): self
+    public function toBeNull(string $message = ''): self
     {
-        Assert::assertNull($this->value);
+        Assert::assertNull($this->value, $message);
 
         return $this;
     }
@@ -558,7 +559,7 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toHaveKey(string|int $key, mixed $value = null): self
+    public function toHaveKey(string|int $key, mixed $value = new Any(), string $message = ''): self
     {
         if (is_object($this->value) && method_exists($this->value, 'toArray')) {
             $array = $this->value->toArray();
@@ -571,11 +572,15 @@ final class Expectation
 
             /* @phpstan-ignore-next-line */
         } catch (ExpectationFailedException $exception) {
-            throw new ExpectationFailedException("Failed asserting that an array has the key '$key'", $exception->getComparisonFailure());
+            if ($message === '') {
+                $message = "Failed asserting that an array has the key '$key'";
+            }
+
+            throw new ExpectationFailedException($message, $exception->getComparisonFailure());
         }
 
-        if (func_num_args() > 1) {
+        if (! $value instanceof Any) {
-            Assert::assertEquals($value, Arr::get($array, $key));
+            Assert::assertEquals($value, Arr::get($array, $key), $message);
         }
 
         return $this;
@@ -584,16 +589,16 @@ final class Expectation
     /**
      * Asserts that the value array has the provided $keys.
      *
-     * @param  array<int, int|string|array<int-string, mixed>>  $keys
+     * @param  array<int, int|string|array<array-key, mixed>>  $keys
      * @return self<TValue>
      */
-    public function toHaveKeys(array $keys): self
+    public function toHaveKeys(array $keys, string $message = ''): self
     {
         foreach ($keys as $k => $key) {
             if (is_array($key)) {
-                $this->toHaveKeys(array_keys(Arr::dot($key, $k.'.')));
+                $this->toHaveKeys(array_keys(Arr::dot($key, $k.'.')), $message);
             } else {
-                $this->toHaveKey($key);
+                $this->toHaveKey($key, message: $message);
             }
         }
 
@@ -605,13 +610,13 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeDirectory(): self
+    public function toBeDirectory(string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertDirectoryExists($this->value);
+        Assert::assertDirectoryExists($this->value, $message);
 
         return $this;
     }
@@ -621,13 +626,13 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeReadableDirectory(): self
+    public function toBeReadableDirectory(string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertDirectoryIsReadable($this->value);
+        Assert::assertDirectoryIsReadable($this->value, $message);
 
         return $this;
     }
@@ -637,13 +642,13 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeWritableDirectory(): self
+    public function toBeWritableDirectory(string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertDirectoryIsWritable($this->value);
+        Assert::assertDirectoryIsWritable($this->value, $message);
 
         return $this;
     }
@@ -653,13 +658,13 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeFile(): self
+    public function toBeFile(string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertFileExists($this->value);
+        Assert::assertFileExists($this->value, $message);
 
         return $this;
     }
@@ -669,13 +674,13 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeReadableFile(): self
+    public function toBeReadableFile(string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
 
-        Assert::assertFileIsReadable($this->value);
+        Assert::assertFileIsReadable($this->value, $message);
 
         return $this;
     }
@@ -685,12 +690,12 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toBeWritableFile(): self
+    public function toBeWritableFile(string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
-        Assert::assertFileIsWritable($this->value);
+        Assert::assertFileIsWritable($this->value, $message);
 
         return $this;
     }
@@ -701,7 +706,7 @@ final class Expectation
      * @param  iterable<int|string, mixed>  $array
      * @return self<TValue>
      */
-    public function toMatchArray(iterable $array): self
+    public function toMatchArray(iterable $array, string $message = ''): self
     {
         if (is_object($this->value) && method_exists($this->value, 'toArray')) {
             $valueAsArray = $this->value->toArray();
@@ -710,17 +715,17 @@ final class Expectation
         }
 
         foreach ($array as $key => $value) {
-            Assert::assertArrayHasKey($key, $valueAsArray);
+            Assert::assertArrayHasKey($key, $valueAsArray, $message);
 
-            Assert::assertEquals(
+            if ($message === '') {
-                $value,
+                $message = sprintf(
-                $valueAsArray[$key],
-                sprintf(
                     'Failed asserting that an array has a key %s with the value %s.',
                     $this->export($key),
                     $this->export($valueAsArray[$key]),
-                ),
+                );
-            );
+            }
+
+            Assert::assertEquals($value, $valueAsArray[$key], $message);
         }
 
         return $this;
@@ -733,26 +738,27 @@ final class Expectation
      * @param  iterable<string, mixed>  $object
      * @return self<TValue>
      */
-    public function toMatchObject(iterable $object): self
+    public function toMatchObject(iterable $object, string $message = ''): self
     {
         foreach ((array) $object as $property => $value) {
             if (! is_object($this->value) && ! is_string($this->value)) {
                 InvalidExpectationValue::expected('object|string');
             }
 
-            Assert::assertTrue(property_exists($this->value, $property));
+            Assert::assertTrue(property_exists($this->value, $property), $message);
 
             /* @phpstan-ignore-next-line */
             $propertyValue = $this->value->{$property};
-            Assert::assertEquals(
+
-                $value,
+            if ($message === '') {
-                $propertyValue,
+                $message = sprintf(
-                sprintf(
                     'Failed asserting that an object has a property %s with the value %s.',
                     $this->export($property),
                     $this->export($propertyValue),
-                ),
+                );
-            );
+            }
+
+            Assert::assertEquals($value, $propertyValue, $message);
         }
 
         return $this;
@@ -763,12 +769,12 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toMatch(string $expression): self
+    public function toMatch(string $expression, string $message = ''): self
     {
         if (! is_string($this->value)) {
             InvalidExpectationValue::expected('string');
         }
-        Assert::assertMatchesRegularExpression($expression, $this->value);
+        Assert::assertMatchesRegularExpression($expression, $this->value, $message);
 
         return $this;
     }
@@ -778,9 +784,9 @@ final class Expectation
      *
      * @return self<TValue>
      */
-    public function toMatchConstraint(Constraint $constraint): self
+    public function toMatchConstraint(Constraint $constraint, string $message = ''): self
     {
-        Assert::assertThat($this->value, $constraint);
+        Assert::assertThat($this->value, $constraint, $message);
 
         return $this;
     }
@@ -789,13 +795,13 @@ final class Expectation
      * @param  class-string  $class
      * @return self<TValue>
      */
-    public function toContainOnlyInstancesOf(string $class): self
+    public function toContainOnlyInstancesOf(string $class, string $message = ''): self
     {
         if (! is_iterable($this->value)) {
             InvalidExpectationValue::expected('iterable');
         }
 
-        Assert::assertContainsOnlyInstancesOf($class, $this->value);
+        Assert::assertContainsOnlyInstancesOf($class, $this->value, $message);
 
         return $this;
     }
@@ -806,7 +812,7 @@ final class Expectation
      * @param (Closure(Throwable): mixed)|string $exception
      * @return self<TValue>
      */
-    public function toThrow(callable|string $exception, string $exceptionMessage = null): self
+    public function toThrow(callable|string $exception, string $exceptionMessage = null, string $message = ''): self
     {
         $callback = NullClosure::create();
 
@@ -833,16 +839,16 @@ final class Expectation
                     throw $e;
                 }
 
-                Assert::assertStringContainsString($exception, $e->getMessage());
+                Assert::assertStringContainsString($exception, $e->getMessage(), $message);
 
                 return $this;
             }
 
             if ($exceptionMessage !== null) {
-                Assert::assertStringContainsString($exceptionMessage, $e->getMessage());
+                Assert::assertStringContainsString($exceptionMessage, $e->getMessage(), $message);
             }
 
-            Assert::assertInstanceOf($exception, $e);
+            Assert::assertInstanceOf($exception, $e, $message);
             $callback($e);
 
             return $this;

src/Support/ExpectationPipeline.php

@@ -21,7 +21,7 @@ final class ExpectationPipeline
     /**
      * The list of passables.
      *
-     * @var array<int, mixed>
+     * @var array<array-key, mixed>
      */
     private array $passables;
 
@@ -46,7 +46,7 @@ final class ExpectationPipeline
      */
     public function send(mixed ...$passables): self
     {
-        $this->passables = array_values($passables);
+        $this->passables = $passables;
 
         return $this;
     }
@@ -72,7 +72,7 @@ final class ExpectationPipeline
             array_reverse($this->pipes),
             $this->carry(),
             function (): void {
-                ($this->closure)(...$this->passables);
+                call_user_func_array($this->closure, $this->passables);
             }
         );
 

tests/.snapshots/success.txt

@@ -242,36 +242,43 @@
    PASS  Tests\Features\Expect\toBe
   ✓ strict comparisons
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeArray
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeBool
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeCallable
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeDirectory
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeEmpty
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeFalse
   ✓ strict comparisons
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeFalsy
@@ -286,116 +293,139 @@
   ✓ passes as not falsy with (1) #2
   ✓ passes as not falsy with (-1)
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeFile
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeFloat
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeGreatherThan
   ✓ passes
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeGreatherThanOrEqual
   ✓ passes
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeIn
   ✓ passes
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeInfinite
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeInstanceOf
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeInt
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeIterable
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeJson
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeLessThan
   ✓ passes
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeLessThanOrEqual
   ✓ passes
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeNAN
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeNull
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeNumeric
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeObject
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeReadableDirectory
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeReadableFile
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeResource
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeScalar
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeString
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeTrue
   ✓ strict comparisons
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeTruthy
@@ -410,16 +440,19 @@
   ✓ passes as not truthy with (0)
   ✓ passes as not truthy with ('0')
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeWritableDirectory
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toBeWritableFile
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toContain
@@ -438,31 +471,36 @@
    PASS  Tests\Features\Expect\toContainOnlyInstancesOf
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toEndWith
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toEqual
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toEqualCanonicalizing
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toEqualWithDelta
   ✓ pass
-  ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toHaveCount
   ✓ pass
   ✓ failures
+  ✓ failures with message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toHaveKey
@@ -473,7 +511,11 @@
   ✓ pass with value check and nested key
   ✓ pass with value check and plain key with dots
   ✓ failures
+  ✓ failures with custom message
+  ✓ failures with custom message and Any matcher
   ✓ failures with nested key
+  ✓ failures with nested key and custom message
+  ✓ failures with nested key and custom message with Any matcher
   ✓ failures with plain key with dots
   ✓ fails with wrong value
   ✓ fails with wrong value and nested key
@@ -489,7 +531,9 @@
   ✓ pass
   ✓ pass with multi-dimensional arrays
   ✓ failures
+  ✓ failures with custom message
   ✓ failures with multi-dimensional arrays
+  ✓ failures with multi-dimensional arrays and custom message
   ✓ not failures
   ✓ not failures with multi-dimensional arrays
 
@@ -501,45 +545,51 @@
   ✓ it passes with array
   ✓ it passes with *not*
   ✓ it properly fails with *not*
-  ✓ it fails with (1)
+  ✓ it fails
-  ✓ it fails with (1.5)
+  ✓ it fails with message
-  ✓ it fails with (true)
-  ✓ it fails with (null)
 
    PASS  Tests\Features\Expect\toHaveProperties
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toHaveProperty
   ✓ pass
   ✓ failures
+  ✓ failures with message
+  ✓ failures with message and Any matcher
   ✓ not failures
 
    PASS  Tests\Features\Expect\toMatch
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toMatchArray
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toMatchConstraint
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toMatchObject
   ✓ pass
   ✓ pass with class
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toStartWith
   ✓ pass
   ✓ failures
+  ✓ failures with custom message
   ✓ not failures
 
    PASS  Tests\Features\Expect\toThrow
@@ -551,6 +601,7 @@
   ✓ failures 5
   ✓ failures 6
   ✓ failures 7
+  ✓ failures with custom message
   ✓ not failures
   ✓ closure missing parameter
   ✓ closure missing type-hint
@@ -767,4 +818,4 @@
    PASS  Tests\Visual\Version
   ✓ visual snapshot of help command output
 
-  Tests:    4 incomplete, 1 todo, 18 skipped, 511 passed (1286 assertions)
+  Tests:    4 incomplete, 1 todo, 18 skipped, 562 passed (1460 assertions)

tests/Features/Expect/toBe.php

@@ -15,6 +15,10 @@ test('failures', function () {
     expect(1)->toBe(2);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(1)->toBe(2, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(1)->not->toBe(1);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeArray.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(null)->toBeArray();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeArray('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(['a', 'b', 'c'])->not->toBeArray();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeBool.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(null)->toBeBool();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeBool('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(false)->not->toBeBool();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeCallable.php

@@ -14,6 +14,12 @@ test('failures', function () {
     expect($hello)->toBeCallable();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    $hello = 5;
+
+    expect($hello)->toBeCallable('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(function () {
         return 42;

tests/Features/Expect/toBeDirectory.php

@@ -12,6 +12,10 @@ test('failures', function () {
     expect('/random/path/whatever')->toBeDirectory();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('/random/path/whatever')->toBeDirectory('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('.')->not->toBeDirectory();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeEmpty.php

@@ -12,6 +12,11 @@ test('failures', function () {
     expect(' ')->toBeEmpty();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect([1, 2])->toBeEmpty('oh no!');
+    expect(' ')->toBeEmpty('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect([])->not->toBeEmpty();
     expect(null)->not->toBeEmpty();

tests/Features/Expect/toBeFalse.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('')->toBeFalse();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('')->toBeFalse('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(false)->not->toBe(false);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeFalsy.php

@@ -14,6 +14,10 @@ test('failures', function () {
     expect(1)->toBeFalsy();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(1)->toBeFalsy('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(null)->not->toBeFalsy();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeFile.php

@@ -18,6 +18,10 @@ test('failures', function () {
     expect('/random/path/whatever.file')->toBeFile();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('/random/path/whatever.file')->toBeFile('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect($this->tempFile)->not->toBeFile();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeFloat.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(42)->toBeFloat();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(42)->toBeFloat('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(log(3))->not->toBeFloat();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeGreatherThan.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(4)->toBeGreaterThan(4);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(4)->toBeGreaterThan(4, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(5)->not->toBeGreaterThan(4);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeGreatherThanOrEqual.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(4)->toBeGreaterThanOrEqual(4.1);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(4)->toBeGreaterThanOrEqual(4.1, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(5)->not->toBeGreaterThanOrEqual(5);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeIn.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect('d')->toBeIn(['a', 'b', 'c']);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('d')->toBeIn(['a', 'b', 'c'], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('a')->not->toBeIn(['a', 'b', 'c']);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeInfinite.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(asin(2))->toBeInfinite();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(asin(2))->toBeInfinite('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(INF)->not->toBeInfinite();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeInstanceOf.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(new Exception())->toBeInstanceOf(RuntimeException::class);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(new Exception())->toBeInstanceOf(RuntimeException::class, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(new Exception())->not->toBeInstanceOf(Exception::class);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeInt.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(42.0)->toBeInt();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(42.0)->toBeInt('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(6 * 7)->not->toBeInt();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeIterable.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(42)->toBeIterable();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(42)->toBeIterable('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     function gen(): iterable
     {

tests/Features/Expect/toBeJson.php

@@ -12,6 +12,10 @@ test('failures', function () {
     expect(':"world"}')->toBeJson();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(':"world"}')->toBeJson('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('{"hello":"world"}')->not->toBeJson();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeLessThan.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(4)->toBeLessThan(4);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(4)->toBeLessThan(4, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(5)->not->toBeLessThan(6);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeLessThanOrEqual.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(4)->toBeLessThanOrEqual(3.9);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(4)->toBeLessThanOrEqual(3.9, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(5)->not->toBeLessThanOrEqual(5);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeNAN.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(1)->toBeNan();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(1)->toBeNan('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(acos(1.5))->not->toBeNan();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeNull.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect('hello')->toBeNull();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('hello')->toBeNull('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(null)->not->toBeNull();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeNumeric.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(null)->toBeNumeric();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeNumeric('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(6 * 7)->not->toBeNumeric();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeObject.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(null)->toBeObject();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeObject('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect((object) 'ciao')->not->toBeObject();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeReadableDirectory.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('/random/path/whatever')->toBeReadableDirectory();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('/random/path/whatever')->toBeReadableDirectory('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(sys_get_temp_dir())->not->toBeReadableDirectory();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeReadableFile.php

@@ -18,6 +18,10 @@ test('failures', function () {
     expect('/random/path/whatever.file')->toBeReadableFile();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('/random/path/whatever.file')->toBeReadableFile('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect($this->tempFile)->not->toBeReadableFile();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeResource.php

@@ -17,6 +17,10 @@ test('failures', function () {
     expect(null)->toBeResource();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeResource('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () use ($resource) {
     expect($resource)->not->toBeResource();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeScalar.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect(null)->toBeScalar();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeScalar('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(42)->not->toBeScalar();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeString.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(null)->toBeString();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeString('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('42')->not->toBeString();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeTrue.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('')->toBeTrue();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('')->toBeTrue('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(false)->not->toBe(false);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeTruthy.php

@@ -14,6 +14,10 @@ test('failures', function () {
     expect(null)->toBeTruthy();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(null)->toBeTruthy('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(1)->not->toBeTruthy();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeWritableDirectory.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('/random/path/whatever')->toBeWritableDirectory();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('/random/path/whatever')->toBeWritableDirectory('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(sys_get_temp_dir())->not->toBeWritableDirectory();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toBeWritableFile.php

@@ -18,6 +18,10 @@ test('failures', function () {
     expect('/random/path/whatever.file')->toBeWritableFile();
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('/random/path/whatever.file')->toBeWritableFile('oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect($this->tempFile)->not->toBeWritableFile();
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toContainOnlyInstancesOf.php

@@ -15,6 +15,10 @@ test('failures', function () {
     expect($this->times)->toContainOnlyInstancesOf(DateTime::class);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect($this->times)->toContainOnlyInstancesOf(DateTime::class, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect($this->times)->not->toContainOnlyInstancesOf(DateTimeImmutable::class);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toEndWith.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('username')->toEndWith('password');
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('username')->toEndWith('password', 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('username')->not->toEndWith('name');
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toEqual.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect(['a', 'b', 'c'])->toEqual(['a', 'b']);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(['a', 'b', 'c'])->toEqual(['a', 'b'], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('042')->not->toEqual(42);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toEqualCanonicalizing.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect([3, 2, 1])->toEqualCanonicalizing([1, 2]);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect([3, 2, 1])->toEqualCanonicalizing([1, 2], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(['a', 'b', 'c'])->not->toEqualCanonicalizing(['b', 'a', 'c']);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toEqualWithDelta.php

@@ -6,9 +6,9 @@ test('pass', function () {
     expect(1.0)->toEqualWithDelta(1.3, .4);
 });
 
-test('failures', function () {
+test('failures with custom message', function () {
-    expect(1.0)->toEqualWithDelta(1.5, .1);
+    expect(1.0)->toEqualWithDelta(1.5, .1, 'oh no!');
-})->throws(ExpectationFailedException::class);
+})->throws(ExpectationFailedException::class, 'oh no!');
 
 test('not failures', function () {
     expect(1.0)->not->toEqualWithDelta(1.6, .7);

tests/Features/Expect/toHaveCount.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect([1, 2, 3])->toHaveCount(4);
 })->throws(ExpectationFailedException::class);
 
+test('failures with message', function () {
+    expect([1, 2, 3])->toHaveCount(4, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect([1, 2, 3])->not->toHaveCount(3);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toHaveKey.php

@@ -24,10 +24,26 @@ test('failures', function () use ($test_array) {
     expect($test_array)->toHaveKey('foo');
 })->throws(ExpectationFailedException::class, "Failed asserting that an array has the key 'foo'");
 
+test('failures with custom message', function () use ($test_array) {
+    expect($test_array)->toHaveKey('foo', message: 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
+test('failures with custom message and Any matcher', function () use ($test_array) {
+    expect($test_array)->toHaveKey('foo', expect()->any(), 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('failures with nested key', function () use ($test_array) {
     expect($test_array)->toHaveKey('d.bar');
 })->throws(ExpectationFailedException::class, "Failed asserting that an array has the key 'd.bar'");
 
+test('failures with nested key and custom message', function () use ($test_array) {
+    expect($test_array)->toHaveKey('d.bar', message: 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
+test('failures with nested key and custom message with Any matcher', function () use ($test_array) {
+    expect($test_array)->toHaveKey('d.bar', expect()->any(), 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('failures with plain key with dots', function () use ($test_array) {
     expect($test_array)->toHaveKey('missing.key.with.dots');
 })->throws(ExpectationFailedException::class, "Failed asserting that an array has the key 'missing.key.with.dots'");

tests/Features/Expect/toHaveKeys.php

@@ -14,10 +14,18 @@ test('failures', function () {
     expect(['a' => 1, 'b', 'c' => 'world', 'foo' => ['bar' => 'baz']])->toHaveKeys(['a', 'd', 'foo.bar', 'hello.world']);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(['a' => 1, 'b', 'c' => 'world', 'foo' => ['bar' => 'baz']])->toHaveKeys(['a', 'd', 'foo.bar', 'hello.world'], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('failures with multi-dimensional arrays', function () {
     expect(['a' => 1, 'b', 'c' => 'world', 'foo' => ['bar' => ['bir' => 'biz']]])->toHaveKeys(['a', 'd', 'foo' => ['bar' => 'bir'], 'hello.world']);
 })->throws(ExpectationFailedException::class);
 
+test('failures with multi-dimensional arrays and custom message', function () {
+    expect(['a' => 1, 'b', 'c' => 'world', 'foo' => ['bar' => ['bir' => 'biz']]])->toHaveKeys(['a', 'd', 'foo' => ['bar' => 'bir'], 'hello.world'], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(['a' => 1, 'b', 'c' => 'world', 'foo' => ['bar' => 'baz']])->not->toHaveKeys(['foo.bar', 'c', 'z']);
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toHaveLength.php

@@ -20,9 +20,13 @@ it('passes with *not*', function () {
 });
 
 it('properly fails with *not*', function () {
-    expect('pest')->not->toHaveLength(4);
+    expect('pest')->not->toHaveLength(4, 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
+it('fails', function () {
+    expect([1, 1.5, true, null])->toHaveLength(1);
 })->throws(ExpectationFailedException::class);
 
-it('fails', function ($value) {
+it('fails with message', function () {
-    expect($value)->toHaveLength(1);
+    expect([1, 1.5, true, null])->toHaveLength(1, 'oh no!');
-})->with([1, 1.5, true, null])->throws(BadMethodCallException::class);
+})->throws(ExpectationFailedException::class, 'oh no!');

tests/Features/Expect/toHaveProperties.php

@@ -17,6 +17,13 @@ test('failures', function () {
     expect($object)->toHaveProperties(['name', 'age']);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    $object = new stdClass();
+    $object->name = 'Jhon';
+
+    expect($object)->toHaveProperties(['name', 'age'], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     $object = new stdClass();
     $object->name = 'Jhon';

tests/Features/Expect/toHaveProperty.php

@@ -17,6 +17,14 @@ test('failures', function () use ($obj) {
     expect($obj)->toHaveProperty('bar');
 })->throws(ExpectationFailedException::class);
 
+test('failures with message', function () use ($obj) {
+    expect($obj)->toHaveProperty(name: 'bar', message: 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
+test('failures with message and Any matcher', function () use ($obj) {
+    expect($obj)->toHaveProperty('bar', expect()->any(), 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () use ($obj) {
     expect($obj)->not->toHaveProperty('foo');
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toMatch.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('Hello World')->toMatch('/^hello$/i');
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('Hello World')->toMatch('/^hello$/i', 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('Hello World')->not->toMatch('/^hello wo.*$/i');
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toMatchArray.php

@@ -24,6 +24,13 @@ test('failures', function () {
     ]);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect($this->user)->toMatchArray([
+        'name' => 'Not the same name',
+        'email' => 'enunomaduro@gmail.com',
+    ], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect($this->user)->not->toMatchArray([
         'id' => 1,

tests/Features/Expect/toMatchConstraint.php

@@ -11,6 +11,10 @@ test('failures', function () {
     expect(false)->toMatchConstraint(new IsTrue());
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(false)->toMatchConstraint(new IsTrue(), 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(true)->not->toMatchConstraint(new IsTrue());
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toMatchObject.php

@@ -36,6 +36,13 @@ test('failures', function () {
     ]);
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect($this->user)->toMatchObject([
+        'name' => 'Not the same name',
+        'email' => 'enunomaduro@gmail.com',
+    ], 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect($this->user)->not->toMatchObject([
         'id' => 1,

tests/Features/Expect/toStartWith.php

@@ -10,6 +10,10 @@ test('failures', function () {
     expect('username')->toStartWith('password');
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect('username')->toStartWith('password', 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect('username')->not->toStartWith('user');
 })->throws(ExpectationFailedException::class);

tests/Features/Expect/toThrow.php

@@ -79,6 +79,12 @@ test('failures 7', function () {
     })->toThrow(RuntimeException::class, 'expected message');
 })->throws(ExpectationFailedException::class);
 
+test('failures with custom message', function () {
+    expect(function () {
+        throw new RuntimeException('actual message');
+    })->toThrow(RuntimeException::class, 'expected message', 'oh no!');
+})->throws(ExpectationFailedException::class, 'oh no!');
+
 test('not failures', function () {
     expect(function () {
         throw new RuntimeException();