@@ -2282,7 +2282,26 @@ when making HTTP requests you might face errors at transport level.
22822282
22832283That's why it's useful to test how your application behaves in case of a transport
22842284error.:class: `Symfony\\ Component\\ HttpClient\\ Response\\ MockResponse ` allows
2285- you to do so, by yielding the exception from its body::
2285+ you to do so in multiple ways.
2286+
2287+ In order to test errors that occur before headers have been received,
2288+ set the ``error `` option value when creating the ``MockResponse ``.
2289+ Transport errors of this kind occur, for example, when a host name
2290+ cannot be resolved or the host was unreachable. The
2291+ ``TransportException `` will be thrown as soon as a method like
2292+ ``getStatusCode() `` or ``getContent() `` is called.
2293+
2294+ In order to test errors that occur while a response is being streamed
2295+ (that is, after the headers have already been received), provide the
2296+ response as one of the iterable ``body `` parts from
2297+ your ``MockResponse `` instance. You can either use an exception
2298+ directly, or yield the exception from a callback. For exceptions of
2299+ this kind, ``getStatusCode() `` may indicate a success (200), but
2300+ accessing ``getContent() `` fails.
2301+
2302+ The following example code illustrates all three options.
2303+
2304+ body::
22862305
22872306 // ExternalArticleServiceTest.php
22882307 use PHPUnit\Framework\TestCase;
@@ -2297,10 +2316,16 @@ you to do so, by yielding the exception from its body::
22972316 {
22982317 $requestData = ['title' => 'Testing with Symfony HTTP Client'];
22992318 $httpClient = new MockHttpClient([
2300- // You can create the exception directly in the body...
2319+ // Mock a transport level error at a time before
2320+ // headers have been received (e. g. host unreachable)
2321+ new MockResponse(info: ['error' => 'host unreachable']),
2322+
2323+ // Mock a response with headers indicating
2324+ // success, but a failure while retrieving the body by
2325+ // creating the exception directly in the body...
23012326 new MockResponse([new \RuntimeException('Error at transport level')]),
23022327
2303- // ... oryou can yield the exception from a callback
2328+ // ... orby yielding it from a callback.
23042329 new MockResponse((static function (): \Generator {
23052330 yield new TransportException('Error at transport level');
23062331 })()),