Support for argument expectations in Stubs

src/Stub.php

@@ -583,10 +583,19 @@ protected static function bindParameters($mock, $params)
             if ($reflectionClass->hasMethod($param)) {
                 if ($value instanceof StubMarshaler) {
                     $marshaler = $value;
-                    $mock
-                        ->expects($marshaler->getMatcher())
-                        ->method($param)
-                        ->will(new ReturnCallback($marshaler->getValue()));
+                    $methodArguments = $marshaler->getArguments();
+                    if ($methodArguments !== null) {
+                        $mock
+                            ->expects($marshaler->getMatcher())
+                            ->method($param)
+                            ->with(...$methodArguments)
+                            ->will(new ReturnCallback($marshaler->getValue()));
+                    } else {
+                        $mock
+                            ->expects($marshaler->getMatcher())
+                            ->method($param)
+                            ->will(new ReturnCallback($marshaler->getValue()));
+                    }
                 } elseif ($value instanceof \Closure) {
                     $mock
                         ->expects(new AnyInvokedCount)

src/Stub/StubMarshaler.php

@@ -13,6 +13,8 @@ class StubMarshaler
 
     private $methodValue;
 
+    private $methodArguments = null;
+
     public function __construct(InvocationOrder $matcher, $value)
     {
         $this->methodMatcher = $matcher;
@@ -28,4 +30,39 @@ public function getValue()
     {
         return $this->methodValue;
     }
+
+    /**
+     * @return array|null expected method arguments, null makes it skip the check
+     */
+    public function getArguments()
+    {
+        return $this->methodArguments;
+    }
+
+    /**
+     * Checks if a method is called with the specified arguments
+     *
+     * If the method is invoked with different arguments, an exception will be thrown.
+     *
+     * ```php
+     * <?php
+     * use \Codeception\Stub\Expected;
+     *
+     * $user = $this->make('User', [
+     *      'setName' => Expected::once()->with('Davert')
+     * ]);
+     * $user->setName('Davert');
+     * ?>
+     * ```
+     *
+     * @see \PHPUnit\Framework\MockObject\Builder\InvocationMocker::with
+     * @param array ...$arguments
+     * @return StubMarshaler
+     */
+    public function with(...$arguments)
+    {
+        $this->methodArguments = $arguments;
+
+        return $this;
+    }
 }

tests/StubTest.php

@@ -374,6 +374,55 @@ public function testConsecutive()
         $this->assertNull($dummy->helloWorld());
     }
 
+    public static function argumentsMatchProvider()
+    {
+        return array(
+            array(Stub\Expected::once()->with(), []),
+            array(Stub\Expected::once()->with('it is me'), ['it is me']),
+            array(Stub\Expected::once()->with(new PHPUnit\Framework\Constraint\IsAnything), ['it is me']),
+            array(Stub\Expected::once()->with('it is me', 'and you'), ['it is me', 'and you']),
+        );
+    }
+
+    /**
+     * @dataProvider argumentsMatchProvider
+     */
+    public function testWithArgumentsMatch($matcher, $arguments)
+    {
+        $dummy = Stub::make('DummyClass', array('helloWorld' => $matcher));
+
+        $this->assertNull($dummy->helloWorld(...$arguments));
+    }
+
+    public static function argumentsMismatchProvider()
+    {
+        return array(
+            array(Stub\Expected::once()->with('it is me'), [], 'Parameter count for invocation DummyClass::helloWorld() is too low.'),
+            array(Stub\Expected::once()->with('it is me'), ['it is you'], 'Parameter 0 for invocation DummyClass::helloWorld(\'it is you\') does not match expected value.'),
+            array(Stub\Expected::once()->with('it is me', 'and you'), ['it is me'], 'Parameter count for invocation DummyClass::helloWorld(\'it is me\') is too low.'),
+        );
+    }
+
+    /**
+     * @dataProvider argumentsMismatchProvider
+     */
+    public function testWithArgumentsMismatch($matcher, $arguments, $failMessage)
+    {
+        $dummy = Stub::make('DummyClass', array('helloWorld' => $matcher));
+
+        try {
+            $dummy->helloWorld(...$arguments);
+            $this->fail('Expected exception');
+        } catch (\Exception $e) {
+            if ($e->getMessage() === 'Expected exception') {
+                $this->fail('Expected exception');
+            }
+            $this->assertStringContainsString($failMessage, $e->getMessage());
+        }
+
+        $this->resetMockObjects();
+    }
+
     public function testStubPrivateProperties()
     {
         $tester = Stub::construct(