feat: adds unless expectation

src/Expectation.php

@@ -221,6 +221,23 @@ public function match($subject, array $expressions): Expectation
         return $this;
     }
 
+    /**
+     * Apply the callback if the given "condition" is falsy.
+     *
+     * @param  (callable(): bool)|bool $condition
+     * @param callable(Expectation<TValue>): mixed $callback
+     */
+    public function unless($condition, callable $callback): Expectation
+    {
+        $condition = is_callable($condition)
+            ? $condition
+            : static function () use ($condition): mixed {
+                return $condition;
+            };
+
+        return $this->when(!$condition(), $callback);
+    }
+
     /**
      * Apply the callback if the given "condition" is truthy.
      *
@@ -236,7 +253,7 @@ public function when($condition, callable $callback): Expectation
             };
 
         if ($condition()) {
-            $callback(new self($this->value));
+            $callback($this->and($this->value));
         }
 
         return $this;

tests/.snapshots/success.txt

@@ -497,6 +497,15 @@
   ✓ closure missing parameter
   ✓ closure missing type-hint
 
+   PASS  Tests\Features\Expect\unless
+  ✓ it pass
+  ✓ it failures
+  ✓ it runs with truthy
+  ✓ it skips with falsy
+  ✓ it runs with truthy closure condition
+  ✓ it skips with falsy closure condition
+  ✓ it can be used in higher order tests
+
    PASS  Tests\Features\Expect\when
   ✓ it pass
   ✓ it failures
@@ -706,5 +715,5 @@
   ✓ it is a test
   ✓ it uses correct parent class
 
-  Tests:  4 incompleted, 9 skipped, 468 passed
+  Tests:  4 incompleted, 9 skipped, 475 passed
 

tests/Features/Expect/unless.php

@@ -0,0 +1,101 @@
+<?php
+
+use PHPUnit\Framework\ExpectationFailedException;
+
+beforeEach(function () {
+    $this->unlessObject = new stdClass();
+    $this->unlessObject->trueValue = true;
+    $this->unlessObject->foo = 'foo';
+});
+
+it('pass', function () {
+    expect('foo')
+        ->unless(
+            true,
+            function ($value) {
+                return $value->toEqual('bar');
+            }
+        )
+        ->toEqual('foo');
+
+    expect(static::getCount())->toBe(1);
+});
+
+it('failures', function () {
+    expect('foo')
+        ->unless(
+            false,
+            function ($value) {
+                return $value->toBeTrue();
+            }
+        )
+        ->toEqual('foo');
+})->throws(ExpectationFailedException::class, 'is true');
+
+it('runs with truthy', function () {
+    expect($this->unlessObject)
+        ->unless(
+            0,
+            function ($value) {
+                return $value->trueValue->toBeTrue();
+            }
+        )
+        ->foo->toEqual('foo');
+
+    expect(static::getCount())->toBe(2);
+});
+
+it('skips with falsy', function () {
+    expect($this->unlessObject)
+        ->unless(
+            1,
+            function ($value) {
+                return $value->trueValue->toBeFalse(); // fails
+            }
+        )
+        ->unless(
+            true,
+            function ($value) {
+                return $value->trueValue->toBeFalse(); // fails
+            }
+        )
+        ->foo->toEqual('foo');
+
+    expect(static::getCount())->toBe(1);
+});
+
+it('runs with truthy closure condition', function () {
+    expect($this->unlessObject)
+        ->unless(
+            function () { return '0'; },
+            function ($value) {
+                return $value->trueValue->toBeTrue();
+            }
+        )
+        ->foo->toEqual('foo');
+
+    expect(static::getCount())->toBe(2);
+});
+
+it('skips with falsy closure condition', function () {
+    expect($this->unlessObject)
+        ->unless(
+            function () { return '1'; },
+            function ($value) {
+                return $value->trueValue->toBeFalse(); // fails
+            }
+        )
+        ->foo->toEqual('foo');
+
+    expect(static::getCount())->toBe(1);
+});
+
+it('can be used in higher order tests')
+    ->expect(true)
+    ->unless(
+        function () { return false; },
+        function ($value) {
+            return $value->toBeFalse();
+        }
+    )
+    ->throws(ExpectationFailedException::class, 'true is false');