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

# Testbench Workbench로 패키지 개발 진행하기

> Orchestra Testbench Workbench를 사용해, 라우트·마이그레이션·서비스 부팅을 갖춘 실제 앱에 가까운 검증 환경을 만드는 방법을 해설합니다.

## Testbench Workbench란

[Orchestra Testbench](https://github.com/orchestral/testbench)는 테스트용이지만, Workbench를 조합하면 패키지 리포지토리 내에 작은 Laravel 앱을 만들어 손끝에서 동작시킬 수 있습니다.

`package-testing`에서 만든 테스트를 보완하면서, UI 확인, 라우트 소통, 시더 딸린 검증을 진행하고 싶을 때 사용합니다.

```mermaid theme={null}
flowchart TD
    A["패키지 본체<br>`src/`"] --> B["Workbench<br>`workbench/`"]
    B --> C["WorkbenchServiceProvider<br>데모용 서비스 등록"]
    B --> D["라우트·컨트롤러<br>화면 확인"]
    B --> E["마이그레이션·Seeder<br>데이터 검증"]
    B --> F["`composer serve`<br>로컬 기동"]
    C --> G["testbench.yaml<br>프로바이더/빌드 설정"]
```

## 셋업

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

  <Step title="Workbench를 작성한다">
    ```bash theme={null}
    vendor/bin/testbench workbench:install
    ```

    이 커맨드는 이하를 한꺼번에 실행합니다.

    * `workbench/` 디렉토리 구조를 작성
    * `composer.json`의 `autoload-dev`에 Workbench 네임스페이스를 추가
    * `composer.json`의 `scripts`에 빌드용 커맨드를 추가

    <Tip>
      추가 옵션:

      * `--force` : 기존 파일을 덮어씀
      * `--basic` : 라우트·package discovery 설정을 생략한 심플한 구성
      * `--devtool` : DevTool 서포트를 활성화
    </Tip>
  </Step>

  <Step title="빌드하여 기동한다">
    ```bash theme={null}
    composer clear
    composer prepare
    composer build
    vendor/bin/testbench serve
    ```
  </Step>
</Steps>

<Info>
  `workbench:install`은 `workbench/` 디렉토리나 `autoload-dev`, 관련 스크립트를 한꺼번에 정비합니다.
</Info>

설치 후, `composer.json`에는 이하의 스크립트가 추가됩니다.

```json theme={null}
{
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/",
            "Workbench\\App\\": "workbench/app/",
            "Workbench\\Database\\Factories\\": "workbench/database/factories/",
            "Workbench\\Database\\Seeders\\": "workbench/database/seeders/"
        }
    },
    "scripts": {
        "post-autoload-dump": [
            "@clear",
            "@prepare"
        ],
        "clear": "@php vendor/bin/testbench package:purge-skeleton --ansi",
        "prepare": "@php vendor/bin/testbench package:discover --ansi",
        "build": "@php vendor/bin/testbench workbench:build --ansi",
        "serve": [
            "Composer\\Config::disableProcessTimeout",
            "@build",
            "@php vendor/bin/testbench serve --ansi"
        ]
    }
}
```

## testbench.yaml로 개발 환경을 정의한다

Workbench의 동작은 루트에 두는 `testbench.yaml`에서 관리합니다.

<Warning>
  `testbench.yaml`은 환경별로 다른 설정을 포함할 수 있으므로, `.gitignore`에 추가하여 커밋 대상에서 제외하는 것이 권장됩니다. 대신 `testbench.yaml.example`을 템플릿으로서 리포지토리에 포함해 주세요.
</Warning>

```yaml theme={null}
providers:
  - Vendor\Package\PackageServiceProvider
  - Workbench\App\Providers\WorkbenchServiceProvider

migrations:
  - workbench/database/migrations

workbench:
  start: '/'
  install: true
  health: false
  discovers:
    web: true
    api: false
    commands: false
    components: false
    views: false
    config: true
  build:
    - asset-publish
    - create-sqlite-db
    - db-wipe
    - migrate-fresh:
        --seed: true
        --seeder: Workbench\Database\Seeders\DatabaseSeeder
  assets:
    - laravel-assets
```

주요 설정 옵션:

| 키                     | 설명                               |
| --------------------- | -------------------------------- |
| `providers`           | Workbench 환경에서 로드하는 서비스 프로바이더 목록 |
| `migrations`          | 실행하는 마이그레이션 디렉토리                 |
| `workbench.start`     | `composer serve` 기동 시의 기본 URL    |
| `workbench.discovers` | Laravel의 패키지 자동 발견의 대상을 제어       |
| `workbench.build`     | 빌드 시에 실행하는 커맨드 목록                |

환경 변수도 `testbench.yaml`에서 관리할 수 있습니다.

```yaml theme={null}
env:
  - APP_ENV=testing
  - APP_KEY=base64:your-app-key
  - DB_CONNECTION=sqlite
  - DB_DATABASE=:memory:
```

## workbench 디렉토리 구조

<Tree>
  <Tree.Folder name="workbench" defaultOpen>
    <Tree.Folder name="app" defaultOpen>
      <Tree.Folder name="Http">
        <Tree.Folder name="Controllers" />
      </Tree.Folder>

      <Tree.Folder name="Models" />

      <Tree.Folder name="Providers">
        <Tree.File name="WorkbenchServiceProvider.php" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="bootstrap" />

    <Tree.Folder name="config" />

    <Tree.Folder name="database" defaultOpen>
      <Tree.Folder name="factories" />

      <Tree.Folder name="migrations" />

      <Tree.Folder name="seeders">
        <Tree.File name="DatabaseSeeder.php" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="public" />

    <Tree.Folder name="resources">
      <Tree.Folder name="views" />
    </Tree.Folder>

    <Tree.Folder name="routes">
      <Tree.File name="web.php" />

      <Tree.File name="api.php" />

      <Tree.File name="console.php" />
    </Tree.Folder>

    <Tree.Folder name="storage" />
  </Tree.Folder>
</Tree>

## Workbench가 제공하는 주요 기능

### WorkbenchServiceProvider

Workbench 전용의 서비스 프로바이더를 작성하여, 데모용의 등록 처리를 합니다.

```php theme={null}
<?php

namespace Workbench\App\Providers;

use Illuminate\Support\ServiceProvider;
use Vendor\Package\SomeClass;
use Workbench\App\Services\DemoService;

class WorkbenchServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(DemoService::class);
    }

    public function boot(): void
    {
        SomeClass::register('demo', DemoService::class);
        $this->loadRoutesFrom(__DIR__.'/../../routes/web.php');
        $this->loadViewsFrom(__DIR__.'/../../resources/views', 'workbench');
    }
}
```

### 라우트와 컨트롤러

`workbench/routes/web.php`나 `workbench/routes/api.php`에 검증 라우트를 둘 수 있습니다.

```php theme={null}
use Illuminate\Support\Facades\Route;
use Vendor\Package\Facades\Package;

Route::get('/', function () {
    return Package::status();
});
```

### 마이그레이션과 Seeder

`workbench/database/migrations`와 `workbench/database/seeders`를 사용하면, 실운용에 가까운 데이터 구조로 검증할 수 있습니다.

```php theme={null}
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('widgets', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});
```

Seeder로 테스트 데이터를 생성합니다.

```php theme={null}
<?php

namespace Workbench\Database\Seeders;

use Illuminate\Database\Seeder;
use Workbench\Database\Factories\UserFactory;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        UserFactory::new()->count(10)->create();
    }
}
```

### 서비스 기동과 CLI 확인

`vendor/bin/testbench` 경유로 Artisan 커맨드를 실행할 수 있습니다.

```bash theme={null}
vendor/bin/testbench list
vendor/bin/testbench route:list
vendor/bin/testbench migrate:fresh --seed
```

## WithWorkbench 트레이트를 사용한 테스트

`WithWorkbench` 트레이트를 사용하면, `testbench.yaml`의 설정이 자동 테스트에도 적용됩니다.

```php theme={null}
<?php

namespace Tests;

use Orchestra\Testbench\Concerns\WithWorkbench;
use Orchestra\Testbench\TestCase as Orchestra;

abstract class TestCase extends Orchestra
{
    use WithWorkbench;

    protected function getPackageProviders($app): array
    {
        return [
            \Vendor\Package\Providers\YourServiceProvider::class,
        ];
    }

    protected function defineEnvironment($app): void
    {
        $app['config']->set('database.default', 'testing');
        $app['config']->set('your-package.key', 'test-value');
    }
}
```

## 테스트와의 연계

Workbench는 "수동 확인·데모용 앱", Testbench의 테스트 코드는 "자동 검증"으로서 역할을 분담하면 운용하기 쉬워집니다.

* 자동화: `tests/`에서 회귀를 방지
* 수동 확인: `workbench/`에서 화면·도선·통합 거동을 확인

## 트러블슈팅

```bash theme={null}
# クリアしてフルリビルド
composer clear && composer prepare && composer build

# パッケージ自動発見を確認する
vendor/bin/testbench package:discover --ansi

# 設定を確認する
vendor/bin/testbench about

# ルート一覧を確認する
vendor/bin/testbench route:list
```

<AccordionGroup>
  <Accordion title="Workbench를 빌드할 수 없음">
    `testbench.yaml`의 구문과 프로바이더 설정을 확인해 주세요. YAML의 인덴트 에러가 원인이 되는 경우가 있습니다.
  </Accordion>

  <Accordion title="라우트가 로드되지 않음">
    라우트 파일의 경로와 WorkbenchServiceProvider의 등록을 확인해 주세요. `testbench.yaml`의 `discovers.web`이 `true`로 되어 있는지 확인합니다.
  </Accordion>

  <Accordion title="데이터베이스 에러가 발생함">
    마이그레이션의 경로가 올바른지 확인해 주세요. SQLite를 사용하는 경우에는 `create-sqlite-db` 빌드 스텝이 포함되어 있는지 확인합니다.
  </Accordion>
</AccordionGroup>

## 관련 페이지

<Columns cols={2}>
  <Card title="Orchestra Testbench로 Laravel 패키지를 테스트하기" icon="flask-conical" href="/ko/advanced/package-testing">
    패키지 테스트 기반의 만드는 법을 먼저 확인합니다.
  </Card>

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

<Info>
  Source: [invokable/laravel-bluesky docs/workbench.md](https://github.com/invokable/laravel-bluesky/blob/main/docs/workbench.md), [Orchestra Testbench](https://github.com/orchestral/testbench)
</Info>


## Related topics

- [Orchestra Testbench로 Laravel 패키지를 테스트하기](/ko/advanced/package-testing.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/ko/packages/laravel-boost-copilot-cli.md)
- [Inertia.js로 SPA 구축하기](/ko/blog/inertia-introduction.md)
- [패키지의 CHANGELOG와 릴리스 관리](/ko/advanced/package-changelog.md)
- [패키지의 정적 해석 (PHPStan / Larastan)](/ko/advanced/package-static-analysis.md)