Orchestra Testbench로 Laravel 패키지를 테스트하기

Orchestra Testbench란

Orchestra Testbench는, 패키지 개발용 Laravel 테스트 헬퍼입니다. Orchestra\Testbench\TestCase를 상속하면, 패키지 단독으로도 Laravel 애플리케이션 내와 같은 감각으로 테스트할 수 있습니다. Laravel 공식 문서의 패키지 개발에서도, 패키지 테스트에는 Testbench를 사용하는 것이 안내되고 있습니다.

셋업

Testbench 설치하기

composer require --dev orchestra/testbench

베이스 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,
        ];
    }
}

필요하다면 설정이나 별칭 추가하기

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를 확인해 주세요.

Laravel	Testbench
12.x	10.x
13.x	11.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 매트릭스 운용을 확인합니다.

​Orchestra Testbench란

​셋업

​기본적인 테스트 작성법

​파일 시스템·데이터베이스의 테스트

​여러 Laravel 버전에서의 테스트

​정리

​관련 페이지