TestCase: Core Testing Foundation

Purpose and Scope

This document provides a comprehensive technical reference for the TestCase base class, the most critical component of the Hypervel Testbench system (importance: 11.69). The TestCase class serves as the foundation for all package testing, managing the complete test lifecycle, application bootstrapping, and integration with Hyperf's coroutine architecture.

This page covers the core TestCase class implementation, its composition, lifecycle management, and application creation mechanisms. For specific testing concerns provided by traits, see HandlesRoutes, CreatesApplication, and HandlesDatabases. For configuration provider management, see Configuration Provider System. For environment bootstrapping details, see Environment Bootstrapping.

Sources: src/TestCase.php22-28

Overview

The TestCase class extends Hypervel\Foundation\Testing\TestCase and provides the complete testing infrastructure for Hypervel/Hyperf packages. It orchestrates one-time environment bootstrapping, per-test application creation, coroutine context management, and test lifecycle hooks.

Key Responsibilities

Responsibility	Implementation	Lines
One-time bootstrapping	Bootstrapper::bootstrap()	src/TestCase.php40-43
Application creation	createApplication()	src/TestCase.php69-78
Environment definition	defineEnvironment()	src/TestCase.php63-67
Coroutine context management	runInCoroutine()	src/TestCase.php57
Route setup	setUpApplicationRoutes()	src/TestCase.php50
Application reloading	reloadApplication()	src/TestCase.php93-97

Sources: src/TestCase.php1-110

Class Composition and Hierarchy

The TestCase class uses a trait-based composition pattern to modularize functionality:

Static State

The class maintains a single static flag to ensure one-time bootstrapping:

Property	Type	Purpose	Line
$hasBootstrappedTestbench	bool	Ensures Bootstrapper::bootstrap() runs once per test run	src/TestCase.php36

Sources: src/TestCase.php28-36

Lifecycle Management

Test Execution Sequence

setUp Method

The setUp() method executes for each test and performs the following sequence:

1. One-time bootstrapping check src/TestCase.php40-43

   • Checks $hasBootstrappedTestbench static flag
   • Calls Bootstrapper::bootstrap() on first test only
   • Sets flag to prevent redundant initialization

2. Application creation callback registration src/TestCase.php45-51

   • Registers afterApplicationCreated callback
   • Clears all Swoole timers to prevent interference
   • Resumes WORKER_EXIT coordinator for proper shutdown
   • Calls setUpApplicationRoutes() after providers are booted

3. Parent setup execution src/TestCase.php53

   • Triggers application creation via parent class
   • Executes environment definition and provider registration

4. Coroutine context setup src/TestCase.php57

   • Wraps attribute-based setup in coroutine context
   • Executes BeforeEach attributes via setUpTheTestEnvironmentUsingTestCase()

Sources: src/TestCase.php38-58

tearDown Method

The tearDown() method provides symmetric cleanup:

1. Coroutine context teardown src/TestCase.php83

   • Wraps attribute-based teardown in coroutine context
   • Executes AfterEach attributes via tearDownTheTestEnvironmentUsingTestCase()

2. Parent teardown src/TestCase.php85

   • Delegates to parent class cleanup logic

3. Queue cleanup src/TestCase.php87

   • Resets queue payload creation callback to prevent test pollution

Sources: src/TestCase.php80-88

Class-Level Lifecycle Hooks

The class provides static hooks for setup/teardown that occur once per test class:

Method	Execution Time	Purpose	Line
setUpBeforeClass()	Before first test in class	Executes class-level setup via setUpBeforeClassUsingTestCase()	src/TestCase.php99-103
tearDownAfterClass()	After last test in class	Executes class-level cleanup via tearDownAfterClassUsingTestCase()	src/TestCase.php105-109

Sources: src/TestCase.php99-109

Application Creation and Configuration

createApplication Method

The createApplication() method constructs the Hypervel application instance:

Implementation Details:

1. Application instantiation src/TestCase.php71

   • Creates new Hypervel\Foundation\Application instance
   • Initializes dependency injection container

2. Kernel binding src/TestCase.php72

   • Binds KernelContract interface to ConsoleKernel implementation
   • Enables console command execution in tests

3. Exception handler binding src/TestCase.php73

   • Binds ExceptionHandlerContract to workbench ExceptionHandler
   • Configures exception handling behavior for tests

4. Context registration src/TestCase.php75

   • Registers container in ApplicationContext
   • Enables static access to container throughout codebase

Sources: src/TestCase.php69-78

defineEnvironment Method

The defineEnvironment() method provides the primary extension point for test customization:

This method is called automatically during application creation and delegates to:

