coders-tm/laravel-core / .agents/skills/testbench-docs
testbench-package-testing
VerifiedDevelops and tests Laravel packages using Orchestra Testbench. Activates when writing package tests, configuring testbench.yaml, managing migrations, defining routes/environment for tests, using Testbench Dusk for browser tests, or working with Workbench for package preview.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| api-examples.md | markdown | 907 B |
| getting-started.md | markdown | 3.2 KB |
| getting-started/configuration.md | markdown | 5.2 KB |
| markdown-examples.md | markdown | 1.0 KB |
| testbench-dusk.md | markdown | 3.3 KB |
| testbench-dusk/the-basic.md | markdown | 3.3 KB |
| testbench-dusk/troubleshooting.md | markdown | 1.7 KB |
| testbench.md | markdown | 2.7 KB |
| testbench/cli.md | markdown | 1.9 KB |
| testbench/integrations.md | markdown | 2.0 KB |
| testbench/the-basic.md | markdown | 6.4 KB |
| testbench/the-basic/databases.md | markdown | 5.0 KB |
| testbench/the-basic/environment.md | markdown | 4.9 KB |
| testbench/the-basic/routes.md | markdown | 2.3 KB |
| testbench/troubleshooting.md | markdown | 3.5 KB |
| workbench.md | markdown | 1.2 KB |
testbench/the-basic/databases.md
View on GitHub# Define Databases
It is recommended for a package to use `ServiceProvider::loadMigrationsFrom()` feature (it automatically handles migrations for packages when used in Laravel applications and during tests) or you can define migrations specifically for the tests environment using the recommended guide below.
## In-Memory SQLite Connection
To reduce setup configuration, you could use `testing` database connection (`:memory:` with `sqlite` driver) by defining it under PHPUnit Configuration File:
```xml
<phpunit>
// ...
<php>
<env name="DB_CONNECTION" value="testing"/> # [!code ++] # [!code focus]
</php>
</phpunit>
```
Otherwise, you can also use `Orchestra\Testbench\Attributes\WithEnv` attribute:
```php
use Orchestra\Testbench\Attributes\WithEnv; # [!code ++] # [!code focus]
#[WithEnv('DB_CONNECTION', 'testing')] # [!code ++] # [!code focus]
class TestCase extends \Orchestra\Testbench\TestCase
{
//
}
```
Alternatively, you can also explicitly set it up under `defineEnvironment()`:
```php
class TestCase extends \Orchestra\Testbench\TestCase
{
/**
* Define environment setup.
*
* @param \Illuminate\Foundation\Application $app
* @return void
*/
protected function defineEnvironment($app) # [!code ++:4] # [!code focus:4]
{
$app['config']->set('database.default', 'testing');
}
}
```
Lastly, you can also use `Orchestra\Testbench\Attributes\WithConfig` attribute:
```php{1,3}
use Orchestra\Testbench\Attributes\WithConfig; # [!code ++] # [!code focus]
#[WithConfig('database.default', 'testing')] # [!code ++] # [!code focus]
class TestCase extends \Orchestra\Testbench\TestCase
{
//
}
```
## Automatically execute migrations
By default, you can use the `RefreshDatabase` trait to *only* run package migrations defined through the package's service provider.
```php
use Illuminate\Foundation\Testing\RefreshDatabase; # [!code ++] # [!code focus]
class TestCase extends \Orchestra\Testbench\TestCase
{
use RefreshDatabase; # [!code ++] # [!code focus]
}
```
If you also need to run the default Laravel migrations such as the `users` table migration, see the [Run Laravel Migrations](#run-laravel-migrations) section.
## Manually execute migrations
Instead of just automatically migrating the database, you also manually configure migrations steps using the `defineDatabaseMigrations()` method:
```php
use function Orchestra\Testbench\artisan; # [!code ++]
class TestCase extends \Orchestra\Testbench\TestCase
{
/**
* Define database migrations.
*
* @return void
*/
protected function defineDatabaseMigrations() # [!code ++:8] # [!code focus:8]
{
artisan($this, 'migrate', ['--database' => 'testbench']);
$this->beforeApplicationDestroyed(
fn () => artisan($this, 'migrate:rollback', ['--database' => 'testbench'])
);
}
}
```
### Run Laravel Migrations
By default, Testbench doesn't execute the default Laravel migrations which include `users` and `password_resets` table. In order to run the migration just add the following command:
```php
use Orchestra\Testbench\Attributes\WithMigration; # [!code ++] # [!code focus]
#[WithMigration] # [!code ++] # [!code focus]
class TestCase extends \Orchestra\Testbench\TestCase
{
//
}
```
You can also run migrations for `cache`, `queue`, `notifications` or `session` by providing additional paramters to `Orchestra\Testbench\Attributes\WithMigration` attribute:
```php
use Orchestra\Testbench\Attributes\WithMigration;
#[WithMigration('laravel', 'cache', 'queue')] # [!code ++:2] # [!code focus:2]
#[WithMigration('session')]
class TestCase extends \Orchestra\Testbench\TestCase
{
//
}
```
### Run Testing Migrations
To run migrations that are only used for testing purposes and not part of your package, add the following to your base test class:
```php
use function Orchestra\Testbench\workbench_path; # [!code hl]
class TestCase extends \Orchestra\Testbench\TestCase
{
/**
* Define database migrations.
*
* @return void
*/
protected function defineDatabaseMigrations() # [!code ++:6] # [!code focus:6]
{
$this->loadMigrationsFrom(
workbench_path('database/migrations')
);
}
}
```
### Using Database Transactions
You may also utilize `DatabaseTransactions` for a migrated state using the following:
```php{1,5}
use Illuminate\Foundation\Testing\DatabaseTransactions; # [!code ++] # [!code focus]
class TestCase extends \Orchestra\Testbench\TestCase
{
use DatabaseTransactions; # [!code ++] # [!code focus]
}
```
::: details NOTES & CONSIDERATIONS
* Your migration files have to suite Laravel's convention, e.g. `0000_00_00_000000_create_package_test_tables.php`.
* You may choose to put your migrations folder in `workbench/database/migrations`.
* You may choose to change your test-migrations class name to be different from the published class names, e.g. from `CreateUsersTable` to `CreateUsersTestTable` or otherwise you may encounter composer class loader collision.
:::
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |