> ## 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="/jp/advanced/package-testing">
    パッケージテスト基盤の作り方を先に確認します。
  </Card>

  <Card title="パッケージのバージョン互換性管理" icon="git-branch" href="/jp/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>