DatabaseTruncation combined with a transactional base TestCase silently runs migrate:fresh on every test and never truncates

[evan-burrell]

Laravel Version: 13.32.0
PHP Version: 8.3.33
Database Driver & Version: MySQL 8.0.30

---

Description

When a base TestCase uses RefreshDatabase (or LazilyRefreshDatabase) and an individual test class uses DatabaseTruncation, both strategies are applied. Two things then go wrong:

• The schema is rebuilt from scratch on every test — twice per test, in fact.
• The tables are never truncated at all. truncateTablesForAllConnections() is never reached; isolation comes incidentally from the migrate:fresh that replaces it.

On a clean Laravel 13.32.0 app with 43 migrations, a 3-test class issued 294 CREATE TABLE and 0 TRUNCATE statements, against an expected 49 and 2.

The tests still pass, so nothing signals that anything is wrong. The only visible symptom is the suite getting dramatically slower.

Why both traits get applied

setUpTraits() resolves strategies with class_uses_recursive(static::class), which does not distinguish a trait used directly by the test class from one inherited via the base class. The four strategies are then dispatched as independent if blocks with no mutual exclusion:

https://github.com/laravel/framework/blob/13.x/src/Illuminate/Foundation/Testing/Concerns/InteractsWithTestCaseLifecycle.php

if (isset($uses[RefreshDatabase::class]))      { $this->refreshDatabase(); }
if (isset($uses[DatabaseMigrations::class]))   { $this->runDatabaseMigrations(); }
if (isset($uses[DatabaseTruncation::class]))   { $this->truncateDatabaseTables(); }
if (isset($uses[DatabaseTransactions::class])) { $this->beginDatabaseTransaction(); }

So a class that inherits LazilyRefreshDatabase and adds DatabaseTruncation gets both, with no error or warning.

Why that produces a rebuild per test

RefreshDatabase::beginDatabaseTransaction() registers a teardown that invalidates the migrated state if the connection is no longer inside the transaction it opened:

if ($connection->getPdo() && ! $connection->getPdo()->inTransaction()) {
    RefreshDatabaseState::$migrated = false;
}

In isolation this is correct and deliberate — a test that committed has escaped the rollback guarantee, so rebuilding is the safe recovery. But DatabaseTruncation commits by design; that is its entire purpose. So the condition is true after every test, and $migrated is reset every time.

DatabaseTruncation::truncateDatabaseTables() then re-enters its first-run branch on every subsequent test:

if (! RefreshDatabaseState::$migrated) {
    $this->artisan('migrate:fresh', $this->migrateFreshUsing());

    $this->app[Kernel::class]->setArtisan(null);

    RefreshDatabaseState::$migrated = true;

    return; // <- returns before truncateTablesForAllConnections()
}

Note the early return. The tables are never truncated at all; isolation ends up being provided incidentally by the migrate:fresh that precedes it.

The root cause is that three traits share one static flag, RefreshDatabaseState::$migrated, while assigning it different meanings — "DB is migrated and safe for transactional use" in RefreshDatabase, versus "the one-time migrate:fresh has happened" in DatabaseTruncation.

DatabaseTruncation used on its own is unaffected, because RefreshDatabase.php is the only place that resets the flag.

Why this is easy to hit

• Putting RefreshDatabase/LazilyRefreshDatabase on a base TestCase is a common and reasonable layout.
• Adding DatabaseTruncation to a single class then looks like selecting a different strategy for that class. It isn't — traits compose rather than override.
• Nothing fails. The only symptom is speed.
• The documentation says to use DatabaseMigrations or DatabaseTruncation "instead" of RefreshDatabase, but does not state that the traits are mutually exclusive, and all examples apply a trait to a test class without discussing a base class that already has one.

Steps To Reproduce

Reproduced on a clean laravel new app (Laravel 13.32.0, PHP 8.3.33, MySQL 8.0.30) with 40 trivial padding migrations added so a rebuild is measurable (43 migrations, 49 tables total).

1. Base test case:

namespace Tests;

use Illuminate\Foundation\Testing\LazilyRefreshDatabase;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    use LazilyRefreshDatabase;
}

2. A test class opting into truncation. The tests must actually touch the database — with LazilyRefreshDatabase nothing happens until a query runs:

namespace Tests\Feature;

