Testing Laravel packages with Orchestra Testbench

Set up Orchestra Testbench for Laravel package testing and verify service providers, facades, configuration, and database behavior.

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

1. Install Testbench

   composer require --dev orchestra/testbench
   
2. 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,
           ];
       }
   }
   
3. 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.

Related pages

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.