Saltar al contenido principal

​
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

1

Instala Testbench

composer require --dev orchestra/testbench
2

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

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:
ClaveDescripción
providersLista de service providers que se cargan en el entorno Workbench.
migrationsDirectorios de migraciones que se ejecutarán.
workbench.startURL por defecto al arrancar composer serve.
workbench.discoversControla el package discovery automático de Laravel.
workbench.buildLista 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
Models
bootstrap
config
database
factories
migrations
public
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
Revisa la sintaxis y la configuración de providers en testbench.yaml. Un error de indentación de YAML puede ser la causa.
Comprueba la ruta del archivo y su registro en el WorkbenchServiceProvider. Verifica también que discovers.web esté en true en testbench.yaml.
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
Última modificación el 13 de julio de 2026

Temas relacionados

Laravel Boost Custom Agent for GitHub Copilot CLIProbar paquetes Laravel con Orchestra TestbenchLaravel Package Skeleton — Plantilla oficial para paquetesGestión de la compatibilidad de versiones de paquetesPHP Reflection API