feature #50662 [FrameworkBundle] Add HttpClientAssertionsTrait whic…

…h provide shortcuts to assert HTTP calls was triggered (welcoMattic)

This PR was squashed before being merged into the 6.4 branch.

Discussion
----------

[FrameworkBundle] Add `HttpClientAssertionsTrait` which provide shortcuts to assert HTTP calls was triggered

| Q             | A
| ------------- | ---
| Branch?       | 6.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       |
| License       | MIT
| Doc PR        | symfony/symfony-docs#18970

This PR brings a new collection (to enhance) of assertions to help users to ensure some HTTP calls has been triggered during a Request processing.

## Example

An example is better than thousands words:

HttpClientAssertionsTest.php
```php
public function testHttpClientAssertions()
{
    $client = static::createClient();
    $client->enableProfiler();

    $client->request('GET', '/foo');

    $this->assertHttpClientRequest($client, 'symfony.http_client', 'https://symfony.com/');
    $this->assertHttpClientRequest($client, 'symfony.http_client', 'https://symfony.com/', 'POST', 'foo');
    $this->assertHttpClientRequest($client, 'symfony.http_client', 'https://symfony.com/', 'POST', ['foo' => 'bar']);
    $this->assertHttpClientRequest($client, 'symfony.http_client', 'https://symfony.com/', 'POST', ['foo' => 'bar']);
    $this->assertNotHttpClientRequest($client, 'symfony.http_client', 'https://laravel.com');

    $this->assertHttpClientRequestCount($client, 'symfony.http_client', 5);
}
```

FooController.php
```php
public function index(HttpClientInterface $symfonyHttpClient)
{
    $symfonyHttpClient->request('GET', '/');
    $symfonyHttpClient->request('POST', '/', ['body' => 'foo']);
    $symfonyHttpClient->request('POST', '/', ['body' => ['foo' => 'bar']]);
    $symfonyHttpClient->request('POST', '/', ['json' => ['foo' => 'bar']]);
    $symfonyHttpClient->request('GET', '/doc/current/index.html');

    return new Response();
}
```

http_client.yaml
```yaml
framework:
    http_client:
        scoped_clients:
            symfony.http_client:
                base_uri: 'https://symfony.com'
```

