Database Testing

This document covers database testing patterns in the Hypervel testbench framework. The testbench provides the HandlesDatabases trait which manages the database testing lifecycle, including migrations and seeders. Tests typically use in-memory SQLite databases for fast, isolated execution.

The database testing system consists of:

• HandlesDatabases Trait: Provides lifecycle hooks for database setup and teardown
• Database Migrations: Schema definitions using Hypervel\Database\Migrations\Migration
• Model Factories: Test data generation with Faker integration
• In-Memory SQLite: Default database configuration for test isolation (see page 6.3)

For database configuration details, see page 6.3. For workbench models and authentication, see page 8.2.

Sources: src/Concerns/HandlesDatabases.php1-56 workbench/config/database.php8-16

HandlesDatabases Trait

The HandlesDatabases trait provides hooks for managing database state during test execution. Tests that extend TestCase can override these methods to define migrations, seeders, and cleanup logic.

HandlesDatabases Trait Architecture

Sources: src/Concerns/HandlesDatabases.php1-56

Trait Methods

The HandlesDatabases trait src/Concerns/HandlesDatabases.php7-56 defines five key methods:

Method	Purpose	Called During
defineDatabaseMigrations()	Define migrations to run before tests	setUp()
destroyDatabaseMigrations()	Clean up migrations after tests	tearDown()
defineDatabaseSeeders()	Define seeders to run after migrations	setUp()
defineDatabaseMigrationsAfterDatabaseRefreshed()	Define migrations after database refresh	Database refresh operations
setUpDatabaseRequirements()	Internal orchestration method	setUp()

The setUpDatabaseRequirements() method src/Concerns/HandlesDatabases.php47-55 orchestrates the lifecycle:

1. Calls defineDatabaseMigrations()
2. Registers destroyDatabaseMigrations() to run before application destruction
3. Executes the provided callback
4. Calls defineDatabaseSeeders()

Tests override defineDatabaseMigrations() to load schema and destroyDatabaseMigrations() to clean up.

Sources: src/Concerns/HandlesDatabases.php7-56

Using Migrations in Tests

Tests define database migrations by overriding the defineDatabaseMigrations() method. The testbench provides a complete lifecycle for running migrations during setUp() and cleaning them up during tearDown().

Migration Lifecycle in Tests

Sources: src/Concerns/HandlesDatabases.php47-55 workbench/database/migrations/2023_08_03_000000_create_users_table.php1-32

Example: Override defineDatabaseMigrations

Tests override defineDatabaseMigrations() to run migrations. Example pattern:

The testbench executes all migrations found in the specified path during test setup.

Sources: src/Concerns/HandlesDatabases.php15-18

Migration Structure

Migrations extend Hypervel\Database\Migrations\Migration and use the Schema facade from Hypervel\Support\Facades\Schema. The up() method creates schema, while the down() method reverses changes.

Migration Class Structure

Sources: workbench/database/migrations/2023_08_03_000000_create_users_table.php1-32

Example Migration: Create Users Table

The workbench provides a users table migration workbench/database/migrations/2023_08_03_000000_create_users_table.php9-32 demonstrating migration structure:

Component	Implementation
Class	Anonymous class extending Migration
Namespace imports	Blueprint, Migration, Schema
up() method	Schema::create('users', closure) with column definitions
down() method	Schema::dropIfExists('users')

The migration creates a users table with the following schema workbench/database/migrations/2023_08_03_000000_create_users_table.php15-21:

Column	Type	Constraints
id	Primary Key	Auto-increment via $table->id()
name	String	Required
email	String	Unique constraint via ->unique()
email_verified_at	Timestamp	Nullable via ->nullable()
password	String	Required
created_at, updated_at	Timestamps	Auto-managed via $table->timestamps()

The down() method workbench/database/migrations/2023_08_03_000000_create_users_table.php28-31 uses Schema::dropIfExists() to safely remove the table during cleanup.

Sources: workbench/database/migrations/2023_08_03_000000_create_users_table.php1-32

Model Factories

Model factories generate test data using the Faker\Generator library. The factory system uses a global $factory variable with closure-based definitions.

Factory System Architecture

Sources: workbench/database/factories/UserFactory.php1-17

Factory Definition Pattern

The UserFactory workbench/database/factories/UserFactory.php10-17 demonstrates the factory definition pattern:

Factory patterns used workbench/database/factories/UserFactory.php10-17:

Pattern	Implementation	Purpose
Unique constraint	$faker->unique()->name()	Prevents duplicate names across factory calls
Unique emails	$faker->unique()->safeEmail()	Ensures unique email addresses
Timestamps	Carbon::now()	Sets email_verified_at to current timestamp
Static password	Pre-hashed bcrypt string	Consistent password hash for all generated users

The pre-hashed password '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi' is the bcrypt hash of the string "password", allowing tests to authenticate with a known password.

Sources: workbench/database/factories/UserFactory.php1-17

Database Testing Patterns

The following patterns demonstrate common database testing workflows using the HandlesDatabases trait, migrations, and factories together.

Pattern 1: Basic Migration Setup

Override defineDatabaseMigrations() to load migrations before each test:

The migration runs during setUp(), and destroyDatabaseMigrations() automatically cleans up during tearDown().

Sources: src/Concerns/HandlesDatabases.php15-18 src/Concerns/HandlesDatabases.php47-55

Pattern 2: Using Seeders

Override defineDatabaseSeeders() to populate test data after migrations:

The defineDatabaseSeeders() method src/Concerns/HandlesDatabases.php31-34 is called after migrations are executed, ensuring the schema exists before seeding.

Sources: src/Concerns/HandlesDatabases.php31-34 src/Concerns/HandlesDatabases.php47-55

Pattern 3: Manual Cleanup

Override destroyDatabaseMigrations() for custom cleanup logic:

This method src/Concerns/HandlesDatabases.php23-26 is registered to run before application destruction via beforeApplicationDestroyed() callback.

Sources: src/Concerns/HandlesDatabases.php23-26 src/Concerns/HandlesDatabases.php50

Database Testing Workflow

The following diagram illustrates how database testing integrates with the TestCase lifecycle:

This workflow ensures each test starts with a clean database state while providing realistic data through the factory system.

Sources: workbench/database/migrations/2023_08_03_000000_create_users_table.php13-31 workbench/database/factories/UserFactory.php10-17