 |
VOOZH | about |
|
VOOZH | about |
This document provides an overview of the three testing traits that extend TestCase functionality in the Hypervel Testbench. These traits implement the template method pattern, providing strategic extension points for route definition, service provider registration, and database management during tests.
For detailed documentation of each trait's API and usage patterns, see:
For information about the TestCase base class that uses these traits, see TestCase: Core Testing Foundation.
The Hypervel Testbench provides three traits that modularize core testing functionality:
| Trait | Importance | Primary Purpose | Key Methods |
|---|---|---|---|
HandlesRoutes | 8.00 | Route definition for HTTP testing | defineRoutes(), defineWebRoutes() |
CreatesApplication | 4.00 | Service provider and alias registration | getPackageProviders(), getPackageAliases() |
HandlesDatabases | 2.00 | Database migration and seeder management | defineDatabaseMigrations(), destroyDatabaseMigrations() |
These traits are composed into the TestCase base class src/TestCase.php providing a complete testing foundation. The importance scores reflect usage frequency: route testing (8.00) is most common, followed by provider registration (4.00), with database testing (2.00) used for specific scenarios.
Sources: src/Concerns/HandlesRoutes.php1-49 src/Concerns/CreatesApplication.php1-60 src/Concerns/HandlesDatabases.php1-56
The following diagram illustrates how the three traits compose into TestCase and integrate with the test lifecycle:
Diagram: Trait Composition and Lifecycle Integration
This architecture demonstrates the template method pattern: TestCase defines the testing algorithm, while traits provide strategic extension points. Developers override trait methods to customize behavior without modifying the base test lifecycle.
Sources: src/Concerns/HandlesRoutes.php16-47 src/Concerns/CreatesApplication.php14-58 src/Concerns/HandlesDatabases.php12-55
The following sequence diagram maps the exact method calls from the TestCase lifecycle to trait extension points:
Diagram: Method Call Flow from TestCase to Trait Extension Points
This sequence demonstrates how TestCase orchestrates trait methods during test execution. Note the conditional logic in src/Concerns/HandlesRoutes.php43-46 that uses reflection to check if defineWebRoutes() is overridden before applying web middleware grouping.
Sources: src/Concerns/HandlesRoutes.php35-47 src/Concerns/CreatesApplication.php37-58 src/Concerns/HandlesDatabases.php45-55
The HandlesRoutes trait provides three methods for route management:
| Method | Signature | Purpose | Called By |
|---|---|---|---|
defineRoutes() | protected function defineRoutes(Router $router): void | Define general-purpose routes without middleware | setUpApplicationRoutes() |
defineWebRoutes() | protected function defineWebRoutes(Router $router): void | Define routes with automatic web middleware grouping | setUpApplicationRoutes() (conditional) |
setUpApplicationRoutes() | protected function setUpApplicationRoutes(ApplicationContract $app): void | Internal orchestration method (rarely overridden) | TestCase::setUp() |
The trait uses ReflectionMethod src/Concerns/HandlesRoutes.php43 to detect if defineWebRoutes() is overridden, preventing empty middleware groups from interfering with route registration.
Sources: src/Concerns/HandlesRoutes.php19-47
The CreatesApplication trait provides four methods for provider and alias management:
| Method | Signature | Purpose | Return Type |
|---|---|---|---|
getPackageProviders() | protected function getPackageProviders(ApplicationContract $app): array | Return array of service provider class names | array<int, class-string> |
getPackageAliases() | protected function getPackageAliases(ApplicationContract $app): array | Return array of class aliases (facades) | array<string, class-string> |
registerPackageProviders() | protected function registerPackageProviders(ApplicationContract $app): void | Internal registration logic (rarely overridden) | void |
registerPackageAliases() | protected function registerPackageAliases(ApplicationContract $app): void | Internal alias registration logic (rarely overridden) | void |
The registration methods src/Concerns/CreatesApplication.php37-58 iterate over arrays returned by the get*() methods and merge them into the application container.
Sources: src/Concerns/CreatesApplication.php14-58
The HandlesDatabases trait provides five methods for database management:
| Method | Signature | Purpose | Lifecycle Phase |
|---|---|---|---|
defineDatabaseMigrations() | protected function defineDatabaseMigrations(): void | Run migrations before each test | Setup |
destroyDatabaseMigrations() | protected function destroyDatabaseMigrations(): void | Roll back migrations after each test | Teardown |
defineDatabaseSeeders() | protected function defineDatabaseSeeders(): void | Seed database after migrations | Setup |
defineDatabaseMigrationsAfterDatabaseRefreshed() | protected function defineDatabaseMigrationsAfterDatabaseRefreshed(): void | Run migrations after database refresh | Post-refresh |
setUpDatabaseRequirements() | protected function setUpDatabaseRequirements(callable $callback): void | Orchestrate database setup (rarely overridden) | Setup |
The setUpDatabaseRequirements() method src/Concerns/HandlesDatabases.php47-55 orchestrates the complete database lifecycle: migrations → callback execution → seeders, with automatic teardown registration via beforeApplicationDestroyed().
Sources: src/Concerns/HandlesDatabases.php13-55
Use HandlesRoutes when your tests require HTTP route definitions:
The web middleware group is automatically applied to routes defined in defineWebRoutes() src/Concerns/HandlesRoutes.php45 For detailed examples and the reflection-based conditional logic, see HandlesRoutes Trait.
Sources: src/Concerns/HandlesRoutes.php19-30
Use CreatesApplication when your package provides service providers or aliases:
Providers are registered via $app->register() src/Concerns/CreatesApplication.php41 while aliases are merged into the app.aliases configuration src/Concerns/CreatesApplication.php57 For provider management patterns and the ConfigProviderRegister integration, see CreatesApplication Trait.
Sources: src/Concerns/CreatesApplication.php19-32
Use HandlesDatabases when your tests require database schema setup:
The trait ensures migrations run before each test and are cleaned up afterward via beforeApplicationDestroyed() callback registration src/Concerns/HandlesDatabases.php50 For migration lifecycle management and factory usage, see HandlesDatabases Trait.
Sources: src/Concerns/HandlesDatabases.php15-26
The following table shows how traits can be combined and potential interaction points:
| Combination | Common Use Case | Considerations |
|---|---|---|
HandlesRoutes only | Testing HTTP endpoints without database or custom providers | Most lightweight option |
CreatesApplication only | Testing service provider registration without HTTP or database | Used for unit testing providers |
HandlesDatabases only | Testing models, repositories, or data layers | Common for domain layer tests |
HandlesRoutes + HandlesDatabases | Full-stack HTTP testing with persistent data | Most common combination for feature tests |
CreatesApplication + HandlesDatabases | Testing providers that require database | Example: testing a database-backed cache provider |
| All three traits | Comprehensive integration testing | Default composition in TestCase |
Sources: All trait files referenced above
All three traits implement the template method pattern:
TestCase): setUp(), createApplication(), tearDown()defineRoutes(), getPackageProviders(), defineDatabaseMigrations()setUpApplicationRoutes(), registerPackageProviders(), setUpDatabaseRequirements()Developers override hook methods to customize behavior while template methods orchestrate the testing algorithm.
The HandlesRoutes trait uses reflection to prevent empty middleware groups:
This pattern src/Concerns/HandlesRoutes.php43-46 ensures that defining a web route requires explicit developer action, avoiding accidental middleware application.
Sources: src/Concerns/HandlesRoutes.php43-46
The HandlesDatabases trait uses beforeApplicationDestroyed() callbacks to ensure cleanup:
This pattern src/Concerns/HandlesDatabases.php49-50 guarantees that database state is cleaned up even if tests throw exceptions, maintaining test isolation.
Sources: src/Concerns/HandlesDatabases.php47-55
The importance scores reflect real-world usage patterns:
HandlesRoutes (8.00): Highest importance due to HTTP testing being the primary use case for web application packages. Routes are defined in nearly every feature test.
CreatesApplication (4.00): Medium importance. Used when testing packages that provide service providers, which is common but not universal.
HandlesDatabases (2.00): Lower importance. Many tests use in-memory data structures or mocks rather than actual database operations.
These scores derive from the codebase's edit frequency as shown in file importance metadata indicating how often developers modify or extend each trait during typical testing workflows.
The three testing traits provide modular, composable functionality for extending TestCase:
All traits implement the template method pattern, providing hook methods that developers override while the base class orchestrates execution. Reflection and callback registration ensure safe, isolated test execution.
For detailed API documentation, usage examples, and advanced patterns, see the individual trait documentation pages: HandlesRoutes, CreatesApplication, and HandlesDatabases.
Sources: src/Concerns/HandlesRoutes.php1-49 src/Concerns/CreatesApplication.php1-60 src/Concerns/HandlesDatabases.php1-56
Refresh this wiki