Introduction

When writing test for any application it is crucial to every test run independently without affecting each other. If your tests use database, every test should run with a clean database. By clean I mean a known state, fresh migrated or seeded, not necessarily an empty one. Laravel offers an easy way to handle this using the RefreshDatabase trait. For more information about the usage of the trait please check the documentation here.

A test’s life cycle in Laravel

Before we dive into the details how refresh database works, let’s take a look at the test’s life cycle. Laravel ships with PHPUnit, so the life cycle of the tests is very similar to the PHPUnit tests life cycle. I won’t cover the details of the whole test running process, just stick to the points which are interesting for the current topic:

Before every test the setUp method is running: It creates/refreshes the laravel application Sets up traits Calls the afterApplicationCreatedCallbacks, sets up events, clears facade’s resolved instances, etc.

method is running: The actual test is running

is running After every test the tearDown method is running: It calls the beforeApplicationDestroyedCallbacks Closes Mockery, resets variables etc.

method is running:

The RefreshDatabase trait

If the test uses the RefreshDatabase trait, the setUpTraits calls the refreshDatabase() method from the trait, and the interesting part starts here. In tests you can use in memory and regular databases, depending on how you’ve set up the test environment, it will refresh the database accordingly.

The in memory database

In case of in memory database things are quite simple just migrates the database, it runs very fast, so it can be done before every test. Easy enough.

protected function refreshInMemoryDatabase() { $this->artisan('migrate'); $this->app[Kernel::class]->setArtisan(null); } 1 2 3 4 5 6 protected function refreshInMemoryDatabase ( ) { $this -> artisan ( 'migrate' ) ; $this -> app [ Kernel:: class ] -> setArtisan ( null ) ; }

Regular database

In other cases it only migrates the database, if it has not been migrated e.g. before running the first test.

if (! RefreshDatabaseState::$migrated) { $this->artisan('migrate:fresh', [ '--drop-views' => $this->shouldDropViews(), '--drop-types' => $this->shouldDropTypes(), ]); $this->app[Kernel::class]->setArtisan(null); RefreshDatabaseState::$migrated = true; } 1 2 3 4 5 6 7 8 9 10 if ( ! RefreshDatabaseState:: $migrated ) { $this -> artisan ( 'migrate:fresh' , [ '--drop-views' = > $this -> shouldDropViews ( ) , '--drop-types' = > $this -> shouldDropTypes ( ) , ] ) ; $this -> app [ Kernel:: class ] -> setArtisan ( null ) ; RefreshDatabaseState:: $migrated = true ; }

When the database has been migrated it starts a database transaction:

foreach ($this->connectionsToTransact() as $name) { $connection = $database->connection($name); $dispatcher = $connection->getEventDispatcher(); $connection->unsetEventDispatcher(); $connection->beginTransaction(); $connection->setEventDispatcher($dispatcher); } 1 2 3 4 5 6 7 8 foreach ( $this -> connectionsToTransact ( ) as $name ) { $connection = $database -> connection ( $name ) ; $dispatcher = $connection -> getEventDispatcher ( ) ; $connection -> unsetEventDispatcher ( ) ; $connection -> beginTransaction ( ) ; $connection -> setEventDispatcher ( $dispatcher ) ; }

and registers a beforeApplicationDestroyed callback where the transaction is rolled back. These callbacks are running in the tearDown method, so after every test. The rollback ensures that the database isn’t changed by the test, and the next test can run on a clean database.

$this->beforeApplicationDestroyed(function () use ($database) { foreach ($this->connectionsToTransact() as $name) { $connection = $database->connection($name); $dispatcher = $connection->getEventDispatcher(); $connection->unsetEventDispatcher(); $connection->rollback(); $connection->setEventDispatcher($dispatcher); $connection->disconnect(); } }); 1 2 3 4 5 6 7 8 9 10 11 $this -> beforeApplicationDestroyed ( function ( ) use ( $database ) { foreach ( $this -> connectionsToTransact ( ) as $name ) { $connection = $database -> connection ( $name ) ; $dispatcher = $connection -> getEventDispatcher ( ) ; $connection -> unsetEventDispatcher ( ) ; $connection -> rollback ( ) ; $connection -> setEventDispatcher ( $dispatcher ) ; $connection -> disconnect ( ) ; } } ) ;

Potential pitfalls

While the method described above works fine in most cases, I had some cases when I spent a couple of hours searching, debugging why my tests are failing and the database doesn’t get refreshed correctly.

As you might presume, the solution is NOT to commit the opened database transaction in tests, and avoid using statements which causes implicit commit in mysql. I made the second mistake by running an sql dump in one of my seeders, which created a table, and therefore implicitly committed the transaction. You can find out more about implicit commits in the mysql documentation. Self defense on: I know the database tables should be created with migrations, and seeders should be written with factories, but sometimes we need to do non optimal things :-).

Conclusion

The RefreshDatabase is a very useful feature when writing tests for Laravel application, just need to be careful with transaction commits in your tests.

Hope this article was useful, if you have any additions, remarks, please let me know in the comments section.

Related articles

If you like this article, please check the other posts of the series here.