Développer un package avec Testbench Workbench

Découvrez comment utiliser Orchestra Testbench Workbench pour créer un environnement de vérification proche d’une vraie application, avec routes, migrations et démarrage de services.

​

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
providers	Liste des service providers chargés dans l’environnement Workbench
migrations	Répertoires de migrations à exécuter
workbench.start	URL par défaut au démarrage de composer serve
workbench.discovers	Contrôle la découverte automatique des packages Laravel
workbench.build	Liste 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

Http

Models

Providers

bootstrap

config

database

factories

migrations

seeders

public

resources

routes

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

Workbench ne se construit pas

Vérifiez la syntaxe de testbench.yaml et la configuration des providers. Une erreur d’indentation YAML est souvent en cause.

Les routes ne sont pas chargées

Vérifiez le chemin du fichier de routes et l’enregistrement dans WorkbenchServiceProvider. Assurez-vous que discovers.web est bien true dans testbench.yaml.

Erreur de base de données

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