> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Orchestra Testbench를 사용해 Laravel 패키지의 테스트 환경을 구축하고, 서비스 프로바이더·파사드·설정·DB를 검증하는 절차를 해설합니다.

## Orchestra Testbench란

[Orchestra Testbench](https://github.com/orchestral/testbench)는, 패키지 개발용 Laravel 테스트 헬퍼입니다. `Orchestra\Testbench\TestCase`를 상속하면, 패키지 단독으로도 Laravel 애플리케이션 내와 같은 감각으로 테스트할 수 있습니다.

Laravel 공식 문서의 [패키지 개발](/ko/advanced/package-development)에서도, 패키지 테스트에는 Testbench를 사용하는 것이 안내되고 있습니다.

```mermaid theme={null}
flowchart TD
    A["PHPUnit / Pest"] --> B["Package TestCase<br>extends Orchestra\\Testbench\\TestCase"]
    B --> C["getPackageProviders() 로<br>서비스 프로바이더 등록"]
    C --> D["인메모리 Laravel 앱 기동"]
    D --> E["패키지 기능 검증"]
```

## 셋업

<Steps>
  <Step title="Testbench 설치하기">
    ```bash theme={null}
    composer require --dev orchestra/testbench
    ```
  </Step>

  <Step title="베이스 TestCase 작성하기">
    ```php theme={null}
    <?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,
            ];
        }
    }
    ```
  </Step>

  <Step title="필요하다면 설정이나 별칭 추가하기">
    `getPackageAliases()`에서는, `config/app.php`의 `aliases`와 마찬가지로, 테스트 중에 사용하는 파사드 별칭을 등록할 수 있습니다.

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

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

## 기본적인 테스트 작성법

서비스 프로바이더가 로드되어 있는지, 파사드가 기대대로 동작하는지, 설정이 반영되는지를 먼저 확인합니다.

```php theme={null}
<?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 theme={null}
<?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');
    }
}
```

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

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

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

Testbench의 메이저 버전은 Laravel의 메이저 버전에 대응합니다. 자세한 것은 공식의 [Version Compatibility](https://packages.tools/testbench)를 확인해 주세요.

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

여러 버전을 지속적으로 검증하는 경우에는, GitHub Actions의 매트릭스와 조합합니다. 설계의 사고방식은 [패키지의 버전 호환성 관리](/ko/advanced/package-versioning)를 참조해 주세요.

```yaml theme={null}
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까지 테스트 대상에 포함시킴으로써, 릴리스 후의 결함을 크게 줄일 수 있습니다.

## 관련 페이지

<Columns cols={2}>
  <Card title="Laravel 패키지 개발" icon="box" href="/ko/advanced/package-development">
    서비스 프로바이더를 중심으로 한 패키지 구현의 기본을 확인합니다.
  </Card>

  <Card title="패키지의 버전 호환성 관리" icon="git-branch" href="/ko/advanced/package-versioning">
    Laravel과 Testbench의 버전 전략과 CI 매트릭스 운용을 확인합니다.
  </Card>
</Columns>


## Related topics

- [Testbench Workbench로 패키지 개발 진행하기](/ko/advanced/package-workbench.md)
- [패키지의 CHANGELOG와 릴리스 관리](/ko/advanced/package-changelog.md)
- [GeneratorCommand — 커스텀 make: 명령어 구현](/ko/advanced/generator-command.md)
- [패키지의 정적 해석 (PHPStan / Larastan)](/ko/advanced/package-static-analysis.md)
- [Laravel 패키지 개발](/ko/advanced/package-development.md)