This is a first try to improve DX in test, to allow users to assert more complex things (here it's HTTP calls, but I think also about adding assertions on logs for example).

## Todo

- [x] Write doc

Commits
-------

59f5eec [FrameworkBundle] Add `HttpClientAssertionsTrait` which provide shortcuts to assert HTTP calls was triggered

src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 6.4
 ---
 
+ * Add `HttpClientAssertionsTrait`
  * Add `AbstractController::renderBlock()` and `renderBlockView()`
  * Add native return type to `Translator` and to `Application::reset()`
  * Deprecate the integration of Doctrine annotations, either uninstall the `doctrine/annotations` package or disable the integration by setting `framework.annotations` to `false`

src/Symfony/Bundle/FrameworkBundle/Test/HttpClientAssertionsTrait.php

@@ -0,0 +1,134 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Test;
+
+use Symfony\Bundle\FrameworkBundle\KernelBrowser;
+use Symfony\Component\HttpClient\DataCollector\HttpClientDataCollector;
+
+/*
+ * @author Mathieu Santostefano <msantostefano@protonmail.com>
+ */
+
+trait HttpClientAssertionsTrait
+{
+    public static function assertHttpClientRequest(string $expectedUrl, string $expectedMethod = 'GET', string|array $expectedBody = null, array $expectedHeaders = [], string $httpClientId = 'http_client'): void
+    {
+        /** @var KernelBrowser $client */
+        $client = static::getClient();
+
+        if (!($profile = $client->getProfile())) {
+            static::fail('The Profiler must be enabled for the current request. Please ensure to call "$client->enableProfiler()" before making the request.');
+        }
+
+        /** @var HttpClientDataCollector $httpClientDataCollector */
+        $httpClientDataCollector = $profile->getCollector('http_client');
+        $expectedRequestHasBeenFound = false;
+
+        if (!\array_key_exists($httpClientId, $httpClientDataCollector->getClients())) {
+            static::fail(sprintf('HttpClient "%s" is not registered.', $httpClientId));
+        }
+
+        foreach ($httpClientDataCollector->getClients()[$httpClientId]['traces'] as $trace) {
+            if (($expectedUrl !== $trace['info']['url'] && $expectedUrl !== $trace['url'])
+                || $expectedMethod !== $trace['method']
+            ) {
+                continue;
+            }
+
+            if (null !== $expectedBody) {
+                $actualBody = null;
+
+                if (null !== $trace['options']['body'] && null === $trace['options']['json']) {
+                    $actualBody = \is_string($trace['options']['body']) ? $trace['options']['body'] : $trace['options']['body']->getValue(true);
+                }
+
+                if (null === $trace['options']['body'] && null !== $trace['options']['json']) {
+                    $actualBody = $trace['options']['json']->getValue(true);
+                }
+
+                if (!$actualBody) {
+                    continue;
+                }
+
+                if ($expectedBody === $actualBody) {
+                    $expectedRequestHasBeenFound = true;
+
+                    if (!$expectedHeaders) {
+                        break;
+                    }
+                }
+            }
+
+            if ($expectedHeaders) {
+                $actualHeaders = $trace['options']['headers'] ?? [];
+
+                foreach ($actualHeaders as $headerKey => $actualHeader) {
+                    if (\array_key_exists($headerKey, $expectedHeaders)
+                        && $expectedHeaders[$headerKey] === $actualHeader->getValue(true)
+                    ) {
+                        $expectedRequestHasBeenFound = true;
+                        break 2;
+                    }
+                }
+            }
+
+            $expectedRequestHasBeenFound = true;
+            break;
+        }
+
+        self::assertTrue($expectedRequestHasBeenFound, 'The expected request has not been called: "'.$expectedMethod.'" - "'.$expectedUrl.'"');
+    }
+
+    public function assertNotHttpClientRequest(string $unexpectedUrl, string $expectedMethod = 'GET', string $httpClientId = 'http_client'): void
+    {
+        /** @var KernelBrowser $client */
+        $client = static::getClient();
+
+        if (!$profile = $client->getProfile()) {
+            static::fail('The Profiler must be enabled for the current request. Please ensure to call "$client->enableProfiler()" before making the request.');
+        }
+
+        /** @var HttpClientDataCollector $httpClientDataCollector */
+        $httpClientDataCollector = $profile->getCollector('http_client');
+        $unexpectedUrlHasBeenFound = false;
+
+        if (!\array_key_exists($httpClientId, $httpClientDataCollector->getClients())) {
+            static::fail(sprintf('HttpClient "%s" is not registered.', $httpClientId));
+        }
+
+        foreach ($httpClientDataCollector->getClients()[$httpClientId]['traces'] as $trace) {
+            if (($unexpectedUrl === $trace['info']['url'] || $unexpectedUrl === $trace['url'])
+                && $expectedMethod === $trace['method']
+            ) {
+                $unexpectedUrlHasBeenFound = true;
+                break;
+            }
+        }
+
+        self::assertFalse($unexpectedUrlHasBeenFound, sprintf('Unexpected URL called: "%s" - "%s"', $expectedMethod, $unexpectedUrl));
+    }
+
+    public static function assertHttpClientRequestCount(int $count, string $httpClientId = 'http_client'): void
+    {
+        /** @var KernelBrowser $client */
+        $client = static::getClient();
+
+        if (!($profile = $client->getProfile())) {
+            static::fail('The Profiler must be enabled for the current request. Please ensure to call "$client->enableProfiler()" before making the request.');
+        }
+
+        /** @var HttpClientDataCollector $httpClientDataCollector */
+        $httpClientDataCollector = $profile->getCollector('http_client');
+
+        self::assertCount($count, $httpClientDataCollector->getClients()[$httpClientId]['traces']);
+    }
+}

src/Symfony/Bundle/FrameworkBundle/Test/WebTestAssertionsTrait.php

@@ -15,4 +15,5 @@ trait WebTestAssertionsTrait
 {
     use BrowserKitAssertionsTrait;
     use DomCrawlerAssertionsTrait;
+    use HttpClientAssertionsTrait;
 }

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/Bundle/TestBundle/Controller/HttpClientController.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Controller;
+
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+class HttpClientController
+{
+    public function index(HttpClientInterface $httpClient, HttpClientInterface $symfonyHttpClient): Response
+    {
+        $httpClient->request('GET', 'https://symfony.com/');
+
+        $symfonyHttpClient->request('GET', '/');
+        $symfonyHttpClient->request('POST', '/', ['body' => 'foo']);
+        $symfonyHttpClient->request('POST', '/', ['body' => ['foo' => 'bar']]);
+        $symfonyHttpClient->request('POST', '/', ['json' => ['foo' => 'bar']]);
+        $symfonyHttpClient->request('POST', '/', [
+            'headers' => ['X-Test-Header' => 'foo'],
+            'json' => ['foo' => 'bar'],
+        ]);
+        $symfonyHttpClient->request('GET', '/doc/current/index.html');
+
+        return new Response();
+    }
+}

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/Bundle/TestBundle/Resources/config/routing.yml

@@ -61,6 +61,10 @@ send_email:
     path:     /send_email
     defaults: { _controller: Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Controller\EmailController::indexAction }
 
+http_client_call:
+    path:     /http_client_call
+    defaults: { _controller: Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Controller\HttpClientController::index }
+
 uid:
     resource: "../../Controller/UidController.php"
     type: "annotation"

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/Bundle/TestBundle/Tests/MockClientCallback.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Tests;
+
+use Symfony\Component\HttpClient\Response\MockResponse;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+class MockClientCallback
+{
+    public function __invoke(string $method, string $url, array $options = []): ResponseInterface
+    {
+        return new MockResponse('foo');
+    }
+}

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/HttpClientTest.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Tests\Functional;
+
+class HttpClientTest extends AbstractWebTestCase
+{
+    public function testHttpClientAssertions()
+    {
+        $client = $this->createClient(['test_case' => 'HttpClient', 'root_config' => 'config.yml', 'debug' => true]);
+        $client->enableProfiler();
+        $client->request('GET', '/http_client_call');
+
+        $this->assertHttpClientRequest('https://symfony.com/');
+        $this->assertHttpClientRequest('https://symfony.com/', httpClientId: 'symfony.http_client');
+        $this->assertHttpClientRequest('https://symfony.com/', 'POST', 'foo', httpClientId: 'symfony.http_client');
+        $this->assertHttpClientRequest('https://symfony.com/', 'POST', ['foo' => 'bar'], httpClientId: 'symfony.http_client');
+        $this->assertHttpClientRequest('https://symfony.com/', 'POST', ['foo' => 'bar'], httpClientId: 'symfony.http_client');
+        $this->assertHttpClientRequest('https://symfony.com/', 'POST', ['foo' => 'bar'], ['X-Test-Header' => 'foo'], 'symfony.http_client');
+        $this->assertHttpClientRequest('https://symfony.com/doc/current/index.html', httpClientId: 'symfony.http_client');
+        $this->assertNotHttpClientRequest('https://laravel.com', httpClientId: 'symfony.http_client');
+
+        $this->assertHttpClientRequestCount(6, 'symfony.http_client');
+    }
+}

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/HttpClient/bundles.php

@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\TestBundle;
+
+return [
+    new FrameworkBundle(),
+    new TestBundle(),
+];

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/HttpClient/config.yml

@@ -0,0 +1,12 @@
+imports:
+    - { resource: ../config/default.yml }
+    - { resource: services.yml }
+
+framework:
+    http_method_override: false
+    profiler: ~
+    http_client:
+        mock_response_factory: Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Tests\MockClientCallback
+        scoped_clients:
+            symfony.http_client:
+                base_uri: 'https://symfony.com'

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/HttpClient/routing.yml

@@ -0,0 +1,2 @@
+_emailtest_bundle:
+    resource: '@TestBundle/Resources/config/routing.yml'

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/HttpClient/services.yml

@@ -0,0 +1,9 @@
+services:
+    _defaults:
+        public: true
+
+    Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Controller\HttpClientController:
+        tags: ['controller.service_arguments']
+
+    Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Tests\MockClientCallback:
+        class: Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\Tests\MockClientCallback