Add SqlStatementExpectations and enhance MockClientBuilder

Author: rybakit

README.md

@@ -39,7 +39,7 @@ final class MyTest extends TestCase
 {
     protected function getClient() : Client
     {
-        // you have to implement this method
+        // TODO: Implement getClient() method.
     }
 
     // ...
@@ -162,7 +162,7 @@ public function testChangeUserPassword() : void
 
 ```php
 /**
- * @requires Tarantool >= 2.3.2 
+ * @requires Tarantool ^2.3.2 
  */
 public function testPrepareCreatesPreparedStatement() : void
 {
@@ -212,6 +212,32 @@ public function testGetSpaceIsCached() : void
 }
 ```
 
+In order to check SQL statements, use the `Tarantool\PhpUnit\Expectation\SqlStatementExpectations` trait,
+which contains the following methods:
+
+ * `expectSqlStatementToBeExecuted(int $count) : void`
+ * `expectSqlStatementToBeExecutedAtLeast(int $count) : void`
+ * `expectSqlStatementToBeExecutedAtMost(int $count) : void`
+ * `expectSqlStatementToBeExecutedOnce() : void`
+ * `expectSqlStatementToBeNeverCalled() : void`
+ * `expectSqlStatementToBeExecutedAtLeastOnce() : void`
+ * `expectSqlStatementToBeExecutedAtMostOnce() : void`
+
+Usage example:
+
+```php
+public function testCloseDeallocatesPreparedStatement() : void
+{
+    $stmt = $this->client->prepare('SELECT ?');
+
+    $this->expectSqlStatementToBeExecutedOnce();
+    $stmt->close();
+}
+```
+
+To enable all the above expectation methods in one go, use the `Tarantool\PhpUnit\Expectation\Expectations` trait,
+or extend the `Tarantool\PhpUnit\TestCase` class.
+
 
 ## Mocking
 
@@ -249,23 +275,20 @@ public function testFoo() : void
 
 To simulate specific scenarios, such as establishing a connection to a server
 or returning specific responses in a specific order from the server, use the facilities
-of the `MockClientBuilder` class. For example, to simulate `PING` request/response:
+of the `MockClientBuilder` class. For example, to simulate the `PING` request:
 
 ```php
 use Tarantool\Client\Request\PingRequest;
-use Tarantool\PhpUnit\Client\DummyFactory;
 use Tarantool\PhpUnit\TestCase;
 
 final class MyTest extends TestCase
 {
     public function testFoo() : void
     {
         $mockClient = $this->getMockClientBuilder()
-            ->shouldHandle(
-                new PingRequest(),
-                DummyFactory::createEmptyResponse()
-            )->build();
-    
+            ->shouldSend(new PingRequest())
+            ->build();
+
         // ...
     }
 
@@ -285,8 +308,10 @@ final class MyTest extends TestCase
     public function testFoo() : void
     {
         $mockClient = $this->getMockClientBuilder()
-            ->shouldHandle(
-                RequestTypes::EVALUATE,
+            ->shouldSend(
+                RequestTypes::EVALUATE, 
+                RequestTypes::EVALUATE
+            )->willReceive(
                 DummyFactory::createResponseFromData([2]),
                 DummyFactory::createResponseFromData([3])
             )->build();
@@ -297,6 +322,16 @@ final class MyTest extends TestCase
     // ...
 }
 ```
+The above example can be simplified to:
+
+```php
+$mockClient = $this->getMockClientBuilder()
+    ->shouldHandle(
+        RequestTypes::EVALUATE,
+        DummyFactory::createResponseFromData([2]),
+        DummyFactory::createResponseFromData([3])
+    )->build();
+```
 
 Besides, the builder allows setting custom `Connection` and `Packer` instances:
 

psalm.xml

@@ -19,6 +19,7 @@
             <errorLevel type="suppress">
                 <referencedMethod name="PHPUnit\Framework\MockObject\Builder\InvocationMocker::method" />
                 <referencedMethod name="PHPUnit\Framework\MockObject\Builder\InvocationMocker::with" />
+                <referencedMethod name="PHPUnit\Framework\MockObject\Builder\InvocationMocker::withConsecutive" />
                 <referencedMethod name="PHPUnit\Framework\MockObject\Builder\InvocationMocker::willReturn" />
                 <referencedMethod name="PHPUnit\Framework\MockObject\Builder\InvocationMocker::willReturnOnConsecutiveCalls" />
                 <referencedMethod name="PHPUnit\Framework\TestCase::__construct" />

src/Client/MockClientBuilder.php

@@ -28,19 +28,25 @@ final class MockClientBuilder
     /** @var TestCase */
     private $testCase;
 
-    /** @var \SplObjectStorage<object, array<int, Response>> */
+    /** @var array<int, Request>|null */
     private $requests;
 
+    /** @var array<int, Response> */
+    private $responses;
+
     /** @var Connection|null */
     private $connection;
 
     /** @var Packer|null */
     private $packer;
 
+    /** @var int|null */
+    private $shouldBeCalledTimes = null;
+
     public function __construct(TestCase $testCase)
     {
         $this->testCase = $testCase;
-        $this->requests = new \SplObjectStorage();
+        $this->responses = [DummyFactory::createEmptyResponse()];
     }
 
     public static function buildDefault() : Client
@@ -52,17 +58,41 @@ public static function buildDefault() : Client
         return $self->build();
     }
 
