HTTP Request Testing

Purpose and Scope

This document covers the HTTP request testing infrastructure in Hypervel Foundation, which enables developers to simulate HTTP requests against their application without running an actual web server. The system is built around the MakesHttpRequests trait and the TestClient class, which execute requests in coroutines to maintain compatibility with Hyperf's async architecture.

For information about response assertions after making requests, see Test Response Assertions. For session-related test setup, see Authentication and Session Testing. For general test case setup and lifecycle, see Test Case Foundation and Lifecycle.

---

HTTP Testing Architecture

The HTTP testing system consists of several cooperating components that simulate the full request lifecycle while maintaining test isolation.

Sources: src/Testing/Concerns/MakesHttpRequests.php1-392 src/Testing/Http/TestClient.php1-348

---

MakesHttpRequests Trait

The MakesHttpRequests trait provides the primary interface for making HTTP requests in tests. It is composed into the base TestCase class and provides convenient methods for all HTTP verbs and request types.

Request State Properties

Property	Type	Purpose	Default
defaultHeaders	array	Headers added to every request	[]
defaultCookies	array	Cookies sent with every request	[]
followRedirects	bool	Whether to automatically follow redirects	false
withCredentials	bool	Include cookies in JSON requests	false
globalMiddleware	array	Global middleware configuration	[]
middlewareGroups	array	Middleware group configuration	[]
middlewareAliases	array	Middleware alias configuration	[]
middlewarePriority	array	Middleware priority configuration	[]

Sources: src/Testing/Concerns/MakesHttpRequests.php14-53

HTTP Method Mapping

Sources: src/Testing/Concerns/MakesHttpRequests.php55-118 src/Testing/Concerns/MakesHttpRequests.php80-113

---

Request Configuration Methods

The trait provides fluent methods for configuring request behavior. These methods return $this to enable method chaining.

Header Configuration

Sources: src/Testing/Concerns/MakesHttpRequests.php227-288

Cookie and Redirect Configuration

Method	Parameters	Purpose
withCookies()	array $cookies	Add multiple cookies to the request
withCookie()	string $name, string $value	Add a single cookie
followingRedirects()	none	Enable automatic redirect following
withCredentials()	none	Include cookies in JSON requests

Sources: src/Testing/Concerns/MakesHttpRequests.php354-391

Middleware Configuration

The trait allows granular control over middleware execution during tests:

Sources: src/Testing/Concerns/MakesHttpRequests.php318-351 src/Testing/Concerns/MakesHttpRequests.php120-146

---

TestClient Architecture

The TestClient class extends the HTTP Kernel and provides the actual request execution infrastructure. It converts test requests into PSR-7 requests and processes them through the full middleware pipeline.

TestClient Initialization

Sources: src/Testing/Http/TestClient.php43-61 src/Testing/Http/TestClient.php254-268 src/Testing/Http/TestClient.php276-288

Request Method Implementation

The TestClient provides methods corresponding to HTTP verbs that prepare request options and delegate to the request() method:

Method	HTTP Verb	Data Encoding	Lines
get()	GET	Query parameters	72-79
post()	POST	Form parameters	81-88
put()	PUT	Form parameters	90-97
delete()	DELETE	Query parameters	99-106
options()	OPTIONS	Query parameters	63-70
json()	Any	JSON body with Content-Type: application/json	108-118
file()	POST	Multipart form data	120-144

Sources: src/Testing/Http/TestClient.php63-144

---

Request Execution Flow

The core request() method orchestrates the complete request lifecycle, from option processing to coroutine execution.

Sources: src/Testing/Http/TestClient.php146-164 src/Testing/Http/TestClient.php173-219 src/Testing/Http/TestClient.php221-252

Request Initialization Details

The initRequest() method builds a complete PSR-7 ServerRequestInterface:

Sources: src/Testing/Http/TestClient.php173-219

---

Coroutine Execution Model

Test requests execute within coroutines to maintain compatibility with Hyperf's async architecture. The Waiter class manages this execution.

Waiter Implementation

The Waiter class (extending Hyperf\Coroutine\Waiter) provides a wait() method that:

1. Creates a channel for communication between coroutines
2. Spawns a new coroutine to execute the request
3. Copies the parent coroutine's context to maintain isolation
4. Captures exceptions and wraps them in ExceptionThrower
5. Returns the result or throws the captured exception

Sources: src/Testing/Coroutine/Waiter.php18-49

The default timeout is 10 seconds as defined in TestClient::$waitTimeout src/Testing/Http/TestClient.php37

---

File Upload Testing

The file() method enables testing of file uploads by converting file specifications into multipart form data.

File Upload Processing

Sources: src/Testing/Http/TestClient.php120-144 src/Testing/Http/TestClient.php290-326

---

Request State Management

The MakesHttpRequests trait maintains state across multiple test method calls and provides cleanup mechanisms.

State Lifecycle

The flushRequestStates() method resets state after each request:

Property Reset	Value
defaultHeaders	[]
defaultCookies	[]
followRedirects	false
withCredentials	false

Note: Middleware configuration (globalMiddleware, middlewareGroups, etc.) is not reset by flushRequestStates() and persists for the entire test method unless explicitly changed.

Sources: src/Testing/Concerns/MakesHttpRequests.php293-301 src/Testing/Concerns/MakesHttpRequests.php148-170

---

Integration with HTTP Kernel

The TestClient extends the HttpKernel class and leverages its middleware dispatch infrastructure. It overrides key methods to adapt kernel behavior for testing.

Kernel Integration Points

Sources: src/Testing/Http/TestClient.php31-61 src/Testing/Http/TestClient.php221-252 src/Testing/Http/TestClient.php254-268

Event Dispatching in Tests

The TestClient optionally dispatches lifecycle events based on server configuration:

Event	When Dispatched	Condition
RequestReceived	Before middleware processing	enable_request_lifecycle = true
RequestHandled	After response generation	enable_request_lifecycle = true

The configuration is read from server.servers.{server}.options.enable_request_lifecycle src/Testing/Http/TestClient.php45-46

Sources: src/Testing/Http/TestClient.php225-248

---

ServerResponse for Tests

The ServerResponse class extends Hyperf's PSR-7 response to capture streamed content during testing.

The write() method accumulates content into $streamedContent for later assertion, while the getStreamedContent() method retrieves the accumulated content src/Testing/Http/ServerResponse.php13-23

Sources: src/Testing/Http/ServerResponse.php1-24

---

Usage Patterns

Basic Request Testing

JSON API Testing

Authenticated Requests

Testing with Custom Middleware

File Upload Testing

---

Summary

The HTTP request testing infrastructure provides a comprehensive system for simulating HTTP requests in tests. The MakesHttpRequests trait offers a fluent API for configuring and executing requests, while the TestClient handles the low-level details of converting test requests into PSR-7 requests and processing them through the middleware pipeline. The Waiter class ensures that requests execute in coroutines with proper context isolation, maintaining compatibility with Hyperf's async architecture.

Sources: src/Testing/Concerns/MakesHttpRequests.php1-392 src/Testing/Http/TestClient.php1-348 src/Testing/Coroutine/Waiter.php1-50