Sviluppare pacchetti con Testbench Workbench

Come creare, con Orchestra Testbench Workbench, un ambiente di verifica vicino a un’app reale, con rotte, migrazioni e avvio dei servizi.

​

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:

Chiave	Descrizione
providers	Lista dei service provider da caricare in Workbench
migrations	Directory delle migrazioni da eseguire
workbench.start	URL di default all’avvio di composer serve
workbench.discovers	Controlla i target dell’auto-discovery di Laravel
workbench.build	Lista 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

Http

Models

Providers

bootstrap

config

database

factories

migrations

seeders

public

resources

routes

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

Workbench non compila

Controlla la sintassi di testbench.yaml e la configurazione dei provider. Spesso il problema è un errore di indentazione YAML.

Le rotte non vengono caricate

Controlla il path del file delle rotte e la registrazione in WorkbenchServiceProvider. Verifica che discovers.web in testbench.yaml sia true.

Errori di database

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