メインコンテンツへスキップ

​
Orchestra Testbenchとは

Orchestra Testbench は、パッケージ開発向けのLaravelテストヘルパーです。Orchestra\Testbench\TestCase を継承すると、パッケージ単体でもLaravelアプリケーション内と同じ感覚でテストできます。 Laravel公式ドキュメントのパッケージ開発でも、パッケージテストにはTestbenchを使うことが案内されています。

​
セットアップ

1

Testbenchをインストールする

composer require --dev orchestra/testbench
2

ベースのTestCaseを作成する

<?php

namespace Vendor\Package\Tests;

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

abstract class TestCase extends BaseTestCase
{
    /**
     * $app はTestbenchが起動したLaravelアプリケーションインスタンス。
     */
    protected function getPackageProviders($app): array
    {
        return [
            PackageServiceProvider::class,
        ];
    }
}
3

必要なら設定やエイリアスを追加する

getPackageAliases() では、config/app.php の aliases と同様に、テスト中に使うファサードエイリアスを登録できます。
protected function getPackageAliases($app): array
{
    return [
        'Package' => \Vendor\Package\Facades\Package::class,
    ];
}

protected function defineEnvironment($app): void
{
    // テスト用設定をここで上書きする
    $app['config']->set('package.enabled', true);
}

​
基本的なテストの書き方

サービスプロバイダーが読み込まれているか、ファサードが期待どおり動くか、設定が反映されているかを最初に確認します。 
<?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
    {
        // ファサード経由で機能を検証する
        $this->assertSame('ok', Package::status());
    }

    public function test_package_config_is_available(): void
    {
        // defineEnvironment()で設定した値を確認する
        $this->assertTrue(config('package.enabled'));
    }
}

​
ファイルシステム・データベースのテスト

DBを使うテストでは、defineEnvironment() でSQLiteインメモリを設定し、テスト対象のマイグレーションを読み込みます。 
<?php

namespace Vendor\Package\Tests;

use Orchestra\Testbench\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function defineEnvironment($app): void
    {
        // SQLiteインメモリDBを使う
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.testing', [
            'driver' => 'sqlite',
            'database' => ':memory:',
            'prefix' => '',
        ]);
    }

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

        // パッケージのマイグレーションを読み込む
        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
    }
}

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

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

​
複数Laravelバージョンでのテスト

TestbenchのメジャーバージョンはLaravelのメジャーバージョンに対応します。詳細は公式のVersion Compatibilityを確認してください。
LaravelTestbench
12.x10.x
13.x11.x
複数バージョンを継続検証する場合は、GitHub Actionsのマトリクスと組み合わせます。設計の考え方はパッケージのバージョン互換性管理を参照してください。 
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"

​
まとめ

Testbenchを使うと、Laravelアプリを手動で用意しなくても、パッケージの振る舞いを実運用に近い形で検証できます。サービスプロバイダー登録、設定、ファサード、DBまでテスト対象に含めることで、リリース後の不具合を大きく減らせます。

​
関連ページ

Laravelパッケージ開発

サービスプロバイダーを中心にしたパッケージ実装の基本を確認します。

パッケージのバージョン互換性管理

LaravelとTestbenchのバージョン戦略とCIマトリクス運用を確認します。
最終更新日 2026年4月23日