Develop Laravel packages with Testbench Workbench

Use Orchestra Testbench Workbench to build a realistic package development environment with routes, migrations, and a local app runtime.

What is Testbench Workbench?

Orchestra Testbench is focused on automated tests. With Workbench, you also get a small Laravel app inside your package repository for interactive development.

Use it as a continuation of package-testing when you need UI checks, route verification, and seeded integration scenarios.

Setup

1. Install Testbench

   composer require --dev orchestra/testbench
   
2. Install Workbench scaffold

   vendor/bin/testbench workbench:install
   

   This command does the following in one step:

   • Creates the workbench/ directory structure
   • Adds Workbench namespaces to composer.json autoload-dev
   • Adds build scripts to composer.json scripts

   Additional options:

   • --force: overwrite existing files
   • --basic: minimal setup without routes and package discovery configuration
   • --devtool: enable DevTool support
3. Build and serve

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

workbench:install prepares the workbench/ tree, autoload-dev, and related scripts in one step.

After installation, composer.json includes the following:

{
    "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"
        ]
    }
}

Define your environment in testbench.yaml

Use testbench.yaml in the package root to control providers, migrations, and build steps.

testbench.yaml often contains environment-specific settings. Add it to .gitignore and keep a testbench.yaml.example template in the repository for other developers.

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

Key configuration options:

Key	Description
providers	Service providers to load in the Workbench environment
migrations	Migration directories to run
workbench.start	Default URL when running composer serve
workbench.discovers	Control Laravel package auto-discovery
workbench.build	Commands to run during the build step

You can also set environment variables in testbench.yaml:

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

Workbench directory structure

workbench

app

Http

Models

Providers

bootstrap

config

database

factories

migrations

seeders

public

resources

routes

storage

Core features Workbench gives you

WorkbenchServiceProvider

Create a service provider to register Workbench-specific services and wire up demo routes and views.

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

Routes and controllers

Place development routes in workbench/routes/web.php and workbench/routes/api.php so you can verify package behavior from a browser or HTTP client.

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

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

Migrations and seeders

Use workbench/database/migrations and workbench/database/seeders to test your package against realistic schema and data.

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

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

Populate test data with a 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();
    }
}

Local runtime and console workflows

Run Artisan commands through vendor/bin/testbench.

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

Testing with the WithWorkbench trait

Use the WithWorkbench trait to apply testbench.yaml configuration to your automated test suite.

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

Combine Workbench with automated tests

Use Workbench for interactive checks and keep your tests/ directory for repeatable automated assertions.

• Automation: regression safety in tests/
• Interactive verification: end-to-end behavior in workbench/

Troubleshooting

# Clear and do a full rebuild
composer clear && composer prepare && composer build

# Check package discovery
vendor/bin/testbench package:discover --ansi

# Inspect configuration
vendor/bin/testbench about

# List all routes
vendor/bin/testbench route:list

Workbench fails to build

Check testbench.yaml syntax and provider configuration. YAML indentation errors are a common cause.

Routes are not loading

Verify the route file paths and the WorkbenchServiceProvider registration. Confirm that discovers.web is set to true in testbench.yaml.

Database errors

Check that migration paths are correct. When using SQLite, make sure the create-sqlite-db build step is included.

Related pages

Testing Laravel packages with Orchestra Testbench

Start with the package testing foundation first.

Package version compatibility management

Learn version mapping and CI matrix strategy for Laravel and Testbench.

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