Vai al contenuto principale

​
Cos’è Testbench Workbench

Orchestra Testbench è pensato per i test, ma combinandolo con Workbench puoi mantenere una piccola app Laravel dentro il repository del pacchetto ed eseguirla in locale. Serve a completare i test creati in package-testing quando vuoi verificare l’UI, la raggiungibilità delle rotte o eseguire verifiche con dati seeded.

​
Setup

1

Installare Testbench

composer require --dev orchestra/testbench
2

Creare il Workbench

vendor/bin/testbench workbench:install
Questo comando fa tutto insieme:
  • crea la struttura di directory workbench/
  • aggiunge il namespace Workbench a autoload-dev di composer.json
  • aggiunge gli script di build a scripts di composer.json
Opzioni aggiuntive:
  • --force : sovrascrive i file esistenti
  • --basic : configurazione semplice senza rotte / package discovery
  • --devtool : abilita il supporto DevTool
3

Build e avvio

composer clear
composer prepare
composer build
vendor/bin/testbench serve
workbench:install prepara workbench/, autoload-dev e gli script correlati in un colpo solo.
Dopo l’installazione, composer.json conterrà i seguenti script. 
{
    "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"
        ]
    }
}

​
Definire l’ambiente di sviluppo con testbench.yaml

Il comportamento di Workbench si gestisce con testbench.yaml nella root.
testbench.yaml può contenere impostazioni specifiche per ogni ambiente: è consigliato aggiungerlo a .gitignore ed escluderlo dal commit. Al suo posto includi nel repository un testbench.yaml.example come template.
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
Opzioni principali:
ChiaveDescrizione
providersLista dei service provider da caricare in Workbench
migrationsDirectory delle migrazioni da eseguire
workbench.startURL di default all’avvio di composer serve
workbench.discoversControlla i target dell’auto-discovery di Laravel
workbench.buildLista di comandi eseguiti in fase di build
Anche le variabili d’ambiente si gestiscono in testbench.yaml. 
env:
  - APP_ENV=testing
  - APP_KEY=base64:your-app-key
  - DB_CONNECTION=sqlite
  - DB_DATABASE=:memory:

​
Struttura della directory workbench

workbench
app
Models
bootstrap
config
database
factories
migrations
public
storage

​
Principali funzionalità offerte da Workbench

​
WorkbenchServiceProvider

Crea un service provider dedicato a Workbench per la registrazione dei componenti demo. 
<?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');
    }
}

​
Rotte e controller

In workbench/routes/web.php o workbench/routes/api.php puoi mettere rotte di verifica. 
use Illuminate\Support\Facades\Route;
use Vendor\Package\Facades\Package;

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

​
Migrazioni e Seeder

Usando workbench/database/migrations e workbench/database/seeders puoi verificare con una struttura dati simile alla produzione. 
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('widgets', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});
Il Seeder genera dati di test. 
<?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();
    }
}

​
Avvio del server e verifica CLI

Puoi eseguire comandi Artisan tramite vendor/bin/testbench. 
vendor/bin/testbench list
vendor/bin/testbench route:list
vendor/bin/testbench migrate:fresh --seed

​
Test con il trait WithWorkbench

Il trait WithWorkbench applica la configurazione di testbench.yaml anche ai test automatici. 
<?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');
    }
}

​
Integrazione con i test

Ti consigliamo questa divisione: Workbench è “l’app per verifiche manuali e demo”, il codice di test di Testbench è “la verifica automatica”.
  • Automazione: previeni regressioni con tests/
  • Verifica manuale: controlla UI, percorsi e comportamento integrato con workbench/

​
Troubleshooting

# clear + rebuild completo
composer clear && composer prepare && composer build

# verifica il package discovery
vendor/bin/testbench package:discover --ansi

# verifica la configurazione
vendor/bin/testbench about

# verifica la lista delle rotte
vendor/bin/testbench route:list
Controlla la sintassi di testbench.yaml e la configurazione dei provider. Spesso il problema è un errore di indentazione YAML.
Controlla il path del file delle rotte e la registrazione in WorkbenchServiceProvider. Verifica che discovers.web in testbench.yaml sia true.
Controlla che il path delle migrazioni sia corretto. Se usi SQLite verifica che sia presente lo step di build create-sqlite-db.

​
Pagine correlate

Testare pacchetti Laravel con Orchestra Testbench

Consulta prima come costruire l’infrastruttura di test del pacchetto.

Gestire la compatibilità tra versioni dei pacchetti

Rivedi la tabella di compatibilità Laravel/Testbench e l’operatività della matrix CI.
Fonte: invokable/laravel-bluesky docs/workbench.md, Orchestra Testbench
Ultima modifica il 13 luglio 2026

Argomenti correlati

Testare pacchetti Laravel con Orchestra TestbenchLaravel Boost Custom Agent for GitHub Copilot CLILaravel Package Skeleton — template starter per pacchetti ufficialiGestire la compatibilità tra versioni dei pacchettiSviluppo di pacchetti Laravel