Assertions

Purpose and Scope

This page documents the assertion methods provided by the Factory class for verifying HTTP request behavior in tests. These methods enable you to confirm that your application sends the expected HTTP requests during test execution.

For information about intercepting requests with fake responses, see Faking Requests. For information about returning ordered responses, see Response Sequences.

---

Overview

The assertion system is built on top of the request recording mechanism. When you call Factory::fake(), recording is automatically enabled, and all subsequent requests (both faked and real) are stored as request/response pairs. Assertion methods then examine this recorded data to verify your application's HTTP behavior.

All assertion methods use PHPUnit's assertion framework internally, integrating seamlessly with PHPUnit-based test suites.

Sources: src/Factory.php48-62 src/Factory.php183-224 src/Factory.php289-306

---

Recording System Architecture

The following diagram illustrates how the recording system captures request/response pairs for later assertion:

Recording Lifecycle:

1. Factory::fake() enables recording and clears any previously recorded pairs
2. Each executed request triggers Factory::recordRequestResponsePair()
3. If recording is enabled, the request/response pair is appended to Factory::recorded
4. Assertion methods query the recorded array using filter callbacks

Sources: src/Factory.php54-61 src/Factory.php183-224 src/Factory.php289-306

---

Assertion Methods Summary

The following table lists all available assertion methods:

Method	Purpose	PHPUnit Assertion Used
assertSent(callable)	Assert that a matching request was recorded	PHPUnit::assertTrue()
assertSentInOrder(array)	Assert that requests were sent in specific order	PHPUnit::assertTrue()
assertNotSent(callable)	Assert that no matching request was recorded	PHPUnit::assertFalse()
assertNothingSent()	Assert that no requests were recorded at all	PHPUnit::assertEmpty()
assertSentCount(int)	Assert exact number of recorded requests	PHPUnit::assertCount()
assertSequencesAreEmpty()	Assert all response sequences are exhausted	PHPUnit::assertTrue()
recorded(?callable)	Retrieve filtered collection of recorded pairs	N/A (helper method)

Sources: src/Factory.php309-399

---

Method: assertSent()

Asserts that at least one request/response pair was recorded that matches the given callback. The callback receives the Request and Response objects as parameters and should return true if the pair matches the expected criteria.

Callback Signature

Implementation Details

The method uses Factory::recorded($callback) to filter recorded pairs, then asserts that the resulting collection contains at least one element. If no matching request is found, PHPUnit fails with the message: "An expected request was not recorded."

Usage Pattern Diagram

Sources: src/Factory.php309-317 src/Factory.php387-399

---

Method: assertSentInOrder()

Asserts that requests were sent in a specific order. The $callbacks array can contain either URL strings or callable functions. Each callback is tested against the corresponding request in the recorded array by index position.

Parameter Format

The $callbacks array accepts:

• URL strings: Converted to callbacks that compare against Request::url()
• Callable functions: Receive Request and Response objects, must return bool

Implementation Details

1. First calls assertSentCount(count($callbacks)) to ensure the correct number of requests were made
2. Iterates through each callback by index position
3. For each position, asserts the callback returns true for the request at that index
4. Fails with message: "An expected request (#N) was not recorded." where N is the 1-based position

Sources: src/Factory.php320-339

---

Method: assertNotSent()

Asserts that no request/response pair was recorded matching the given callback. This is the inverse of assertSent().

Implementation Details

Uses PHPUnit::assertFalse() to verify that Factory::recorded($callback)->count() equals zero. Fails with message: "Unexpected request was recorded." if a matching request is found.

Sources: src/Factory.php342-350

---

Method: assertNothingSent()

Asserts that no requests were recorded at all. Useful for testing scenarios where no HTTP activity should occur.

Implementation Details

Calls PHPUnit::assertEmpty($this->recorded) directly. Fails with message: "Requests were recorded." if any requests exist in the recorded array.

Sources: src/Factory.php353-361

---

Method: assertSentCount()

Asserts that exactly $count requests were recorded. Does not examine request content, only the total number.

Implementation Details

Uses PHPUnit::assertCount($count, $this->recorded) to verify the array length.

Sources: src/Factory.php364-369

---

Method: assertSequencesAreEmpty()

Asserts that all ResponseSequence objects created via Factory::sequence() or Factory::fakeSequence() have been fully consumed (i.e., all responses have been returned).

Implementation Details

Iterates through Factory::$responseSequences and calls ResponseSequence::isEmpty() on each. Fails with message: "Not all response sequences are empty." if any sequence still has pending responses.

This assertion is useful for verifying that your test actually triggered all the expected requests when using response sequences.

Sources: src/Factory.php372-382 src/Factory.php64-66

---

Method: recorded()

Returns a Collection of recorded request/response pairs, optionally filtered by the given callback. This is a helper method used internally by assertion methods, but can also be called directly for custom assertions.

Return Format

The returned Collection contains arrays where:

• Index 0 is the Request object
• Index 1 is the Response object (may be null for connection failures)

Callback Signature

If no callback is provided, all recorded pairs are returned.

Sources: src/Factory.php384-399

---

Assertion Workflow Diagram

This diagram shows how assertion methods integrate with the test lifecycle:

Sources: src/Factory.php183-224 src/Factory.php301-306 src/Factory.php309-369

---

Common Callback Patterns

The following table shows common patterns for assertion callbacks:

Pattern	Example Callback
URL matching	fn($req) => $req->url() === 'https://api.example.com/users'
URL pattern	fn($req) => str_contains($req->url(), '/api/')
Method matching	fn($req) => $req->method() === 'POST'
Header checking	fn($req) => $req->hasHeader('Authorization', 'Bearer token')
Body inspection	fn($req) => $req->data()['email'] === 'test@example.com'
Status code	fn($req, $res) => $res->status() === 200
Combined criteria	fn($req) => $req->method() === 'POST' && str_contains($req->url(), '/users')

Sources: src/Factory.php309-350 src/Request.php src/Response.php

---

Data Structure: recorded Array

The Factory::$recorded array has the following structure:

Each array element is a two-element array containing:

1. Index 0: Request object with full request details
2. Index 1: Response object with full response details (may be null for connection failures)

The array is cleared each time Factory::fake() is called.

Sources: src/Factory.php56-61 src/Factory.php183-188 src/Factory.php301-306

---

Integration with PHPUnit

All assertion methods integrate with PHPUnit's assertion framework:

Factory Method	PHPUnit Method	Assertion Type
assertSent()	PHPUnit::assertTrue()	Boolean
assertSentInOrder()	PHPUnit::assertTrue()	Boolean
assertNotSent()	PHPUnit::assertFalse()	Boolean
assertNothingSent()	PHPUnit::assertEmpty()	Array empty
assertSentCount()	PHPUnit::assertCount()	Array count
assertSequencesAreEmpty()	PHPUnit::assertTrue()	Boolean

The PHPUnit framework is imported at the top of the Factory class:

Sources: src/Factory.php22 src/Factory.php309-382

---

Relationship to Other Testing Features

The following diagram shows how assertions relate to other testing components:

Key relationships:

• Factory::fake() enables both stubbing and recording
• Recording captures all requests, whether stubbed or real
• Assertions query the recorded data without affecting execution
• Response sequences are tracked separately for assertSequencesAreEmpty()

Sources: src/Factory.php48-66 src/Factory.php183-224 src/Factory.php289-399