Skip to main content

​
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:
KeyDescription
providersService providers to load in the Workbench environment
migrationsMigration directories to run
workbench.startDefault URL when running composer serve
workbench.discoversControl Laravel package auto-discovery
workbench.buildCommands 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
Models
bootstrap
config
database
factories
migrations
public
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
Check testbench.yaml syntax and provider configuration. YAML indentation errors are a common cause.
Verify the route file paths and the WorkbenchServiceProvider registration. Confirm that discovers.web is set to true in testbench.yaml.
Check that migration paths are correct. When using SQLite, make sure the create-sqlite-db build step is included.

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
Last modified on April 26, 2026