[Feature Request] RefreshDatabase should refuse migrate:fresh when APP_ENV is not testing

[brinytaco]

Description

Laravel's RefreshDatabase trait (Illuminate\Foundation\Testing\RefreshDatabase) runs migrate:fresh against whichever database connection PHPUnit/Laravel is currently using.

The documented safety model assumes:

• phpunit.xml sets APP_ENV=testing
• A separate test database (or SQLite :memory:) is configured there

If PHPUnit is invoked with --no-configuration, or without loading phpunit.xml, those overrides are skipped. Laravel bootstraps from .env instead (for example APP_ENV=local, DB_DATABASE=my_app).

In that situation, RefreshDatabase can run migrate:fresh against the developer's real local database with no warning.

This is a common footgun:

• Documented in many Stack Overflow threads over the years
• Easy to trigger when running vendor/bin/phpunit tests/Feature/ExampleTest.php --no-configuration as a shortcut
• Automated tooling (IDEs, AI agents) often uses --no-configuration as a fallback when a test command fails for unrelated reasons

Production is partially protected by DB::prohibitDestructiveCommands() (Laravel 11+), but local development is not. The docs say tests should only run when APP_ENV=testing, yet RefreshDatabase does not enforce that contract at runtime.

Steps to reproduce

1. Create a Laravel app with RefreshDatabase on a feature test
2. Configure .env with APP_ENV=local and DB_DATABASE=my_real_dev_db
3. Configure phpunit.xml with APP_ENV=testing and DB_DATABASE=my_app_test (the safe setup)
4. Run:

vendor/bin/phpunit tests/Feature/ExampleTest.php --no-configuration

5. Observe migrate:fresh runs against my_real_dev_db from .env instead of my_app_test

Expected behavior

RefreshDatabase (or the test bootstrap) should refuse to run destructive migrations unless the application environment is testing, with a clear error message pointing to phpunit.xml / php artisan test.

Example error message:

RuntimeException: Refusing to refresh database: APP_ENV must be "testing" (got "local").
Run tests via php artisan test or vendor/bin/phpunit from the project root so phpunit.xml applies.
Never use --no-configuration.

Optionally, also verify the active database name differs from a configured production/dev name, or matches an explicit test database from config.

Actual behavior

migrate:fresh runs silently against the .env database. Local data is destroyed.

Proposed solution

In RefreshDatabase::migrateDatabases() (or refreshTestDatabase()), before calling $this->artisan('migrate:fresh', ...):

if (! $this->app->environment('testing')) {
    throw new RuntimeException(
        'Refusing to refresh the database while APP_ENV is not "testing". '
        .'Ensure phpunit.xml is loaded (do not use --no-configuration).'
    );
}

Consider also shipping a similar check in the default application tests/TestCase.php skeleton.

An escape hatch (for example RefreshDatabase::$force = true) could cover exotic CI setups.

Environment

• Laravel: 11.x (also relevant to 10.x / 12.x)
• PHPUnit: 10.x / 11.x
• Database: MySQL / MariaDB (also affects PostgreSQL, etc.)

Additional context

We mitigated this in our applications with Tests\Support\TestingEnvironmentGuard called from TestCase::setUp() and createApplication(). This should arguably be framework-default behavior so every Laravel project gets the guard without copying custom code.

Related docs already imply this contract:

• Testing database configuration in phpunit.xml
• .env.testing / APP_ENV=testing
• Separate test database or :memory: SQLite

The missing piece is runtime enforcement inside RefreshDatabase, mirroring the spirit of DB::prohibitDestructiveCommands() for production CLI.

Related (searched 2026-07-05 — no exact duplicate open)

Link	Relevance
PR #30391 (closed, not merged)	Same problem class — block RefreshDatabase when misconfigured. Only targeted production (isProduction()). Taylor closed: PHPUnit should not be installed in production. Does not cover local dev + APP_ENV=local + --no-configuration.
Issue #58985 (closed, fixed)	DB_URL in .env bypassed phpunit.xml → tests/RefreshDatabase hit staging DB. Fixed in skeleton via laravel/laravel#6761. Different vector from --no-configuration.
Issue #12874	Wrong DB during tests when config cached — closed as configuration issue.
Issue #31924	PHPUnit using wrong connection — closed; phpunit.xml must override DB_CONNECTION.
Issue #32556	.env.testing vs phpunit.xml precedence — closed; team will not change override order.
Issue #55194 (open)	migrate:fresh / RefreshDatabase with multiple DB connections — tangential for multi-DB apps.

This proposal fills a gap: enforce the documented APP_ENV=testing contract inside RefreshDatabase itself, for local and staging, not only production CLI.

[trtajim]

This seems like a valuable safeguard, but I have one question about the choice of APP_ENV as the deciding factor.

Is APP_ENV=testing really the right condition to enforce, or is the underlying requirement simply "don't run destructive refreshes against a non-test database"?

I can imagine CI pipelines or custom test environments where APP_ENV isn't literally testing, yet the database is still disposable. Likewise, a misconfigured application could have APP_ENV=testing while pointing at an important database.

Would validating the target database (or requiring an explicit opt-in for destructive refreshes) be a more robust safeguard than relying solely on the environment name?