HTTP Client Testing

Purpose and Scope

This document covers testing HTTP client operations when making outgoing HTTP requests using the Http facade. The HTTP client testing infrastructure allows you to fake HTTP responses, prevent real network calls during tests, and assert that your application makes the expected HTTP requests with the correct parameters.

For information about testing HTTP requests received by your application, see Request and Response. For general testing patterns and facade mocking, see Facade Mocking.

Architecture Overview

The HTTP client testing system intercepts outgoing HTTP requests made through the Http facade and returns predetermined responses without making actual network calls. This is achieved through a stubbing mechanism that records requests and matches them against configured fake responses.

System Architecture

Sources: src/Facades/Http.php1-122

Faking Mechanism

Sources: src/Facades/Http.php17-29 src/Facades/Http.php95-102

Faking HTTP Responses

Basic Faking

The Http::fake() method configures the HTTP client to return predetermined responses instead of making real HTTP calls.

Method	Parameters	Description
Http::fake()	callable|array|null $callback	Fake all HTTP requests with callback or array
Http::stubUrl()	string $url, Response|callable	Stub a specific URL pattern
Http::response()	mixed $body, int $status, array $headers	Create a fake response
Http::sequence()	array $responses	Create a response sequence
Http::fakeSequence()	string $url	Create a sequence for a URL pattern

Sources: src/Facades/Http.php14-19

URL Pattern Stubbing

Stub responses can be configured for specific URL patterns using array syntax:

The URL patterns are matched in order, with wildcards (*) matching any characters.

Sources: src/Facades/Http.php17-19

Response Sequences

Response sequences allow different responses for multiple requests to the same URL:

Alternatively, use fakeSequence() for a specific URL:

Sources: src/Facades/Http.php16-18

Callback-Based Faking

For dynamic response generation based on request details:

Sources: src/Facades/Http.php17

Simulating Failures

Sources: src/Facades/Http.php15

Stray Request Prevention

The stray request prevention system ensures that all HTTP requests made during tests are explicitly expected.

Method	Description
Http::preventStrayRequests()	Throw exception for unstubbed URLs
Http::allowStrayRequests()	Allow unstubbed URLs to make real requests
Http::preventingStrayRequests()	Check if prevention is enabled

Sources: src/Facades/Http.php20-22

Assertion Methods

The HTTP testing system provides comprehensive assertion methods to verify request behavior.

Request Assertions

Sources: src/Facades/Http.php24-29

Available Assertions

Method	Parameters	Purpose
assertSent()	callable $callback	Assert at least one request matches the callback
assertSentInOrder()	array $callbacks	Assert requests were sent in specific order
assertNotSent()	callable $callback	Assert no requests match the callback
assertNothingSent()	-	Assert no requests were made
assertSentCount()	int $count	Assert exact number of requests
assertSequencesAreEmpty()	-	Assert all response sequences consumed

Sources: src/Facades/Http.php24-29

Assertion Callback Examples

The callback receives a Request instance and should return true for matching requests:

Sources: src/Facades/Http.php24

Ordered Assertions

Verify requests were sent in a specific sequence:

Sources: src/Facades/Http.php25

Recording and Inspection

The recorded() method provides access to all captured requests for custom inspection.

Recording System

Method	Parameters	Returns	Purpose
recorded()	callable|null $callback	Collection	Get all or filtered recorded requests
recordRequestResponsePair()	Request, Response|null	void	Record a request/response pair

Sources: src/Facades/Http.php23 src/Facades/Http.php30

Inspection Examples

Sources: src/Facades/Http.php30

Testing Patterns

Basic Test Structure

Sources: src/Facades/Http.php17-29

Complete Test Example

Sources: src/Facades/Http.php17-29

Testing with Response Sequences

Sources: src/Facades/Http.php16-18 src/Facades/Http.php29

Testing Authentication

Sources: src/Facades/Http.php66 src/Facades/Http.php24

Testing Error Handling

Sources: src/Facades/Http.php15 src/Facades/Http.php24

Advanced Testing Scenarios

Global Middleware Testing

Sources: src/Facades/Http.php10-12

Connection-Specific Testing

Sources: src/Facades/Http.php108-109

Conditional Request Testing

Sources: src/Facades/Http.php24-26

Summary

The HTTP client testing infrastructure provides:

• Faking System: Intercept outgoing HTTP requests without network calls via Http::fake() src/Facades/Http.php17
• Response Configuration: Flexible response stubbing with URL patterns, sequences, and callbacks src/Facades/Http.php14-19
• Stray Prevention: Ensure all requests are explicitly expected with preventStrayRequests() src/Facades/Http.php20-22
• Comprehensive Assertions: Verify request behavior with assertSent(), assertSentCount(), and related methods src/Facades/Http.php24-29
• Request Recording: Inspect captured requests with recorded() for custom verification src/Facades/Http.php30

This system enables isolated, fast, and reliable testing of HTTP client interactions without external dependencies.