Merge branch 'master' into method-match

src/Expectation.php

@@ -219,6 +219,26 @@ final class Expectation
 
         return $this;
     }
+  
+    /**
+     * It skips the tests in the callback if the condition is not truthy.
+     *
+     * @param Closure|bool|string $condition
+     */
+    public function when($condition, callable $callback): Expectation
+    {
+        $condition = is_callable($condition)
+            ? $condition
+            : function () use ($condition) {
+                return $condition;
+            };
+
+        if ($condition()) {
+            $callback(new self($this->value));
+        }
+
+        return $this;
+    }
 
     /**
      * Asserts that two variables have the same type and

tests/.snapshots/success.txt

@@ -492,6 +492,15 @@
   ✓ closure missing parameter
   ✓ closure missing type-hint
 
+   PASS  Tests\Features\Expect\when
+  ✓ 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\Helpers
   ✓ it can set/get properties on $this
   ✓ it throws error if property do not exist
@@ -692,5 +701,5 @@
   ✓ it is a test
   ✓ it uses correct parent class
 
-  Tests:  4 incompleted, 9 skipped, 456 passed
+  Tests:  4 incompleted, 9 skipped, 463 passed
   

tests/Features/Expect/when.php

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