 |
VOOZH | about |
|
VOOZH | about |
This document covers the database testing utilities provided by Hypervel Foundation's testing framework. These utilities enable developers to write tests that interact with databases while maintaining proper isolation between test cases.
The database testing system provides three primary strategies for managing database state during tests:
These strategies are implemented as traits that integrate with the test lifecycle through automatic detection and initialization. For information about the overall test lifecycle, see Test Case Foundation and Lifecycle. For other testing concerns, see Container and Service Testing and Authentication and Session Testing.
Sources: src/Testing/TestCase.php1-197
The database testing system integrates with the TestCase lifecycle through trait-based composition and automatic initialization. Each database strategy trait provides specific methods that are invoked during test setup and teardown phases.
Sources: src/Testing/TestCase.php24-197
The TestCase base class automatically detects and initializes database testing traits through the setUpTraits() method. This method uses PHP's reflection capabilities to discover which traits are in use and execute their corresponding setup methods.
| Detection Phase | Method | Line Reference |
|---|---|---|
| Trait Discovery | class_uses_recursive(static::class) | src/Testing/TestCase.php82 |
| RefreshDatabase Check | isset($uses[RefreshDatabase::class]) | src/Testing/TestCase.php84 |
| DatabaseMigrations Check | isset($uses[DatabaseMigrations::class]) | src/Testing/TestCase.php88 |
| DatabaseTransactions Check | isset($uses[DatabaseTransactions::class]) | src/Testing/TestCase.php92 |
| Setup Method Invocation | $this->{$method}() | src/Testing/TestCase.php106 |
| Teardown Registration | beforeApplicationDestroyed(fn() => ...) | src/Testing/TestCase.php110 |
Sources: src/Testing/TestCase.php80-115
The RefreshDatabase trait provides a testing strategy that ensures a clean database state by refreshing the database before each test. This trait is automatically detected and initialized when included in a test class.
When the TestCase detects the RefreshDatabase trait during setup, it invokes the refreshDatabase() method:
Line 84-86 in TestCase.php:
if (isset($uses[RefreshDatabase::class])) {
$this->refreshDatabase();
}
| Scenario | Recommendation |
|---|---|
| Integration tests with database state changes | ✓ Recommended |
| Tests that need fresh migrations each run | ✓ Recommended |
| Fast unit tests without database interaction | ✗ Not needed |
| Tests requiring data to persist across test methods | ✗ Use DatabaseTransactions |
Sources: src/Testing/TestCase.php84-86
The DatabaseMigrations trait runs database migrations before test execution begins. This strategy is suitable for tests that require a migrated database schema but don't need to refresh the database between individual tests.
When detected during test setup, the trait invokes the runDatabaseMigrations() method:
Line 88-90 in TestCase.php:
if (isset($uses[DatabaseMigrations::class])) {
$this->runDatabaseMigrations();
}
| Scenario | Recommendation |
|---|---|
| Test suite setup requiring schema | ✓ Recommended |
| Tests running against static test data | ✓ Recommended |
| Tests needing to verify migration behavior | ✓ Recommended |
| Tests requiring clean state between runs | ✗ Use RefreshDatabase |
Sources: src/Testing/TestCase.php88-90
The DatabaseTransactions trait wraps each test method in a database transaction. After the test completes, the transaction is rolled back, ensuring database state is not persisted between tests. This provides excellent test isolation with minimal performance overhead.
The trait is detected and initialized with the beginDatabaseTransaction() method:
Line 92-94 in TestCase.php:
if (isset($uses[DatabaseTransactions::class])) {
$this->beginDatabaseTransaction();
}
| Scenario | Recommendation |
|---|---|
| Fast tests with database changes | ✓ Recommended |
| Tests requiring isolation without migration overhead | ✓ Recommended |
| Multiple tests in same class sharing setup data | ✓ Recommended |
| Tests verifying transaction behavior | ✗ May interfere |
| Tests using nested transactions | ✗ Check database support |
Sources: src/Testing/TestCase.php92-94
The InteractsWithDatabase trait provides the base functionality for database interaction during tests. This trait is automatically included in the TestCase base class and provides methods for database assertions and utilities.
The TestCase includes InteractsWithDatabase as one of its core testing traits:
Line 13: use Hypervel\Foundation\Testing\Concerns\InteractsWithDatabase;
Line 30: use InteractsWithDatabase;
Sources: src/Testing/TestCase.php13-30
Database testing traits can register teardown methods that execute before the application is destroyed. This mechanism ensures proper cleanup of database state and resources.
The trait detection system automatically discovers teardown methods using naming conventions:
Line 109-111 in TestCase.php:
if (method_exists($this, $method = 'tearDown' . class_basename($trait))) {
$this->beforeApplicationDestroyed(fn () => $this->{$method}());
}
Teardown callbacks are executed with error handling to ensure all callbacks run even if one fails:
| Behavior | Implementation | Line Reference |
|---|---|---|
| Exception Capture | try { $callback(); } catch (Throwable $e) | src/Testing/TestCase.php180-186 |
| First Exception Stored | if (! $this->callbackException) | src/Testing/TestCase.php183 |
| Exception Re-thrown | throw $this->callbackException | src/Testing/TestCase.php132 |
Sources: src/Testing/TestCase.php109-111 src/Testing/TestCase.php117-152 src/Testing/TestCase.php177-188
Different database testing strategies have different performance characteristics and use cases. The following comparison helps determine which trait to use.
| Feature | RefreshDatabase | DatabaseMigrations | DatabaseTransactions |
|---|---|---|---|
| Execution Speed | Slow (migrations run each test) | Medium (migrations run once) | Fast (rollback only) |
| Isolation Level | Complete (fresh database) | Partial (shared schema) | Complete (rolled back) |
| Setup Overhead | High | Medium | Low |
| Best For | Integration tests | Test suite setup | Unit/feature tests |
| Multiple Tests | Each test isolated | Tests share state | Each test isolated |
| Database Changes | Persisted then reset | Persisted across tests | Never persisted |
Fast Feature Tests:
Integration Tests:
Suite-Level Setup:
Sources: src/Testing/TestCase.php84-94
Database testing methods are executed within coroutine context to ensure compatibility with Hyperf's async architecture. This is handled automatically by the TestCase infrastructure.
All trait initialization occurs within a coroutine context:
Line 64-66 in TestCase.php:
$this->runInCoroutine(
fn () => $this->setUpTraits()
);
The runInCoroutine() method ensures execution happens in a coroutine:
Line 193-196 in TestCase.php:
protected function runInCoroutine(callable $callback): void
{
Coroutine::inCoroutine() ? $callback() : run($callback);
}
| Aspect | Behavior |
|---|---|
| Database Connections | Must be coroutine-safe |
| Transaction Isolation | Bound to coroutine context |
| Connection Pooling | Handled by Hyperf's async driver |
| Blocking Operations | Avoided through async I/O |
Sources: src/Testing/TestCase.php64-66 src/Testing/TestCase.php193-196
DatabaseTransactions for most tests requiring database interactionRefreshDatabase when tests create complex interdependent dataDatabaseMigrations when tests read from pre-loaded fixturesDatabaseTransactions provides the best performance for isolated testsRefreshDatabase should be used sparingly due to migration overhead:memory:) for even faster test execution| Issue | Solution |
|---|---|
| Slow test suite | Prefer DatabaseTransactions over RefreshDatabase |
| Tests affecting each other | Ensure proper trait usage and isolation |
| Transaction deadlocks | Check for nested transaction issues |
| Migration failures | Verify migrations are idempotent |
Sources: src/Testing/TestCase.php80-115
Refresh this wiki