Testing Laravel packages with Orchestra Testbench

What is Orchestra Testbench?

Orchestra Testbench is a Laravel testing helper designed for package development. By extending Orchestra\Testbench\TestCase, you can test your package in isolation while still booting a Laravel application context. Laravel’s package documentation also recommends Testbench for package testing workflows. See Laravel Package Development.

Setup

Install Testbench

composer require --dev orchestra/testbench

Create your base TestCase

<?php

namespace Vendor\Package\Tests;

use Orchestra\Testbench\TestCase as BaseTestCase;
use Vendor\Package\PackageServiceProvider;

abstract class TestCase extends BaseTestCase
{
    /**
     * $app is the Laravel application instance booted by Testbench.
     */
    protected function getPackageProviders($app): array
    {
        return [
            PackageServiceProvider::class,
        ];
    }
}

Add aliases or environment overrides if needed

Use getPackageAliases() to register facade aliases for tests, similar to the aliases section in config/app.php.

protected function getPackageAliases($app): array
{
    return [
        'Package' => \Vendor\Package\Facades\Package::class,
    ];
}

protected function defineEnvironment($app): void
{
    // Override config values for tests
    $app['config']->set('package.enabled', true);
}

Writing your first tests

Start by testing package bootstrap behavior: provider registration, facade calls, and configuration values.

<?php

namespace Vendor\Package\Tests\Feature;

use Vendor\Package\Facades\Package;
use Vendor\Package\PackageServiceProvider;
use Vendor\Package\Tests\TestCase;

class PackageBootstrapTest extends TestCase
{
    public function test_service_provider_is_registered(): void
    {
        $this->assertTrue($this->app->providerIsLoaded(PackageServiceProvider::class));
    }

    public function test_facade_returns_expected_value(): void
    {
        // Verify behavior through the facade
        $this->assertSame('ok', Package::status());
    }

    public function test_package_config_is_available(): void
    {
        // Assert the value configured in defineEnvironment()
        $this->assertTrue(config('package.enabled'));
    }
}

Filesystem and database testing

For database tests, configure SQLite in-memory in defineEnvironment() and load your package migrations.

<?php

namespace Vendor\Package\Tests;

use Orchestra\Testbench\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function defineEnvironment($app): void
    {
        // Use SQLite in-memory for fast tests
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.testing', [
            'driver' => 'sqlite',
            'database' => ':memory:',
            'prefix' => '',
        ]);
    }

    protected function setUp(): void
    {
        parent::setUp();

        // Load package migrations
        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
    }
}

public function test_it_persists_data(): void
{
    \DB::table('widgets')->insert(['name' => 'test']);

    $this->assertDatabaseHas('widgets', ['name' => 'test']);
}

Testing across Laravel versions

Testbench major versions align with Laravel major versions. Check the official Version Compatibility table for updates.

Laravel	Testbench
12.x	10.x
13.x	11.x

Use a GitHub Actions matrix to keep compatibility verified continuously. For strategy details, see Package Version Compatibility Management.

strategy:
  fail-fast: false
  matrix:
    php: [8.3, 8.4]
    laravel: ["^12.0", "^13.0"]
    include:
      - laravel: "^13.0"
        testbench: "^11.0"
      - laravel: "^12.0"
        testbench: "^10.0"

Summary

Testbench gives you a reliable, app-like test environment for package development without creating a full Laravel app manually. By covering providers, config, facades, and database behavior, you reduce regressions before release.

Laravel package development

Review package implementation fundamentals centered on service providers.

Package version compatibility management

Learn versioning strategy and CI matrix design for Laravel and Testbench.

Documentation Index

​What is Orchestra Testbench?

​Setup

​Writing your first tests

​Filesystem and database testing

​Testing across Laravel versions

​Summary

​Related pages