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

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

```mermaid theme={null}
flowchart TD
    A["Cœur du package<br>`src/`"] --> B["Workbench<br>`workbench/`"]
    B --> C["WorkbenchServiceProvider<br>services de démo"]
    B --> D["Routes et contrôleurs<br>vérification écran"]
    B --> E["Migrations et Seeders<br>vérification des données"]
    B --> F["`composer serve`<br>démarrage local"]
    C --> G["testbench.yaml<br>providers/build"]
```

## Installation

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

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

    <Tip>
      Options supplémentaires :

      * `--force` : écrase les fichiers existants.
      * `--basic` : configuration simple, sans routes ni discovery du package.
      * `--devtool` : active le support DevTool.
    </Tip>
  </Step>

  <Step title="Construire et démarrer">
    ```bash theme={null}
    composer clear
    composer prepare
    composer build
    vendor/bin/testbench serve
    ```
  </Step>
</Steps>

<Info>
  `workbench:install` met en place d'un seul coup le répertoire `workbench/`, l'`autoload-dev` et les scripts associés.
</Info>

Après installation, les scripts suivants sont ajoutés au `composer.json`.

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

## Définir l'environnement de développement avec testbench.yaml

Le comportement de Workbench se pilote via `testbench.yaml` à la racine.

<Warning>
  `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.
</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
```

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`.

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

## Structure du répertoire 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>

## Principales fonctionnalités offertes par Workbench

### WorkbenchServiceProvider

Créez un service provider dédié à Workbench pour effectuer les enregistrements de démonstration.

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

### Routes et contrôleurs

Vous pouvez placer des routes de vérification dans `workbench/routes/web.php` ou `workbench/routes/api.php`.

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

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

Générez des données de test via un Seeder.

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

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

Vous pouvez exécuter des commandes Artisan via `vendor/bin/testbench`.

```bash theme={null}
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 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');
    }
}
```

## 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

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

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

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

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

## Pages associées

<Columns cols={2}>
  <Card title="Tester des packages Laravel avec Orchestra Testbench" icon="flask-conical" href="/fr/advanced/package-testing">
    Découvrez d'abord comment poser les fondations de tests de package.
  </Card>

  <Card title="Gestion de la compatibilité de versions de package" icon="git-branch" href="/fr/advanced/package-versioning">
    Passez en revue la table de correspondance Laravel/Testbench et la stratégie de matrice CI.
  </Card>
</Columns>

<Info>
  Source : [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 Boost Custom Agent for GitHub Copilot CLI](/fr/packages/laravel-boost-copilot-cli.md)
- [Tester des packages Laravel avec Orchestra Testbench](/fr/advanced/package-testing.md)
- [Gestion de la compatibilité de versions de package](/fr/advanced/package-versioning.md)
- [Plugin Directories](/fr/packages/laravel-copilot-sdk/plugin-directories.md)
- [Laravel Package Skeleton — le template de démarrage pour packages officiels](/fr/blog/package-skeleton-introduction.md)