Testing Overview

This document provides an overview of the testing infrastructure in the hypervel/support package. It covers the testing philosophy, architectural patterns for test isolation, and the distinction between faking and mocking. For specific testing topics, see Facade Mocking for Mockery-based mocking, Event Testing for event fakes, HTTP Client Testing for HTTP request stubbing, and Queue Testing for queue job fakes.

Purpose and Scope

The hypervel/support package provides comprehensive testing utilities that enable isolated, deterministic tests without relying on external services. The testing infrastructure supports two primary approaches:

• Faking: Replacing real service implementations with test doubles that record interactions and provide assertion methods
• Mocking: Using Mockery to create mock objects with expectations

This page covers the overall testing architecture, patterns, and strategies. Specific facade testing capabilities are documented in their respective subsections.

Testing Philosophy

Faking vs Mocking

The package distinguishes between two testing approaches, each serving different purposes:

Approach	Implementation	Use Case	Verification
Faking	Test double implementing real interface	Testing that code dispatches events, pushes jobs, or makes HTTP requests	Assertion methods like assertDispatched()
Mocking	Mockery mock with expectations	Testing method calls and return values	Mockery expectations like shouldReceive()

Faking is preferred for testing interactions with framework services. Fakes implement the same interfaces as real services but record interactions for later assertions. The EventFake class exemplifies this pattern by implementing EventDispatcherInterface while capturing all dispatched events src/Testing/Fakes/EventFake.php17

Mocking via Mockery is useful for testing specific method calls and return values on dependencies. The Facade base class provides spy(), partialMock(), and shouldReceive() methods that integrate with Mockery src/Facades/Facade.php42-81

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

Testing Architecture

Component Overview

Sources: src/Testing/Fakes/EventFake.php17 src/Facades/Event.php45-53 src/Facades/Facade.php131-136

Fake Implementation Pattern

Fakes in the hypervel/support package follow a consistent pattern. They implement the same interface as the real service, intercept operations, and provide assertion methods. The EventFake class demonstrates this pattern:

Sources: src/Testing/Fakes/EventFake.php17-327

Test Isolation Strategies

Swap Mechanism

The Facade::swap() method is the foundation of test isolation. It replaces the resolved instance in both the static facade cache and the dependency injection container src/Facades/Facade.php131-136:

Sources: src/Facades/Facade.php131-136 src/Facades/Event.php45-53

Selective Faking

The EventFake supports selective faking through the eventsToFake parameter and the except() method. This allows tests to fake specific events while allowing others to dispatch normally:

Sources: src/Testing/Fakes/EventFake.php45-62 src/Testing/Fakes/EventFake.php249-288

Scoped Faking

The Event::fakeFor() method enables temporary faking within a specific scope, automatically restoring the original dispatcher afterward src/Facades/Event.php70-82:

Method	Purpose	Restoration
Event::fake()	Global fake for entire test	Manual restoration required
Event::fakeFor(callable)	Scoped fake during callable execution	Automatic restoration
Event::fakeExcept(events)	Fake all except specified events	Manual restoration required
Event::fakeExceptFor(callable, events)	Scoped fake except specified events	Automatic restoration

Sources: src/Facades/Event.php45-99

Common Testing Patterns

Basic Fake Usage

The typical test follows this pattern:

1. Call Facade::fake() to replace the real implementation
2. Execute application code that interacts with the service
3. Use assertion methods to verify expected interactions

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

Assertion Methods

Fakes provide various assertion methods for different verification needs:

Method	Purpose	Example Use Case
assertDispatched(event, callback)	Verify event was dispatched	Check OrderPlaced was dispatched with correct order ID
assertDispatchedTimes(event, count)	Verify dispatch count	Ensure exactly 3 notifications sent
assertNotDispatched(event, callback)	Verify event was not dispatched	Ensure PaymentFailed not dispatched on success
assertNothingDispatched()	Verify no events dispatched	Check no events in read-only operation
assertListening(event, listener)	Verify listener registered	Ensure event has required listener

The assertDispatched() method supports multiple invocation patterns src/Testing/Fakes/EventFake.php100-115:

• String event name: assertDispatched('OrderPlaced')
• With callback: assertDispatched('OrderPlaced', fn($event) => $event->orderId === 123)
• With count: assertDispatched('OrderPlaced', 3) (shorthand for assertDispatchedTimes)
• Closure with type hint: assertDispatched(function (OrderPlaced $event) { return $event->orderId === 123; })

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

Mockery Integration

For mocking facade methods directly, the Facade class provides Mockery integration:

Sources: src/Facades/Facade.php42-126

Detection Methods

Both fakes and mocks can be detected programmatically:

Method	Purpose	Return Type
Facade::isFake()	Check if a Fake instance is active	bool
Facade::isMock()	Check if a Mockery mock is active	bool

The isFake() method checks if the resolved instance implements the Fake marker interface src/Facades/Facade.php158-164 while isMock() checks for LegacyMockInterface src/Facades/Facade.php108-114

Sources: src/Facades/Facade.php108-164

Reflection Utilities

The testing infrastructure uses the Reflector class for type inspection and callable validation. The ReflectsClosures trait enables extraction of parameter types from closures, which is used by EventFake::assertDispatched() to automatically determine the event class when a closure is passed src/Testing/Fakes/EventFake.php102-104:

Method	Purpose	Used By
Reflector::isCallable()	PHP 7.4-compatible callable check	General validation
Reflector::getParameterClassName()	Extract class name from parameter	Type resolution
Reflector::getParameterClassNames()	Extract union type class names	Advanced type resolution
ReflectsClosures::firstClosureParameterType()	Get first parameter type from closure	assertDispatched(Closure)

Sources: src/Reflector.php1-136 src/Testing/Fakes/EventFake.php12

Test Lifecycle

The complete lifecycle of a test using fakes:

Sources: src/Facades/Facade.php131-208 src/Testing/Fakes/EventFake.php231-244