Testing Infrastructure

Purpose and Scope

The Testing Infrastructure provides comprehensive utilities for mocking services and asserting on application behavior during automated tests. The system offers two parallel testing strategies: generic facade mocking via Mockery for any facade, and specialized fake implementations for services that require domain-specific testing capabilities (events, queues, HTTP).

This document covers mocking strategies, fake implementations, and assertion patterns. For testing HTTP routes and controller responses, see Request and Response. For database testing strategies, see Database Operations.

---

Testing Architecture Overview

The testing infrastructure integrates with PHPUnit/Pest test suites by providing two primary mechanisms for isolating and verifying behavior:

Sources: src/Facades/Facade.php1-264 src/Testing/Fakes/EventFake.php1-327

Mocking Strategy Selection

Service	Generic Mocking	Specialized Fake	Recommended Approach
Events	✓	✓ (EventFake)	Use EventFake for better assertions
Queues	✓	✓ (QueueFake)	Use QueueFake to inspect job payloads
HTTP Client	✓	✓ (Http::fake())	Use Http::fake() to stub responses
Database	✓	✗	Use generic mocking or real DB with transactions
Cache	✓	✗	Use generic mocking or array driver
Redis	✓	✗	Use generic mocking
Other Facades	✓	✗	Use generic mocking

---

Generic Facade Mocking

All facades extend the base Facade class, which provides four generic mocking methods powered by Mockery. These methods allow testing code that uses any facade without implementing specialized fakes.

Mocking Methods

Sources: src/Facades/Facade.php42-136

spy() - Observe Without Modification

The spy() method creates a Mockery spy that records all method calls while allowing the original implementation to execute. Use this when you want to verify interactions without changing behavior.

Implementation: src/Facades/Facade.php42-53

The method checks if a mock already exists via isMock() Facade.php108-114 creates a spy using Mockery::spy(), and swaps it into the container via swap() Facade.php131-136

partialMock() - Mock Specific Methods

The partialMock() method creates a partial mock that allows real implementation for some methods while mocking others. This enables surgical mocking of specific behavior.

Implementation: src/Facades/Facade.php58-67

Creates or reuses an existing mock via createFreshMockInstance() Facade.php86-93 and calls makePartial() to enable partial mocking mode.

shouldReceive() - Set Expectations

The shouldReceive() method sets up Mockery expectations for method calls. This is the most explicit mocking approach, throwing exceptions if expectations aren't met.

Implementation: src/Facades/Facade.php72-81

swap() - Replace Instance

The swap() method replaces the facade's underlying instance with a custom implementation. Use this for complete control over the mocked behavior.

Implementation: src/Facades/Facade.php131-136

Updates both the static $resolvedInstance array and the container binding.

Sources: src/Facades/Facade.php42-136

---

Event Testing with EventFake

The EventFake class provides specialized testing capabilities for event dispatching, allowing tests to verify which events were dispatched and inspect their payloads.

Event Fake Architecture

Sources: src/Facades/Event.php45-99 src/Testing/Fakes/EventFake.php17-327

Creating Event Fakes

Event::fake() - Fake All or Specific Events

Implementation: src/Facades/Event.php45-53

The fake() method creates an EventFake instance, swaps it into the container, and updates the model event dispatcher registration via Register::setEventDispatcher() Event.php49

Event::fakeExcept() - Selective Faking

Implementation: src/Facades/Event.php58-65

Uses closure-based filtering to invert the selection logic.

Event::fakeFor() - Scoped Faking

Implementation: src/Facades/Event.php70-82

Sources: src/Facades/Event.php45-99

Selective Event Interception

The EventFake determines whether to intercept or dispatch each event based on configuration:

Sources: src/Testing/Fakes/EventFake.php231-244 EventFake.php249-262

Event Assertions

The EventFake provides comprehensive assertions for verifying event behavior:

assertDispatched() - Verify Event Was Dispatched

Implementation: src/Testing/Fakes/EventFake.php100-115

When a closure is provided without explicit event class, firstClosureParameterType() EventFake.php103 extracts the type hint from the first parameter using the ReflectsClosures trait EventFake.php20

assertDispatchedTimes() - Verify Exact Count

Implementation: src/Testing/Fakes/EventFake.php120-129

assertNotDispatched() - Verify Event Was Not Dispatched

Implementation: src/Testing/Fakes/EventFake.php134-145

assertNothingDispatched() - Verify No Events

Implementation: src/Testing/Fakes/EventFake.php150-159

Counts all dispatched events using Arr::flatten() EventFake.php152

assertListening() - Verify Listener Registration

Implementation: src/Testing/Fakes/EventFake.php67-95

Uses reflection to extract the actual listener from closure wrappers and supports both class-based listeners and closures.

Sources: src/Testing/Fakes/EventFake.php67-159

Inspecting Dispatched Events

dispatched() - Get Filtered Event Collection

Implementation: src/Testing/Fakes/EventFake.php164-177

Returns a Collection instance for fluent manipulation.

hasDispatched() - Check Event Existence

Implementation: src/Testing/Fakes/EventFake.php182-185

dispatchedEvents() - Get All Events

Implementation: src/Testing/Fakes/EventFake.php315-318

Sources: src/Testing/Fakes/EventFake.php164-318

---

