Usage

Quick-Start

Only a couple of steps are needed to get started:

1. Replace Laravel's RefreshDatabase, DatabaseMigrations and DatabaseTransactions traits in your tests with AdaptDatabase.
2. Then run your tests like normal. e.g.

# run tests using Laravel's test command
php artisan test
# run tests in parallel using Laravel's command
php artisan test --parallel
# run tests using Pest (if you use Pest)
./vendor/bin/pest
# run tests in parallel using Pest (if you use Pest)
./vendor/bin/pest --parallel
# run tests using PHPUnit directly
./vendor/bin/phpunit
# run tests in parallel using ParaTest directly
./vendor/bin/paratest

NOTE

As mentioned in the browser testing section; running tests using php artisan dusk might work, but is not preferred.

PHPUnit Usage

Use the AdaptDatabase trait in your test-classes instead of RefreshDatabase, DatabaseTransactions or DatabaseMigrations.

Add it to each test you'd like a database for.

<?php
// tests/Feature/MyFeatureTest.php

namespace Tests\Feature;

use CodeDistortion\Adapt\AdaptDatabase;
//use Illuminate\Foundation\Testing\DatabaseMigrations;   // not needed
//use Illuminate\Foundation\Testing\DatabaseTransactions; // not needed
//use Illuminate\Foundation\Testing\RefreshDatabase;      // not needed
use Tests\TestCase;

class MyFeatureTest extends TestCase
{
    use AdaptDatabase;
//  use DatabaseMigrations;   // not needed
//  use DatabaseTransactions; // not needed
//  use RefreshDatabase;      // not needed
    …
}

Then run your tests like normal. e.g.

php artisan test

TIP

You can customise Adapt's settings on a per-test basis, by adding properties to your test-classes.

PEST Usage

PEST lets you assign classes and traits to your Pest tests with the uses(…) helper function.

Add uses(AdaptDatabase::class); to the tests you'd like a database for.

<?php
// tests/Feature/MyFeatureTest.php

use App\User;
use CodeDistortion\Adapt\AdaptDatabase;
//use Illuminate\Foundation\Testing\DatabaseMigrations;   // not needed
//use Illuminate\Foundation\Testing\DatabaseTransactions; // not needed
//use Illuminate\Foundation\Testing\RefreshDatabase;      // not needed

uses(AdaptDatabase::class);
// uses(DatabaseMigrations::class);   // not needed
// uses(DatabaseTransactions::class); // not needed
// uses(RefreshDatabase::class);      // not needed

beforeEach(fn () => factory(User::class)->create());

it('has users')->assertDatabaseHas('users', ['id' => 1]);

Then run your tests like normal. e.g.

./vendor/bin/pest

TIP

You can customise Adapt's settings on a per-test basis, when using PEST.

Dusk Browser Test Usage

Please see the browser testing section for usage details.

Parallel Test Usage

Please see the parallel testing section for usage details.

Artisan Console Commands

Adapt has two artisan commands:

1. php artisan adapt:list Lists the databases and snapshot files that Adapt has created.
2. php artisan adapt:clear Removes them.

TIP

You don't need to remove old databases yourself. Adapt clears these (and old snapshot files) automatically.

Usage Notes

To carry out the different types of caching this package uses, you may need to be aware of the following:

• The user your tests run as needs to have write-access to the filesystem. The relevant location is defined in the storage_dir config value.
• When using MySQL or PostgreSQL, the user your code connects to your database server 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 MySQL, the mysql and mysqldump executables are used (when needed) to import sql-dumps and create snapshots. If these aren't in your system-path, you can specify their location in the database.mysql section of Adapt's config.
• When using PostgreSQL, the psql and pg_dump executables are used (when needed) to import sql-dumps and create snapshots. If these aren't in your system-path, you can specify their location in the database.pgsql section of Adapt's config.
• When using a shared database server, you should give each separate project a unique project_name config value. This stops Adapt from interfering with test-databases it doesn't own.
• If you see databases with names like "testing_17bd3c_d266ab43ac75", don't worry! These names are generated because of database scenarios. Leave them to get the speed benefit from reusing them (but you can safely delete them if you like).

If you're having trouble, please enable logging, and check out the troubleshooting section.