Desarrollar paquetes con Testbench Workbench

Qué es Testbench Workbench

Orchestra Testbench está pensado para tests, pero combinándolo con Workbench puedes crear una pequeña aplicación Laravel dentro del propio repositorio del paquete y ejecutarla en local. Se usa para complementar los tests que creaste en package-testing cuando quieres validar la UI, la respuesta de las rutas o hacer verificaciones con seeders.

Configuración

Instala Testbench

composer require --dev orchestra/testbench

Crea el Workbench

vendor/bin/testbench workbench:install

Este comando realiza a la vez lo siguiente:

Crea la estructura del directorio workbench/.
Añade el namespace de Workbench a autoload-dev en composer.json.
Añade comandos de build a scripts en composer.json.

Opciones adicionales:

--force: sobrescribe archivos existentes.
--basic: composición simple sin la configuración de rutas ni package discovery.
--devtool: habilita el soporte de DevTool.

Compila y arranca

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

workbench:install prepara de una vez el directorio workbench/, autoload-dev y los scripts relacionados.

Tras la instalación, se añaden los siguientes scripts en 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"
        ]
    }
}

Definir el entorno de desarrollo con testbench.yaml

El comportamiento del Workbench se gestiona en el testbench.yaml de la raíz.

testbench.yaml puede contener configuración específica del entorno, así que se recomienda añadirlo a .gitignore y no incluirlo en los commits. En su lugar, deja en el repositorio un testbench.yaml.example a modo de plantilla.

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

Opciones principales:

Clave	Descripción
`providers`	Lista de service providers que se cargan en el entorno Workbench.
`migrations`	Directorios de migraciones que se ejecutarán.
`workbench.start`	URL por defecto al arrancar `composer serve`.
`workbench.discovers`	Controla el package discovery automático de Laravel.
`workbench.build`	Lista de comandos que se ejecutan durante el build.

También puedes gestionar variables de entorno en testbench.yaml.

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

Estructura del directorio workbench

workbench

app

Http

Models

Providers

bootstrap

config

database

factories

migrations

seeders

public

resources

routes

storage

Funcionalidades principales de Workbench

WorkbenchServiceProvider

Crea un service provider dedicado a Workbench para registrar componentes de demo.

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

Rutas y controladores

En workbench/routes/web.php o workbench/routes/api.php puedes colocar rutas de verificación.

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

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

Migraciones y seeders

Usa workbench/database/migrations y workbench/database/seeders para validar con una estructura de datos cercana a la real.

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

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

Genera datos de prueba con 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();
    }
}

Arranque del servicio y verificación por CLI

Puedes ejecutar comandos Artisan a través de vendor/bin/testbench.

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

Tests con el trait WithWorkbench

Con el trait WithWorkbench, la configuración de testbench.yaml se aplica también a los tests automatizados.

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

Coordinación con los tests

Reparte responsabilidades entre Workbench como «app de verificación manual y demo» y los tests de Testbench como «verificación automática».

Automatización: previene regresiones en tests/.
Verificación manual: valida pantalla, navegación y comportamiento integrado en workbench/.

Solución de problemas

# Limpiar y reconstruir por completo
composer clear && composer prepare && composer build

# Comprobar el package discovery
vendor/bin/testbench package:discover --ansi

# Comprobar la configuración
vendor/bin/testbench about

# Ver la lista de rutas
vendor/bin/testbench route:list

El Workbench no compila

Revisa la sintaxis y la configuración de providers en testbench.yaml. Un error de indentación de YAML puede ser la causa.

No se cargan las rutas

Comprueba la ruta del archivo y su registro en el WorkbenchServiceProvider. Verifica también que discovers.web esté en true en testbench.yaml.

Aparecen errores de base de datos

Comprueba que las rutas de las migraciones son correctas. Si usas SQLite, asegúrate de incluir el paso create-sqlite-db en el build.

Páginas relacionadas

Probar paquetes Laravel con Orchestra Testbench

Aprende primero cómo montar la base de pruebas de tu paquete.

Gestión de la compatibilidad de versiones de paquetes

Consulta la tabla de compatibilidad Laravel/Testbench y la operativa de la matriz de CI.

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

Desarrollo con IA

Patrones de diseño

Desarrollo de paquetes

Estructura de la aplicación

Novedades de Laravel 13

Profundizando en Eloquent

Extensión de validación

Extensión de autenticación

Seguridad

Pruebas

テスト

Desarrollar paquetes con Testbench Workbench

Qué es Testbench Workbench

Configuración

Definir el entorno de desarrollo con testbench.yaml

Estructura del directorio workbench

Funcionalidades principales de Workbench

WorkbenchServiceProvider

Rutas y controladores

Migraciones y seeders

Arranque del servicio y verificación por CLI

Tests con el trait WithWorkbench

Coordinación con los tests

Solución de problemas

Páginas relacionadas

Probar paquetes Laravel con Orchestra Testbench

Gestión de la compatibilidad de versiones de paquetes

​Qué es Testbench Workbench

​Configuración

​Definir el entorno de desarrollo con testbench.yaml

​Estructura del directorio workbench

​Funcionalidades principales de Workbench

​WorkbenchServiceProvider

​Rutas y controladores

​Migraciones y seeders

​Arranque del servicio y verificación por CLI

​Tests con el trait WithWorkbench

​Coordinación con los tests

​Solución de problemas

​Páginas relacionadas

Probar paquetes Laravel con Orchestra Testbench

Gestión de la compatibilidad de versiones de paquetes

Qué es Testbench Workbench

Configuración

Definir el entorno de desarrollo con testbench.yaml

Estructura del directorio workbench

Funcionalidades principales de Workbench

WorkbenchServiceProvider

Rutas y controladores

Migraciones y seeders

Arranque del servicio y verificación por CLI

Tests con el trait WithWorkbench

Coordinación con los tests

Solución de problemas

Páginas relacionadas