+    /**
+     * @param Request|Constraint|int $request
+     * @param Request|Constraint|int ...$requests
+     */
+    public function shouldSend($request, ...$requests) : self
+    {
+        $this->requests = [];
+        foreach (\func_get_args() as $arg) {
+            $this->requests[] = \is_int($arg) ? new IsRequestType($arg) : $arg;
+        }
+
+        $this->shouldBeCalledTimes = \count($this->requests);
+
+        return $this;
+    }
+
     /**
      * @param Request|Constraint|int $request
      * @param Response ...$responses
      */
     public function shouldHandle($request, ...$responses) : self
     {
-        if (\is_int($request)) {
-            $request = new IsRequestType($request);
+        $this->shouldSend($request);
+        $this->willReceive(...$responses);
+
+        if ($responses) {
+            $this->shouldBeCalledTimes = \count($responses);
         }
 
-        $this->requests->attach($request, $responses);
+        return $this;
+    }
+
+    public function willReceive(Response $response, Response ...$responses) : self
+    {
+        $this->responses = \func_get_args();
 
         return $this;
     }
@@ -99,23 +129,18 @@ private function createHandler() : MockObject
         $packer = $this->createPacker();
         $handler->method('getPacker')->willReturn($packer);
 
-        $defaultResponse = DummyFactory::createEmptyResponse();
+        $handleMocker = null !== $this->shouldBeCalledTimes
+            ? $handler->expects(TestCase::exactly($this->shouldBeCalledTimes))->method('handle')
+            : $handler->method('handle');
 
-        if (!$this->requests->count()) {
-            $handler->method('handle')->willReturn($defaultResponse);
-
-            return $handler;
+        if ($this->requests) {
+            $handleMocker->withConsecutive(...array_chunk($this->requests, 1));
         }
 
-        foreach ($this->requests as $request) {
-            if (!$responses = $this->requests->getInfo()) {
-                $handler->method('handle')->with($request)->willReturn($defaultResponse);
-                continue;
-            }
-
-            $handler->expects(TestCase::exactly(\count($responses)))
-                ->method('handle')->with($request)
-                ->willReturnOnConsecutiveCalls(...$responses);
+        if (1 === \count($this->responses)) {
+            $handleMocker->willReturn($this->responses[0]);
+        } else {
+            $handleMocker->willReturnOnConsecutiveCalls(...$this->responses);
         }
 
         return $handler;

src/Expectation/Expectations.php

@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * This file is part of the tarantool/phpunit-extras package.
+ *
+ * (c) Eugene Leonovich <gen.work@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Tarantool\PhpUnit\Expectation;
+
+trait Expectations
+{
+    use RequestExpectations;
+    use SqlStatementExpectations;
+}

src/Expectation/ExpressionContext/SqlStatementCountContext.php

@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * This file is part of the tarantool/phpunit-extras package.
+ *
+ * (c) Eugene Leonovich <gen.work@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Tarantool\PhpUnit\Expectation\ExpressionContext;
+
+use PHPUnitExtras\Expectation\ExpressionContext;
+use Tarantool\Client\Client;
+
+final class SqlStatementCountContext implements ExpressionContext
+{
+    /** @var Client */
+    private $client;
+
+    /** @var string */
+    private $expression;
+
+    /** @var int */
+    private $initialValue;
+
+    private function __construct(Client $client, string $expression)
+    {
+        $this->client = $client;
+        $this->expression = $expression;
+        $this->initialValue = $this->getValue();
+    }
+
+    public static function exactly(Client $client, int $count) : self
+    {
+        return new self($client, "new_count === old_count + $count");
+    }
+
+    public static function atLeast(Client $client, int $count) : self
+    {
+        return new self($client, "new_count >= old_count + $count");
+    }
+
+    public static function atMost(Client $client, int $count) : self
+    {
+        return new self($client, "new_count <= old_count + $count");
+    }
+
+    public function getExpression() : string
+    {
+        return $this->expression;
+    }
+
+    public function getValues() : array
+    {
+        return [
+            'old_count' => $this->initialValue,
+            'new_count' => $this->getValue(),
+        ];
+    }
+
+    private function getValue() : int
+    {
+        return $this->client->evaluate('return box.info.sql().cache.stmt_count')[0];
+    }
+}

src/Expectation/SqlStatementExpectations.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * This file is part of the tarantool/phpunit-extras package.
+ *
+ * (c) Eugene Leonovich <gen.work@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Tarantool\PhpUnit\Expectation;
+
+use PHPUnitExtras\Expectation\ExpressionExpectation;
+use Tarantool\Client\Client;
+use Tarantool\PhpUnit\Expectation\ExpressionContext\SqlStatementCountContext;
+
+trait SqlStatementExpectations
+{
+    public function expectSqlStatementToBeExecuted(int $count) : void
+    {
+        $context = SqlStatementCountContext::exactly($this->getClient(), $count);
+        $this->expect(new ExpressionExpectation($context));
+    }
+
+    public function expectSqlStatementToBeExecutedAtLeast(int $count) : void
+    {
+        $context = SqlStatementCountContext::atLeast($this->getClient(), $count);
+        $this->expect(new ExpressionExpectation($context));
+    }
+
+    public function expectSqlStatementToBeExecutedAtMost(int $count) : void
+    {
+        $context = SqlStatementCountContext::atMost($this->getClient(), $count);
+        $this->expect(new ExpressionExpectation($context));
+    }
+
+    public function expectSqlStatementToBeExecutedOnce() : void
+    {
+        $this->expectSqlStatementToBeExecuted(1);
+    }
+
+    public function expectSqlStatementToBeNeverCalled() : void
+    {
+        $this->expectSqlStatementToBeExecuted(0);
+    }
+
+    public function expectSqlStatementToBeExecutedAtLeastOnce() : void
+    {
+        $this->expectSqlStatementToBeExecutedAtLeast(1);
+    }
+
+    public function expectSqlStatementToBeExecutedAtMostOnce() : void
+    {
+        $this->expectSqlStatementToBeExecutedAtMost(1);
+    }
+
+    abstract protected function getClient() : Client;
+}

src/TestCase.php

@@ -16,11 +16,11 @@
 use PHPUnitExtras\TestCase as BaseTestCase;
 use Tarantool\PhpUnit\Annotation\Annotations;
 use Tarantool\PhpUnit\Client\ClientMocking;
-use Tarantool\PhpUnit\Expectation\RequestExpectations;
+use Tarantool\PhpUnit\Expectation\Expectations;
 
 abstract class TestCase extends BaseTestCase
 {
     use ClientMocking;
     use Annotations;
-    use RequestExpectations;
+    use Expectations;
 }