 |
VOOZH | about |
|
VOOZH | about |
This document explains the complete test execution lifecycle in the Hypervel Testbench, including the order of hook methods, one-time bootstrapping, per-test setup and teardown phases, and available extension points. Understanding this lifecycle is essential for writing effective tests and customizing test behavior.
For details on how the application instance is created during setup, see Application Creation and Container Setup. For information on how coroutines are managed during test execution, see Coroutine Context and Hyperf Integration. For environment management and reloading patterns, see Reloading and Environment Management.
The testbench implements a sophisticated lifecycle that distinguishes between one-time initialization (performed once per test run) and per-test setup/teardown (performed for each individual test method). This design optimizes performance while maintaining test isolation.
Sources: src/TestCase.php36-110 src/Bootstrapper.php21-40
The testbench uses a static flag $hasBootstrappedTestbench to ensure that bootstrapping occurs exactly once per PHPUnit test run, regardless of how many test classes or test methods execute.
The guard is implemented in the setUp() method:
This check occurs at src/TestCase.php40-43
When Bootstrapper::bootstrap() executes, it performs several critical initialization tasks:
| Operation | Purpose | File Reference |
|---|---|---|
Load testbench.yaml | Parse configuration file to get environment settings | src/Bootstrapper.php23-25 |
Define BASE_PATH constant | Set application base directory (defaults to workbench/) | src/Bootstrapper.php27-32 |
Define SWOOLE_HOOK_FLAGS | Configure Swoole coroutine hooks | src/Bootstrapper.php33 |
Generate .env file | Create environment file from YAML env key | src/Bootstrapper.php98-108 |
Generate composer.lock | Create mock composer.lock with provider configuration | src/Bootstrapper.php56-78 |
| Register purge files | Schedule cleanup of temporary files on shutdown | src/Bootstrapper.php119-145 |
Initialize ClassLoader | Setup class scanning with TestScanHandler | src/Bootstrapper.php39 |
The bootstrapping only loads configuration and defines constants—it does not create the application instance. Application creation occurs separately during each test's setUp() phase.
Sources: src/Bootstrapper.php21-40 src/TestCase.php40-43
Each test method executes within a fresh application context. The setup phase creates a new application instance, registers providers, configures routes, and prepares the database.
Sources: src/TestCase.php38-58
The setUp() method performs the following operations in order:
Bootstrap Check src/TestCase.php40-43: Conditionally calls Bootstrapper::bootstrap() on first test execution.
Register Callback src/TestCase.php45-51: Registers an afterApplicationCreated callback that will execute after provider booting:
Parent Setup src/TestCase.php53: Calls parent::setUp() which triggers:
createApplication()defineEnvironment()Coroutine Setup src/TestCase.php57: Executes attribute-based setup inside coroutine context:
The afterApplicationCreated callback performs three critical operations:
Timer::clearAll(): Clears all Swoole timers to prevent interference between testsCoordinatorManager::until(Constants::WORKER_EXIT)->resume(): Resumes the worker exit coordinator$this->setUpApplicationRoutes($this->app): Registers routes defined in defineRoutes() and defineWebRoutes()These operations ensure that each test starts with a clean Swoole timer state and properly configured routing.
Sources: src/TestCase.php38-58
After the setup phase completes, PHPUnit invokes the test method. At this point:
$this->appHandlesDatabases trait)Test methods can access the application container, make HTTP requests, query the database, and use any registered services. The application lifecycle is managed transparently by the TestCase base class.
The teardown phase cleans up after each test, ensuring that subsequent tests start with a fresh state.
Sources: src/TestCase.php80-88
The tearDown() method src/TestCase.php80-88 performs cleanup in this order:
Coroutine Teardown src/TestCase.php83: Executes attribute-based teardown inside coroutine context:
Parent Teardown src/TestCase.php85: Calls parent::tearDown() which:
destroyDatabaseMigrations() (if using HandlesDatabases)Queue Reset src/TestCase.php87: Resets the Queue payload callback:
This ensures that any custom queue payload creators registered during a test do not affect subsequent tests.
Sources: src/TestCase.php80-88
In addition to per-test hooks, PHPUnit provides class-level hooks that execute once per test class.
The setUpBeforeClass() static method src/TestCase.php99-103 executes once before any test methods in the class run:
This hook:
setUpBeforeClassUsingTestCase() from the InteractsWithTestCase traitBeforeClass attributes if defined on the test classThe tearDownAfterClass() static method src/TestCase.php105-109 executes once after all test methods in the class complete:
This hook:
tearDownAfterClassUsingTestCase() from the InteractsWithTestCase traitAfterClass attributes if defined on the test classNote: Class-level hooks execute outside coroutine context and should not perform async operations.
Sources: src/TestCase.php99-109
The testbench provides multiple extension points for customizing test behavior. These methods can be overridden in test classes to inject custom logic at specific lifecycle points.
Sources: src/TestCase.php38-110 src/Concerns/CreatesApplication.php src/Concerns/HandlesRoutes.php src/Concerns/HandlesDatabases.php
| Method | Phase | Purpose | Default Behavior |
|---|---|---|---|
defineEnvironment(ApplicationContract $app) | Setup | Configure application before provider boot | Registers package providers and aliases |
getPackageProviders(ApplicationContract $app) | Setup | Define service providers to register | Returns empty array |
getPackageAliases(ApplicationContract $app) | Setup | Define class aliases to register | Returns empty array |
defineRoutes(Router $router) | Setup | Define test routes without middleware | Empty implementation |
defineWebRoutes(Router $router) | Setup | Define routes with web middleware group | Empty implementation |
defineDatabaseMigrations() | Setup | Run database migrations | Empty implementation |
destroyDatabaseMigrations() | Teardown | Roll back database migrations | Empty implementation |
createApplication() | Setup | Instantiate application container | Creates Hypervel\Foundation\Application |
reloadApplication() | Manual | Recreate application during test | Calls tearDown() then setUp() |
For detailed information on each extension point, see:
Sources: src/TestCase.php63-97
The testbench automatically wraps setup and teardown logic in Hyperf coroutines to ensure compatibility with async operations.
Two lifecycle operations execute explicitly inside coroutine context:
Setup Attributes src/TestCase.php57:
This executes BeforeEach attributes inside a coroutine, matching the context where test methods run.
Teardown Attributes src/TestCase.php83:
This executes AfterEach attributes inside a coroutine, ensuring proper cleanup of async resources.
Hyperf's architecture requires that certain operations (database queries, HTTP requests, cache operations) execute within a coroutine context. The testbench ensures this by:
BaseTestCase)runInCoroutine() helper for explicit async operationsFor a deep dive into coroutine integration, including coordinator management and Swoole timer handling, see Coroutine Context and Hyperf Integration.
Sources: src/TestCase.php57 src/TestCase.php83
The reloadApplication() method src/TestCase.php93-97 allows tests to recreate the application instance mid-test:
This pattern is useful when:
Note: Reloading the application executes the full teardown and setup cycle, including database migration rollback and re-execution.
For more information on environment management and reloading patterns, see Reloading and Environment Management.
Sources: src/TestCase.php93-97
The testbench lifecycle implements a sophisticated initialization strategy:
This architecture balances performance optimization (one-time bootstrap) with test isolation (per-test application creation), while maintaining compatibility with Hyperf's async runtime environment.
Refresh this wiki