Passer au contenu principal

​
Qu’est-ce que Testbench Workbench

Orchestra Testbench est conçu pour les tests ; en combinant Workbench, vous pouvez créer une petite application Laravel à l’intérieur du dépôt de votre package et l’exécuter localement. C’est utile en complément des tests écrits avec package-testing, pour vérifier l’interface, tester le routing et faire tourner l’application avec des seeders.

​
Installation

1

Installer Testbench

composer require --dev orchestra/testbench
2

Créer Workbench

vendor/bin/testbench workbench:install
Cette commande fait le tout à la fois :
  • Crée la structure du répertoire workbench/.
  • Ajoute le namespace Workbench à autoload-dev du composer.json.
  • Ajoute les commandes de build aux scripts du composer.json.
Options supplémentaires :
  • --force : écrase les fichiers existants.
  • --basic : configuration simple, sans routes ni discovery du package.
  • --devtool : active le support DevTool.
3

Construire et démarrer

composer clear
composer prepare
composer build
vendor/bin/testbench serve
workbench:install met en place d’un seul coup le répertoire workbench/, l’autoload-dev et les scripts associés.
Après installation, les scripts suivants sont ajoutés au composer.json. 
{
    "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"
        ]
    }
}

​
Définir l’environnement de développement avec testbench.yaml

Le comportement de Workbench se pilote via testbench.yaml à la racine.
testbench.yaml peut contenir des paramètres spécifiques à chaque environnement : il est recommandé de l’ajouter à .gitignore et de ne pas le commiter. À la place, incluez testbench.yaml.example comme modèle dans le dépôt.
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
Principales options de configuration :
CléDescription
providersListe des service providers chargés dans l’environnement Workbench
migrationsRépertoires de migrations à exécuter
workbench.startURL par défaut au démarrage de composer serve
workbench.discoversContrôle la découverte automatique des packages Laravel
workbench.buildListe des commandes à exécuter lors du build
Les variables d’environnement se gèrent également dans testbench.yaml. 
env:
  - APP_ENV=testing
  - APP_KEY=base64:your-app-key
  - DB_CONNECTION=sqlite
  - DB_DATABASE=:memory:

​
Structure du répertoire workbench

workbench
app
Models
bootstrap
config
database
factories
migrations
public
storage

​
Principales fonctionnalités offertes par Workbench

​
WorkbenchServiceProvider

Créez un service provider dédié à Workbench pour effectuer les enregistrements de démonstration. 
<?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 et contrôleurs

Vous pouvez placer des routes de vérification dans workbench/routes/web.php ou workbench/routes/api.php. 
use Illuminate\Support\Facades\Route;
use Vendor\Package\Facades\Package;

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

​
Migrations et Seeders

workbench/database/migrations et workbench/database/seeders permettent de valider avec une structure de données proche de la production. 
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('widgets', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});
Générez des données de test via un 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();
    }
}

​
Démarrage du service et vérification en CLI

Vous pouvez exécuter des commandes Artisan via vendor/bin/testbench. 
vendor/bin/testbench list
vendor/bin/testbench route:list
vendor/bin/testbench migrate:fresh --seed

​
Tester avec le trait WithWorkbench

Grâce au trait WithWorkbench, la configuration de testbench.yaml s’applique aussi automatiquement aux tests. 
<?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');
    }
}

​
Articulation avec les tests

Il est plus facile de séparer les rôles : Workbench sert d’« application de démonstration et de vérification manuelle », tandis que les tests Testbench prennent en charge la « vérification automatique ».
  • Automatisé : tests/ pour prévenir les régressions.
  • Manuel : workbench/ pour valider écrans, parcours et comportement d’intégration.

​
Dépannage

# Reconstruction complète depuis zéro
composer clear && composer prepare && composer build

# Vérifier la découverte automatique de package
vendor/bin/testbench package:discover --ansi

# Vérifier la configuration
vendor/bin/testbench about

# Lister les routes
vendor/bin/testbench route:list
Vérifiez la syntaxe de testbench.yaml et la configuration des providers. Une erreur d’indentation YAML est souvent en cause.
Vérifiez le chemin du fichier de routes et l’enregistrement dans WorkbenchServiceProvider. Assurez-vous que discovers.web est bien true dans testbench.yaml.
Vérifiez que le chemin des migrations est correct. Avec SQLite, vérifiez que l’étape de build create-sqlite-db est bien présente.

​
Pages associées

Tester des packages Laravel avec Orchestra Testbench

Découvrez d’abord comment poser les fondations de tests de package.

Gestion de la compatibilité de versions de package

Passez en revue la table de correspondance Laravel/Testbench et la stratégie de matrice CI.
Source : invokable/laravel-bluesky docs/workbench.md, Orchestra Testbench
Dernière modification le 13 juillet 2026

Sujets connexes

Laravel Boost Custom Agent for GitHub Copilot CLITester des packages Laravel avec Orchestra TestbenchGestion de la compatibilité de versions de packagePlugin DirectoriesLaravel Package Skeleton — le template de démarrage pour packages officiels