1. Provider registration src/TestCase.php65

   • Calls registerPackageProviders() from CreatesApplication trait
   • Loads service providers defined in getPackageProviders()

2. Alias registration src/TestCase.php66

   • Calls registerPackageAliases() from CreatesApplication trait
   • Registers class aliases defined in getPackageAliases()

Tests override getPackageProviders() and getPackageAliases() to customize the application configuration. See CreatesApplication Trait for details.

Sources: src/TestCase.php63-67

Coroutine Integration with Hyperf

runInCoroutine Wrapper

The TestCase ensures compatibility with Hyperf's coroutine architecture by wrapping specific lifecycle methods in coroutine context:

Usage Location	Purpose	Line
setUp()	Executes BeforeEach attributes in coroutine context	src/TestCase.php57
tearDown()	Executes AfterEach attributes in coroutine context	src/TestCase.php83

This pattern allows tests to use Hyperf's async operations (database queries, HTTP clients, caching) without explicit coroutine management.

Sources: src/TestCase.php57 src/TestCase.php83

Swoole Timer Management

The afterApplicationCreated callback clears Swoole timers to prevent interference between tests:

1. Timer cleanup src/TestCase.php46

   • Calls Timer::clearAll() to remove all Swoole timers
   • Prevents timer callbacks from previous tests affecting current test

2. Coordinator resumption src/TestCase.php47

   • Resumes WORKER_EXIT coordinator
   • Ensures proper coroutine coordination for application lifecycle

3. Route setup src/TestCase.php50

   • Calls setUpApplicationRoutes() after providers are booted
   • Ensures routes are registered after all middleware is available

Sources: src/TestCase.php45-51

Application Reloading

reloadApplication Method

The reloadApplication() method provides a way to reset the application instance during a test:

This method is useful when tests need to:

• Reset application state without starting a new test
• Re-register providers with different configurations
• Clear service bindings and cached values

Implementation:

1. Teardown execution src/TestCase.php95

   • Calls tearDown() to clean up current application instance
   • Executes all teardown callbacks and attribute cleanup

2. Setup re-execution src/TestCase.php96

   • Calls setUp() to create new application instance
   • Re-runs entire setup sequence except one-time bootstrapping

Note: The $hasBootstrappedTestbench flag remains true, so Bootstrapper::bootstrap() is not called again.

Sources: src/TestCase.php93-97

Extension Points for Test Customization

The TestCase provides several methods that can be overridden in child test classes:

Method	Defined In	Purpose	Default Behavior
getPackageProviders()	CreatesApplication trait	Return array of service providers	Empty array
getPackageAliases()	CreatesApplication trait	Return array of class aliases	Empty array
defineRoutes()	HandlesRoutes trait	Define general routes	No-op
defineWebRoutes()	HandlesRoutes trait	Define web middleware routes	No-op
defineDatabaseMigrations()	HandlesDatabases trait	Load migrations for testing	No-op
defineEnvironment()	TestCase	Configure application environment	Registers providers/aliases

See the respective trait documentation pages for detailed usage of each extension point.

Sources: src/TestCase.php30-34

Dependencies and Imports

The TestCase integrates with multiple Hyperf and Hypervel components:

Hyperf Components

Import	Purpose	Lines
ApplicationContext	Static container access	src/TestCase.php7 src/TestCase.php75
CoordinatorManager	Coroutine coordination	src/TestCase.php9 src/TestCase.php47
Constants::WORKER_EXIT	Worker exit coordination constant	src/TestCase.php8 src/TestCase.php47
Swoole\Timer	Swoole timer management	src/TestCase.php19 src/TestCase.php46

Hypervel Components

Import	Purpose	Lines
Application	Main application container	src/TestCase.php10 src/TestCase.php71
KernelContract	Console kernel interface	src/TestCase.php11 src/TestCase.php72
ConsoleKernel	Console kernel implementation	src/TestCase.php12 src/TestCase.php72
ExceptionHandlerContract	Exception handler interface	src/TestCase.php14 src/TestCase.php73
HandlesAttributes	Attribute processing trait	src/TestCase.php15 src/TestCase.php33
InteractsWithTestCase	Test case interaction trait	src/TestCase.php16 src/TestCase.php34
Queue	Queue payload customization	src/TestCase.php18 src/TestCase.php87

Workbench Components

Import	Purpose	Lines
ExceptionHandler	Workbench exception handler	src/TestCase.php20 src/TestCase.php73

Sources: src/TestCase.php7-20

Class-Level Metadata

The TestCase class includes PHPDoc annotations that affect test execution:

• @internal: Indicates this class is for internal testbench use
• @coversNothing: Tells PHPUnit not to track code coverage for this base class

Sources: src/TestCase.php22-27