Queue Testing with QueueFake

The QueueFake provides specialized testing for queued jobs, allowing verification of job dispatching and inspection of job payloads.

Queue Fake Architecture

Sources: src/Facades/Queue.php91-104

Creating Queue Fakes

Implementation: src/Facades/Queue.php91-104

The fake() method preserves a reference to the actual queue manager for selective dispatching.

Queue Assertions

assertPushed() - Verify Job Was Queued

Method signature (from docblock): src/Facades/Queue.php59

assertPushedOn() - Verify Queue Name

Method signature (from docblock): src/Facades/Queue.php60

assertPushedWithChain() - Verify Job Chain

Method signature (from docblock): src/Facades/Queue.php61

assertPushedWithoutChain() - Verify No Chain

Method signature (from docblock): src/Facades/Queue.php62

assertClosurePushed() - Verify Queued Closure

Method signature (from docblock): src/Facades/Queue.php63

assertClosureNotPushed() - Verify No Queued Closures

Method signature (from docblock): src/Facades/Queue.php64

assertNotPushed() - Verify Job Was Not Queued

Method signature (from docblock): src/Facades/Queue.php65

assertNothingPushed() - Verify No Jobs Queued

Method signature (from docblock): src/Facades/Queue.php67

assertCount() - Verify Total Job Count

Method signature (from docblock): src/Facades/Queue.php66

Sources: src/Facades/Queue.php59-72

Inspecting Queued Jobs

pushed() - Get Filtered Job Collection

Method signature (from docblock): src/Facades/Queue.php68

hasPushed() - Check Job Existence

Method signature (from docblock): src/Facades/Queue.php69

pushedJobs() - Get All Jobs

Method signature (from docblock): src/Facades/Queue.php71

Sources: src/Facades/Queue.php68-71

Job Serialization Testing

The serializeAndRestore() method enables testing of job serialization behavior:

Method signature (from docblock): src/Facades/Queue.php72

This is useful for catching serialization issues before jobs reach production queue workers.

Selective Job Faking

The except() method allows specific jobs to be queued normally while others are faked:

Method signature (from docblock): src/Facades/Queue.php58

Sources: src/Facades/Queue.php58-72

---

HTTP Client Testing

The HTTP client provides specialized testing capabilities for stubbing external HTTP responses and asserting on sent requests.

HTTP Fake Architecture

Sources: src/Facades/Http.php17-30

Creating HTTP Fakes

Http::fake() - Stub All or Specific URLs

Method signature (from docblock): src/Facades/Http.php17

Http::stubUrl() - Stub Single URL

Method signature (from docblock): src/Facades/Http.php19

Http::fakeSequence() - Sequential Responses

Method signature (from docblock): src/Facades/Http.php18

Response Creation Methods

Method signatures (from docblock): src/Facades/Http.php14-15

Sources: src/Facades/Http.php14-19

Preventing Stray Requests

Method signatures (from docblock): src/Facades/Http.php20-22

Sources: src/Facades/Http.php20-22

HTTP Assertions

assertSent() - Verify Request Was Made

Method signature (from docblock): src/Facades/Http.php24

assertSentInOrder() - Verify Request Order

Method signature (from docblock): src/Facades/Http.php25

assertNotSent() - Verify Request Was Not Made

Method signature (from docblock): src/Facades/Http.php26

assertNothingSent() - Verify No Requests

Method signature (from docblock): src/Facades/Http.php27

assertSentCount() - Verify Request Count

Method signature (from docblock): src/Facades/Http.php28

assertSequencesAreEmpty() - Verify All Sequences Consumed

Method signature (from docblock): src/Facades/Http.php29

Sources: src/Facades/Http.php24-29

Inspecting Sent Requests

recorded() - Get Filtered Request Collection

Method signature (from docblock): src/Facades/Http.php30

Returns a Collection instance containing request/response pairs.

Sources: src/Facades/Http.php30

---

Testing Best Practices

When to Use Each Testing Strategy

Isolation Patterns

Pattern	Use Case	Implementation
Spy Everything	Verify all interactions without changing behavior	Facade::spy()
Fake Domain Events	Test event-driven architecture	Event::fake()
Stub External APIs	Test API integrations without network calls	Http::fake()
Capture Async Jobs	Verify background job dispatching	Queue::fake()
Selective Faking	Fake some events/jobs, dispatch others	Event::fake()->except(), Queue::fake()->except()

Assertion Strategies

Existence Assertions - Verify something happened:

• Event::assertDispatched()
• Queue::assertPushed()
• Http::assertSent()

Absence Assertions - Verify something didn't happen:

• Event::assertNotDispatched()
• Queue::assertNotPushed()
• Http::assertNotSent()

Count Assertions - Verify exact occurrences:

• Event::assertDispatchedTimes()
• Queue::assertCount()
• Http::assertSentCount()

Payload Assertions - Verify data correctness:

Sources: src/Testing/Fakes/EventFake.php100-159 src/Facades/Queue.php59-67 src/Facades/Http.php24-29

---

Integration with PHPUnit

All testing utilities integrate seamlessly with PHPUnit and Pest test frameworks:

Setup and Teardown

Fakes and mocks should typically be created in test setup and automatically cleaned up by the framework:

Sources: src/Facades/Facade.php197-208