use Illuminate\Foundation\Testing\DatabaseTruncation;
use Illuminate\Support\Facades\DB;
use Tests\TestCase;

class TruncationTest extends TestCase
{
    use DatabaseTruncation;

    private function touchDatabase(): void
    {
        DB::table('pad_001')->insert(['name' => 'x']);
        $this->assertSame(1, DB::table('pad_001')->count());
    }

    public function test_one(): void   { $this->touchDatabase(); }
    public function test_two(): void   { $this->touchDatabase(); }
    public function test_three(): void { $this->touchDatabase(); }
}

3. Drop and recreate the test schema, then run the class while watching MySQL's own counters:

SHOW GLOBAL STATUS LIKE 'Com_create_table';
SHOW GLOBAL STATUS LIKE 'Com_truncate';

Expected: one migrate:fresh on the first test (49 CREATE TABLE), then a truncation pass before each subsequent test (2 TRUNCATE batches).

Actual: six full schema rebuilds and no truncation at all.

Measurement

Identical 3 tests, same app, same machine:

Setup	CREATE TABLE	TRUNCATE	Wall
LazilyRefreshDatabase base + DatabaseTruncation	294 (6 rebuilds)	0	3808ms
Same, with refreshDatabase() overridden to a no-op	49 (1 rebuild)	2	930ms

The tests pass in both cases.

Note the count: 294 = 3 tests x 2 rebuilds x 49 tables. There appear to be two rebuilds per test, because truncateDatabaseTables() invokes artisan('migrate:fresh'), whose query activity trips LazilyRefreshDatabase's beforeExecuting hook mid-flight and nests a second migrateDatabases() inside the first. beginDatabaseTransaction() then registers its teardown, which finds the connection outside a transaction (the DDL having implicitly committed), resets $migrated, and the cycle repeats on the next test.

Because $migrated is false on entry to every test, truncateDatabaseTables() always takes the early-return branch, which is why truncateTablesForAllConnections() is never reached and Com_truncate stays at zero.

For scale, on a real application (112 migrations, 87 tests across 6 classes) the same collision cost roughly 9x: one 6-test class took 36.1s instead of 4.1s.

Possible directions

I'm happy to open a PR, but the right approach isn't obvious to me and I'd rather ask than guess:

1. Throw when more than one strategy resolves in setUpTraits(). Clearest signal, and everything needed is already in scope at that point — but it would break any application currently combining traits, so presumably it could only be considered for a major release.

2. Give one strategy precedence — e.g. skip refreshDatabase() when DatabaseTruncation is present. Non-erroring and strictly faster, but it does change behaviour for existing combined setups.

3. Stop the teardown reset clobbering truncation's state. Closest to root cause. RefreshDatabaseState::$migrated is documented as "indicates if the test database has been migrated", which is a legitimately shared concern; the issue is that a RefreshDatabase-specific recovery path writes to it. I'd want to understand the original motivation for that reset before narrowing it, so as not to reintroduce whatever it was guarding against.

Happy to implement whichever of these you'd accept, or something else entirely.

Workaround

For anyone who lands here from a search: override refreshDatabase() to a no-op in the truncating test class, so no transaction is ever opened. A trait used directly by the class takes precedence over the method inherited from the parent, so this suppresses the transactional strategy while leaving truncation intact.

---

[HIRATRA]

I dug a little deeper into the interaction between LazilyRefreshDatabase and DatabaseTruncation, and I think there may be a second issue beyond the shared $migrated flag.

LazilyRefreshDatabase registers a beforeExecuting callback on the database connection, while DatabaseTruncation::truncateDatabaseTables() runs migrate:fresh() when $migrated is false.

This means the queries triggered by migrate:fresh() can themselves wake up the lazy refresh callback, potentially causing RefreshDatabase to enter its migration path while DatabaseTruncation is already performing its own refresh.

So there seem to be two separate concerns:

1. RefreshDatabaseState::$migrated is shared between strategies with different semantics.
2. LazilyRefreshDatabase has no apparent guard to prevent its beforeExecuting callback from being triggered during framework-controlled operations such as migrate:fresh().

I wonder if temporarily disabling the lazy-refresh callback during migrate:fresh() could be a safer approach than relying only on the shared $migrated state.

I haven't tested this approach yet, so I'd be interested to hear whether there are cases where the beforeExecuting hook intentionally needs to fire during migrate:fresh().