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

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

​

Testbench Workbench란

Orchestra Testbench는 테스트용이지만, Workbench를 조합하면 패키지 리포지토리 내에 작은 Laravel 앱을 만들어 손끝에서 동작시킬 수 있습니다.

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

​

셋업

1. Testbench를 설치한다

   composer require --dev orchestra/testbench
   
2. Workbench를 작성한다

   vendor/bin/testbench workbench:install
   

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

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

   추가 옵션:

   • --force : 기존 파일을 덮어씀
   • --basic : 라우트·package discovery 설정을 생략한 심플한 구성
   • --devtool : DevTool 서포트를 활성화
3. 빌드하여 기동한다

   composer clear
   composer prepare
   composer build
   vendor/bin/testbench serve
   

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

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

{
    "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에서 관리합니다.

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

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에서 관리할 수 있습니다.

env:
  - APP_ENV=testing
  - APP_KEY=base64:your-app-key
  - DB_CONNECTION=sqlite
  - DB_DATABASE=:memory:

​

workbench 디렉토리 구조

workbench

app

Http

Models

Providers

bootstrap

config

database

factories

migrations

seeders

public

resources

routes

storage

​

Workbench가 제공하는 주요 기능

​

WorkbenchServiceProvider

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

<?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에 검증 라우트를 둘 수 있습니다.

use Illuminate\Support\Facades\Route;
use Vendor\Package\Facades\Package;

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

​

마이그레이션과 Seeder

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

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

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 커맨드를 실행할 수 있습니다.

vendor/bin/testbench list
vendor/bin/testbench route:list
vendor/bin/testbench migrate:fresh --seed

​

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

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

<?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/에서 화면·도선·통합 거동을 확인

​

트러블슈팅

# クリアしてフルリビルド
composer clear && composer prepare && composer build

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

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

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

Workbench를 빌드할 수 없음

testbench.yaml의 구문과 프로바이더 설정을 확인해 주세요. YAML의 인덴트 에러가 원인이 되는 경우가 있습니다.

라우트가 로드되지 않음

라우트 파일의 경로와 WorkbenchServiceProvider의 등록을 확인해 주세요. testbench.yaml의 discovers.web이 true로 되어 있는지 확인합니다.

데이터베이스 에러가 발생함

마이그레이션의 경로가 올바른지 확인해 주세요. SQLite를 사용하는 경우에는 create-sqlite-db 빌드 스텝이 포함되어 있는지 확인합니다.

​

관련 페이지

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

패키지 테스트 기반의 만드는 법을 먼저 확인합니다.

패키지의 버전 호환성 관리

Laravel과 Testbench의 대응표와 CI 매트릭스 운용을 확인합니다.

Source: invokable/laravel-bluesky docs/workbench.md, Orchestra Testbench