feat: add naming for expecations (#30)

Author: nivseb

README.md

@@ -190,6 +190,26 @@ return an empty response with the status code 200.
 Advance
 -------
 
+### Naming Expectations
+
+If you have to add many expectations in the same test szenario, it can be difficult to differentiate between that
+expectations. For that case it is possible to give each expectation a custom name. By default,
+the name is build from method and path.
+
+```php
+    use Nivseb\PhpMockServerConnector\PhpUnit\UseMockServer;
+    use Nivseb\PhpMockServerConnector\PhpUnit\MockServerEndpoint;
+    use PHPUnit\Framework\TestCase;
+    use GuzzleHttp\Client;
+    
+    $mockServer = new MockServerEndpoint('/');
+    $mockServer->allows('GET', '/records/1')->andReturn(200);  // result to name `GET /records/1`
+    $mockServer->allows('GET', '/records/2')->name('Load Record 2')->andReturn(200); // result to name `Load Record 2`
+    $mockServer->allows('GET', '/records/3')->name('Load Record 3')->andReturn(200); // result to name `Load Record 3`
+```
+
+### Duplicate Expectation
+
 In some cases you expect nearly same request twice, but only with a little change in the response or request. In that case,
 you can build a new expectation from an existing and add your changes to the new one. this example shows a definition that
 expect 2 requests and answer the first one with a 200 response and the second call to with a 304 response.
@@ -205,7 +225,6 @@ expect 2 requests and answer the first one with a 200 response and the second ca
     $mockServer->duplicate($firstExpectation)->andReturn(304);
 ```
 
-
 Example
 -------
 

src/Exception/UnsuccessfulVerificationException.php

@@ -14,6 +14,10 @@ public function __construct(
         public ResponseInterface $response,
         ?Throwable $previous = null
     ) {
+        $message .= ' for expectation `';
+        $message .= $expectation->expectation->getName();
+        $message .= '`';
+
         parent::__construct($message, previous: $previous);
     }
 }

src/Expectation/PendingExpectation.php

@@ -38,7 +38,10 @@ public function __destruct()
 
     public function __clone(): void
     {
-        $this->expectation       = clone $this->expectation;
+        $this->expectation = clone $this->expectation;
+        if ($this->expectation->name) {
+            $this->expectation->name = null;
+        }
         $this->remoteExpectation = null;
     }
 
@@ -57,7 +60,7 @@ public function run(): void
      *
      * @throws AlreadyExpectedExpectationException
      */
-    public function andReturn(int $statusCode, null|array|string $responseBody = null, ?array $headers = null): static
+    public function andReturn(int $statusCode, array|string|null $responseBody = null, ?array $headers = null): static
     {
         if ($this->remoteExpectation) {
             throw new AlreadyExpectedExpectationException($this->remoteExpectation);
@@ -174,4 +177,18 @@ public function once(): static
     {
         return $this->times(1);
     }
+
+    /**
+     * @throws AlreadyExpectedExpectationException
+     */
+    public function name(string $expectationName): static
+    {
+        if ($this->remoteExpectation) {
+            throw new AlreadyExpectedExpectationException($this->remoteExpectation);
+        }
+
+        $this->expectation->name = $expectationName;
+
+        return $this;
+    }
 }

src/Server/MockServerEndpoint.php

@@ -34,7 +34,7 @@ public function registerExpectation(RemoteExpectation $expectation): void
     }
 
     /**
-     * @return array<string, MockServerEndpoint>
+     * @return array<string, RemoteExpectation>
      */
     public function getExpectations(): array
     {

src/Structs/MockServerExpectation.php

@@ -13,13 +13,19 @@ public function __construct(
         public readonly string $method,
         public readonly string $url,
         public int $responseStatusCode = 200,
-        public null|array|string $responseBody = null,
+        public array|string|null $responseBody = null,
         public ?array $responseHeaders = null,
         public int $atLeast = 1,
         public int $atMost = 1,
         public ?array $pathParameters = null,
         public ?array $queryParameters = null,
         public ?array $requestHeaders = null,
-        public null|array|string $requestBody = null,
+        public array|string|null $requestBody = null,
+        public ?string $name = null,
     ) {}
+
+    public function getName(): string
+    {
+        return $this->name ?: $this->method.' '.$this->url;
+    }
 }

tests/Unit/ConnectorTest.php

@@ -306,7 +306,7 @@ protected function buildClient(string $mockServerUrl): Client
             ->toThrow(
                 function (UnsuccessfulVerificationException $exception) use ($remoteExpectation, $response): void {
                     expect($exception->getMessage())
-                        ->toBe('Request not found exactly 1 times')
+                        ->toBe('Request not found exactly 1 times for expectation `METHOD /path`')
                         ->and($exception->expectation)->toBe($remoteExpectation)
                         ->and($exception->response)->toBe($response);
                 }
@@ -376,7 +376,7 @@ protected function buildClient(string $mockServerUrl): Client
             ->toThrow(
                 function (UnsuccessfulVerificationException $exception) use ($remoteExpectation, $response): void {
                     expect($exception->getMessage())
-                        ->toBe('Request not found exactly 1 times')
+                        ->toBe('Request not found exactly 1 times for expectation `METHOD /path`')
                         ->and($exception->expectation)->toBe($remoteExpectation)
                         ->and($exception->response)->toBe($response);
                 }