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