Troubleshooting

This section is here to help if you're having trouble getting Adapt to work properly.

Usage Notes

Please review the usage notes first for general things that you might need to take into account.

Logging

The next thing you should try is to turn logging on. This will give you a much better idea of what's going on.

Please see the logging section for more details.

Adapt Doesn't Seem to Run

When Using BitBucket Pipelines

When using Adapt, the user you connect to the database with needs to have permission to create and drop databases.

When running in environments like BitBucket Pipelines, connecting with the root user will solve this.

When Using an Old Version of Laravel

If you're using an old version of Laravel (<= 5.4), you'll need to register Adapt's service-provider, AdaptLaravelServiceProvider yourself.

Don't add it to your config/app.php file because that will try to load it in production (where it won't be available, as you should have added Adapt to your project using --dev).

Instead, add the following to your app/Providers/AppServiceProvider.php. This will enable Adapt in your local and testing environments.

<?php
// app/Providers/AppServiceProvider.php

namespace App\Providers;
…
use CodeDistortion\Adapt\AdaptLaravelServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    …
    public function register()
    {
        if (class_exists(AdaptLaravelServiceProvider::class)) {
            $this->app->register(AdaptLaravelServiceProvider::class);
        }
        …
    }
}

When Using an Old Version of PHPUnit

Adapt uses the @before docblock annotation to trigger the database building process.

If you find that Adapt doesn't build your databases when using older versions of PHPUnit, you can trigger this process yourself.

Just update your TestCase class with the following tweak:

<?php
// tests/TestCase.php

namespace Tests;

use CodeDistortion\Adapt\AdaptDatabase;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;

    // **** add the setUp() method if it doesn't exist ****
    protected function setUp(): void
    {
        parent::setUp();

        // **** this will trigger Adapt whenever
        // AdaptDatabase has been added to a test ****
        AdaptDatabase::initialiseAdaptIfNeeded($this);
    }
}

Slowness When Using a HDD

If you use a HDD (i.e. with spinning disk platters) instead of an SSD, disk accesses will be slower.

A good place to start would be to run your databases in a memory filesystem (SQLite, MySQL & PostgreSQL).

There are also some Adapt settings you can turn off to speed things up…

Stale Databases

Before running your tests, Adapt looks through the filesystem to create a checksum of your migrations, seeders etc. When the checksum changes, it knows that it needs to build new databases for your tests.

TIP

You can see how long this step takes by turning logging on. e.g.

Generated a build-source checksum based on file modified timestamps (10ms)

As well as that, Adapt looks through the existing databases and snapshot files to find ones that are "stale". It removes these after a grace-period. e.g.

Looking for stale things to remove
Retrieved database list (connection: "mysql", driver: "mysql") (5ms)
- Found database "db_4a3b17_a32454a721ed" (usable) (3ms)
- Found database "db_4a3b17_c67c70f1e46f" (usable) (1ms)
Retrieved snapshot list (0ms)
- Found snapshot "/var/www/html/database/adapt-test-storage/snapshots/snapshot.db.4a3b17-3af4f9b38325.sqlite" (usable) (0ms)
Nothing found to remove - total time taken (11ms)

Both of these steps are usually quite quick, but if you find they're slowing down your tests, you can disable them.

---

You can turn off the step that removes stale databases by changing Adapt's cache_invalidation.purge_stale config setting.

TIP

When turned off, you may want to clear old databases and snapshot files yourself from time-to-time, to free-up space:

php artisan adapt:clear
# or
php artisan adapt:clear --force

---

If you want to take it further, you can turn the detection of changes off altogether by changing Adapt's cache_invalidation.enabled config setting.

WARNING

When turned off, Adapt won't detect changes made to your migrations and seeders etc.

In this situation, you will need to clear the databases and snapshot files yourself as you make changes to your code:

php artisan adapt:clear
# or
php artisan adapt:clear --force

You can read more about cache-invalidation in the section about rebuilding your database.

Browser Tests With Multiple Codebases

If you've placed different Laravel codebases behind a reverse-proxy, you may need to be aware of the following when running Dusk browser tests:

• You may need to use a custom APP_URL value in .env.testing, so that the browser makes requests via your reverse-proxy, instead of http://localhost. e.g.

  # .env.testing
  APP_URL=https://nginx
  

• If you're using a custom hostname (as above), you'll probably want to tell the Chrome browser to ignore certificate errors. This will let it visit https pages without needing to set up a certificate.

  // tests/DuskTestCase.php
  
  // instead of
  protected function driver()
  {
      return RemoteWebDriver::create(
          'http://localhost:9515', DesiredCapabilities::chrome()
      );
  }
  
  // specify additional arguments with something like…
  protected function driver()
  {
      $extraArguments = ['--ignore-certificate-errors'];
      $chromeOptions = (new ChromeOptions())->addArguments($extraArguments);
      $capabilites = DesiredCapabilities::chrome();
      $capabilites->setCapability(ChromeOptions::CAPABILITY, $chromeOptions);
      return RemoteWebDriver::create('http://localhost:9515', $capabilites);
  }
  

• For $browser->loginAs($user) to work, you will need to use a SESSION_DRIVER that both Laravel codebases can access (e.g. "database"). e.g.

  # .env.testing
  SESSION_DRIVER=database
  

Having Other Issues?

If you encounter other issues, please reach out on Twitter, and if you've found any bugs, please raise a ticket.