使用 Testbench Workbench 进行包开发

什么是 Testbench Workbench

Orchestra Testbench 面向测试，但结合 Workbench 后可以在包仓库内构建一个小型 Laravel 应用，可以在本地跑起来。它用于补充 package-testing 中的测试，方便进行 UI 检查、路由联调、带 Seeder 的验证等。

搭建

安装 Testbench

composer require --dev orchestra/testbench

创建 Workbench

vendor/bin/testbench workbench:install

该命令会一次完成：

创建 workbench/ 目录结构
向 composer.json 的 autoload-dev 添加 Workbench 命名空间
向 composer.json 的 scripts 添加构建用命令

附加选项：

--force：覆盖已有文件
--basic：省略路由与包 discovery 配置的简洁结构
--devtool：启用 DevTool 支持

构建并启动

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 环境加载的 Service Provider 列表
`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 专用 Service Provider，用于演示相关的注册处理。

<?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');
    }
}

路由与 Controller

可以在 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 trait 进行测试

使用 WithWorkbench trait，可以将 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 的语法与 Provider 设置。可能是 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

AI 开发

设计模式

包开发

应用结构

Laravel 13 新特性

Eloquent 深入

验证扩展

认证扩展

安全

测试

使用 Testbench Workbench 进行包开发

什么是 Testbench Workbench

搭建

用 testbench.yaml 定义开发环境

workbench 目录结构

Workbench 提供的主要功能

WorkbenchServiceProvider

路由与 Controller

迁移与 Seeder

启动服务与 CLI 确认

使用 WithWorkbench trait 进行测试

与测试的联动

故障排查

相关页面

使用 Orchestra Testbench 测试 Laravel 包

包的版本兼容性管理

​什么是 Testbench Workbench

​搭建

​用 testbench.yaml 定义开发环境

​workbench 目录结构

​Workbench 提供的主要功能

​WorkbenchServiceProvider

​路由与 Controller

​迁移与 Seeder

​启动服务与 CLI 确认

​使用 WithWorkbench trait 进行测试

​与测试的联动

​故障排查

​相关页面

使用 Orchestra Testbench 测试 Laravel 包

包的版本兼容性管理

什么是 Testbench Workbench

搭建

用 testbench.yaml 定义开发环境

workbench 目录结构

Workbench 提供的主要功能

WorkbenchServiceProvider

路由与 Controller

迁移与 Seeder

启动服务与 CLI 确认

使用 WithWorkbench trait 进行测试

与测试的联动

故障排查

相关页面