> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Paketentwicklung mit Testbench Workbench

> Wie Sie mit Orchestra Testbench Workbench eine praxisnahe Entwicklungs- und Prüfumgebung mit Routen, Migrationen und Service-Startup bauen.

## Was ist Testbench Workbench?

[Orchestra Testbench](https://github.com/orchestral/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.

```mermaid theme={null}
flowchart TD
    A["Paket-Quellcode<br>`src/`"] --> B["Workbench<br>`workbench/`"]
    B --> C["WorkbenchServiceProvider<br>Demo-Services registrieren"]
    B --> D["Routen, Controller<br>UI-Prüfung"]
    B --> E["Migrationen, Seeder<br>Datenprüfung"]
    B --> F["`composer serve`<br>lokaler Start"]
    C --> G["testbench.yaml<br>Provider-/Build-Konfiguration"]
```

## Einrichtung

<Steps>
  <Step title="Testbench installieren">
    ```bash theme={null}
    composer require --dev orchestra/testbench
    ```
  </Step>

  <Step title="Workbench anlegen">
    ```bash theme={null}
    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.

    <Tip>
      Zusätzliche Optionen:

      * `--force`: überschreibt bestehende Dateien
      * `--basic`: schlanke Variante ohne Routen und Package Discovery
      * `--devtool`: aktiviert DevTool-Unterstützung
    </Tip>
  </Step>

  <Step title="Bauen und starten">
    ```bash theme={null}
    composer clear
    composer prepare
    composer build
    vendor/bin/testbench serve
    ```
  </Step>
</Steps>

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

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

```json theme={null}
{
    "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.

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

```yaml theme={null}
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.

```yaml theme={null}
env:
  - APP_ENV=testing
  - APP_KEY=base64:your-app-key
  - DB_CONNECTION=sqlite
  - DB_DATABASE=:memory:
```

## Struktur des Ordners workbench

<Tree>
  <Tree.Folder name="workbench" defaultOpen>
    <Tree.Folder name="app" defaultOpen>
      <Tree.Folder name="Http">
        <Tree.Folder name="Controllers" />
      </Tree.Folder>

      <Tree.Folder name="Models" />

      <Tree.Folder name="Providers">
        <Tree.File name="WorkbenchServiceProvider.php" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="bootstrap" />

    <Tree.Folder name="config" />

    <Tree.Folder name="database" defaultOpen>
      <Tree.Folder name="factories" />

      <Tree.Folder name="migrations" />

      <Tree.Folder name="seeders">
        <Tree.File name="DatabaseSeeder.php" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="public" />

    <Tree.Folder name="resources">
      <Tree.Folder name="views" />
    </Tree.Folder>

    <Tree.Folder name="routes">
      <Tree.File name="web.php" />

      <Tree.File name="api.php" />

      <Tree.File name="console.php" />
    </Tree.Folder>

    <Tree.Folder name="storage" />
  </Tree.Folder>
</Tree>

## Wichtige Funktionen der Workbench

### WorkbenchServiceProvider

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

```php theme={null}
<?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.

```php theme={null}
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.

```php theme={null}
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 theme={null}
<?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.

```bash theme={null}
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 theme={null}
<?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

```bash theme={null}
# 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
```

<AccordionGroup>
  <Accordion title="Workbench baut nicht">
    Prüfen Sie Syntax und Provider-Einträge in `testbench.yaml`. Häufig sind YAML-Einrückungen die Ursache.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Datenbankfehler">
    Prüfen Sie die Migrationspfade. Bei SQLite muss der Build-Schritt `create-sqlite-db` enthalten sein.
  </Accordion>
</AccordionGroup>

## Verwandte Seiten

<Columns cols={2}>
  <Card title="Laravel-Pakete mit Orchestra Testbench testen" icon="flask-conical" href="/de/advanced/package-testing">
    Zunächst die Testgrundlage für Pakete aufbauen.
  </Card>

  <Card title="Versionskompatibilität von Paketen verwalten" icon="git-branch" href="/de/advanced/package-versioning">
    Kompatibilitätsmatrix von Laravel/Testbench und Betrieb der CI-Matrix.
  </Card>
</Columns>

<Info>
  Quellen: [invokable/laravel-bluesky docs/workbench.md](https://github.com/invokable/laravel-bluesky/blob/main/docs/workbench.md), [Orchestra Testbench](https://github.com/orchestral/testbench)
</Info>


## Related topics

- [Laravel-Pakete mit Orchestra Testbench testen](/de/advanced/package-testing.md)
- [Laravel-Paketentwicklung](/de/advanced/package-development.md)
- [GeneratorCommand — Eigene make:-Befehle implementieren](/de/advanced/generator-command.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/de/packages/laravel-boost-phpstorm-copilot.md)
- [Statische Analyse für Pakete (PHPStan / Larastan)](/de/advanced/package-static-analysis.md)