Paketentwicklung mit Testbench Workbench

Was ist Testbench Workbench?

Orchestra Testbench ist auf Tests ausgelegt. In Kombination mit Workbench können Sie jedoch eine kleine Laravel-Anwendung innerhalb Ihres Paket-Repositorys erstellen und lokal ausführen. Nutzen Sie Workbench als Ergänzung zu den in package-testing gebauten Tests, wenn Sie UI-Prüfungen, Routen-Sanity-Checks oder Datenprüfungen mit Seeder machen wollen.

Einrichtung

Testbench installieren

composer require --dev orchestra/testbench

Workbench anlegen

vendor/bin/testbench workbench:install

Der Befehl erledigt zusammen:

die Ordnerstruktur workbench/ anzulegen,
den Workbench-Namensraum in autoload-dev der composer.json einzutragen,
Build-Skripte in scripts der composer.json zu ergänzen.

Zusätzliche Optionen:

--force: überschreibt bestehende Dateien
--basic: schlanke Variante ohne Routen und Package Discovery
--devtool: aktiviert DevTool-Unterstützung

Bauen und starten

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

workbench:install richtet den Ordner workbench/, den Eintrag in autoload-dev und die zugehörigen Skripte gemeinsam ein.

Nach der Installation stehen in Ihrer composer.json folgende Skripte:

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

Umgebung mit testbench.yaml definieren

Das Verhalten der Workbench steuern Sie über die Datei testbench.yaml im Projekt-Root.

Da testbench.yaml umgebungsspezifische Einstellungen enthalten kann, ist es empfehlenswert, sie in .gitignore einzutragen. Stellen Sie stattdessen eine Vorlage testbench.yaml.example ins Repository.

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

Wichtige Konfigurationsoptionen:

Schlüssel	Beschreibung
`providers`	Liste der Service Provider, die in der Workbench-Umgebung geladen werden
`migrations`	Verzeichnisse, aus denen Migrationen ausgeführt werden
`workbench.start`	Standard-URL beim Start von `composer serve`
`workbench.discovers`	Steuert, was von Laravels Package Discovery erkannt wird
`workbench.build`	Beim Build auszuführende Kommandos

Auch Umgebungsvariablen lassen sich in testbench.yaml pflegen.

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

Struktur des Ordners workbench

workbench

app

Http

Models

Providers

bootstrap

config

database

factories

migrations

seeders

public

resources

routes

storage

Wichtige Funktionen der Workbench

WorkbenchServiceProvider

Legen Sie einen Workbench-eigenen Service Provider an, um Demo-Registrierungen vorzunehmen.

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

Routen und Controller

Legen Sie Testrouten in workbench/routes/web.php oder workbench/routes/api.php ab.

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

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

Migrationen und Seeder

Mit workbench/database/migrations und workbench/database/seeders prüfen Sie das Paket in einer datenrealistischen Umgebung.

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

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

Der Seeder erzeugt Testdaten.

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

Service-Start und Prüfung über CLI

Artisan-Befehle führen Sie über vendor/bin/testbench aus.

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

Tests mit dem Trait WithWorkbench

Mit dem Trait WithWorkbench werden die Einstellungen aus testbench.yaml auch in automatischen Tests aktiv.

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

Zusammenspiel mit Tests

Wenn Sie die Workbench als „manuelle Prüfung / Demo-App” und die Testbench-Tests als „automatische Verifikation” verstehen, ist der Betrieb klarer:

Automatisiert: tests/ schützt vor Regressionen.
Manuell: workbench/ prüft UI, User-Flow und integriertes Verhalten.

Fehlerbehebung

# Bereinigen und komplett neu bauen
composer clear && composer prepare && composer build

# Package Discovery prüfen
vendor/bin/testbench package:discover --ansi

# Konfiguration prüfen
vendor/bin/testbench about

# Routen prüfen
vendor/bin/testbench route:list

Workbench baut nicht

Prüfen Sie Syntax und Provider-Einträge in testbench.yaml. Häufig sind YAML-Einrückungen die Ursache.

Routen werden nicht geladen

Prüfen Sie den Pfad Ihrer Routendatei und die Registrierung im WorkbenchServiceProvider. Stellen Sie sicher, dass discovers.web in testbench.yaml auf true steht.

Datenbankfehler

Prüfen Sie die Migrationspfade. Bei SQLite muss der Build-Schritt create-sqlite-db enthalten sein.

Laravel-Pakete mit Orchestra Testbench testen

Zunächst die Testgrundlage für Pakete aufbauen.

Versionskompatibilität von Paketen verwalten

Kompatibilitätsmatrix von Laravel/Testbench und Betrieb der CI-Matrix.

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

KI-Entwicklung

Design Patterns