Probar paquetes Laravel con Orchestra Testbench

Explica cómo construir el entorno de pruebas de un paquete Laravel con Orchestra Testbench y verificar service providers, facades, configuración y base de datos.

​

Qué es Orchestra Testbench

Orchestra Testbench es un helper de pruebas de Laravel orientado al desarrollo de paquetes. Al extender Orchestra\Testbench\TestCase, puedes testear el paquete de forma aislada con la misma sensación que si estuvieras dentro de una aplicación Laravel.

La documentación oficial de Laravel también recomienda Testbench para las pruebas de paquete en la sección de desarrollo de paquetes.

​

Configuración

1. Instala Testbench

   composer require --dev orchestra/testbench
   
2. Crea el TestCase base

   <?php
   
   namespace Vendor\Package\Tests;
   
   use Orchestra\Testbench\TestCase as BaseTestCase;
   use Vendor\Package\PackageServiceProvider;
   
   abstract class TestCase extends BaseTestCase
   {
       /**
        * $app es la instancia de la aplicación Laravel que arranca Testbench.
        */
       protected function getPackageProviders($app): array
       {
           return [
               PackageServiceProvider::class,
           ];
       }
   }
   
3. Añade configuración o aliases si es necesario

   En getPackageAliases() puedes registrar los alias de facade que se usarán en los tests, igual que en aliases de config/app.php.

   protected function getPackageAliases($app): array
   {
       return [
           'Package' => \Vendor\Package\Facades\Package::class,
       ];
   }
   
   protected function defineEnvironment($app): void
   {
       // Sobrescribe aquí la configuración para las pruebas
       $app['config']->set('package.enabled', true);
   }
   

​

Cómo escribir los tests básicos

Empieza comprobando si el service provider está cargado, si el facade se comporta como esperas y si la configuración se aplica correctamente.

<?php

namespace Vendor\Package\Tests\Feature;

use Vendor\Package\Facades\Package;
use Vendor\Package\PackageServiceProvider;
use Vendor\Package\Tests\TestCase;

class PackageBootstrapTest extends TestCase
{
    public function test_service_provider_is_registered(): void
    {
        $this->assertTrue($this->app->providerIsLoaded(PackageServiceProvider::class));
    }

    public function test_facade_returns_expected_value(): void
    {
        // Verifica la funcionalidad a través del facade
        $this->assertSame('ok', Package::status());
    }

    public function test_package_config_is_available(): void
    {
        // Comprueba el valor configurado en defineEnvironment()
        $this->assertTrue(config('package.enabled'));
    }
}

​

Pruebas de sistema de archivos y base de datos

Para tests que usan BD, configura SQLite en memoria en defineEnvironment() y carga las migraciones del paquete objetivo.

<?php

namespace Vendor\Package\Tests;

use Orchestra\Testbench\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function defineEnvironment($app): void
    {
        // Usa una BD SQLite en memoria
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.testing', [
            'driver' => 'sqlite',
            'database' => ':memory:',
            'prefix' => '',
        ]);
    }

    protected function setUp(): void
    {
        parent::setUp();

        // Carga las migraciones del paquete
        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
    }
}

public function test_it_persists_data(): void
{
    \DB::table('widgets')->insert(['name' => 'test']);

    $this->assertDatabaseHas('widgets', ['name' => 'test']);
}

​

Pruebas contra varias versiones de Laravel

La versión mayor de Testbench se corresponde con la de Laravel. Consulta el detalle en la tabla de compatibilidad oficial.

Laravel	Testbench
12.x	10.x
13.x	11.x

Para verificar varias versiones de forma continua, combínalo con la matriz de GitHub Actions. La forma de diseñarla se explica en Gestión de la compatibilidad de versiones de paquetes.

strategy:
  fail-fast: false
  matrix:
    php: [8.3, 8.4]
    laravel: ["^12.0", "^13.0"]
    include:
      - laravel: "^13.0"
        testbench: "^11.0"
      - laravel: "^12.0"
        testbench: "^10.0"

​

Resumen

Con Testbench puedes verificar el comportamiento de un paquete de una forma muy cercana a la real, sin tener que preparar una aplicación Laravel a mano. Al cubrir con tests el registro del service provider, la configuración, los facades y la BD reduces drásticamente los problemas tras el release.

​

Páginas relacionadas

Desarrollo de paquetes Laravel

Fundamentos de implementación de paquetes centrada en los service providers.

Gestión de la compatibilidad de versiones de paquetes

Estrategia de versiones de Laravel y Testbench, y cómo operar la matriz de CI.