Under the hood: How RefreshDatabase works in Laravel tests
Tags: laravel, testing, underthehood
Published: 2019-09-02 06:32:35

---
title: Under the hood: How RefreshDatabase works in Laravel tests
published: true
tags: Laravel,Testing,Under the hood,laravel
canonical_url: https://42coders.com/under-the-hood-how-refreshdatabase-works-in-laravel-tests/
---

## 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](https://laravel.com/docs/5.8/database-testing#resetting-the-database-after-each-test).

## 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.
- The actual **test** is running
- After every test the **tearDown** method is running:
  - It calls the **beforeApplicationDestroyedCallbacks**
  - Closes Mockery, resets variables etc.

## 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);
    }
```

### 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;
        }
```

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);
        }
```

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();
            }
        });
```

## 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](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html). 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.

The post [Under the hood: How RefreshDatabase works in Laravel tests](https://42coders.com/under-the-hood-how-refreshdatabase-works-in-laravel-tests/) appeared first on [42 Coders](https://42coders.com).