Enlighten es un nuevo componente para Laravel desarrollado por Duilio Palacios y Jeff Ochoa que te permite generar automáticamente la documentación de tus APIs usando para ello tu suite de pruebas automatizadas.

Así es, Enlighten toma tus clases de prueba y genera la documentación de tus APIs, por lo que no tendrás que preocuparte de añadir un sinfín de docblocks a cada método o crear wikis extensos, con este paquete tendrás tu documentación actualizada de forma rápida y sencilla.

Pre-requisitos

Enlighten requiere PHP 7.3 o superior, así como Laravel en su versión 7 o superior.

Por defecto, Enlighten requiere que tu proyecto use el sistema de control de versiones git.

Instalar Enlighten

Puedes instalar Enlighten usando Composer. Para ello, ve al directorio raíz de tu proyecto y ejecuta desde la terminal:

#
composer require styde/enlighten --dev

Este comando instalará la versión más reciente del paquete; para el momento de escribir esta serie es 0.4.

Si no estás utilizando la característica de auto-descubrimiento de paquetes de Laravel, puedes agregar en tu archivo config/app.php el siguiente proveedor de servicios:

<?php
return [
    //...
    'providers' => [
        // ...
        Styde\Enlighten\Providers\EnlightenServiceProvider::class,
    ]
];

Publicar assets

Luego debes publicar los assets (CSS, JavaScript) en la carpeta public de tu proyecto, ejecutando:

#
php artisan vendor:publish --tag=enlighten-build

Además, también puedes publicar su archivo de configuración y las vistas para una mayor personalización:

php artisan vendor:publish --tag=enlighten-config
php artisan vendor:publish --tag=enlighten-views

Este último paso es opcional.

Agregar trait EnlightenSetup

Finalmente, en tu archivo tests/TestCase.php, agrega el trait EnlightenSetup y llama a setUpEnlighten() dentro del método setUp, por ejemplo:

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Styde\Enlighten\Tests\EnlightenSetup;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication, EnlightenSetup;

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

        $this->setUpEnlighten();
    }
}

No olvides importar y usar el trait Styde\Enlighten\Tests\EnlightenSetup.

Configuración de la base de datos

Enlighten necesita su propia base de datos y conexión para registrar y mostrar la información de tu suite de pruebas. Puedes configurar esta base de datos de dos formas:

Usando la convención

Si tu proyecto cumple con las siguientes convenciones:

    • Una base de datos por defecto (no sqlite) para el entorno local.
    • Una base de datos (no sqlite) para el entorno de pruebas con el sufijo _test o _tests.

Solo necesitarás crear una nueva base de datos con el mismo nombre de tu base de datos local, más el sufijo _enlighten.

Por ejemplo, si tu base de datos local es my_db y la de tus pruebas es my_db_tests, deberás crear una base de datos llamada my_db_enlighten.

Recuerda que tu base de datos local está configurada en el archivo .env, mientras que el nombre de la base de datos de pruebas se configura en phpunit.xml.

Agregando una nueva conexión

Si no sigues la convención anterior, puedes crear una nueva base de datos con el nombre de tu preferencia y agregar una nueva conexión en el archivo config/database.php con el nombre enlighten, por ejemplo:

<?php

//...
'enlighten' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => 'my_enlighten_database',
    // ...
],

Ejecutar migraciones

Una vez que tengas creada y configurada la base de datos, puedes ejecutar tus migraciones por medio de Artisan:

#
php artisan migrate

Enlighten también te proporciona el comando enlighten:migrate para ejecutar las migraciones del paquete de forma aislada. Para habilitarlo, publica los archivos de migración de la base de datos:

#
php artisan vendor:publish --tag=enlighten-migrations

Y con esto podrás ejecutar los comandos:

php artisan enlighten:migrate

php artisan enlighten:migrate:fresh

Enlace «See in Enlighten»

Con la finalidad de ayudarte a depurar pruebas fallidas, Enlighten incluye una característica muy útil llamada «See in Enlighten».

Cuando alguna de tus pruebas falle, se agregará automáticamente al final de ella un enlace hacia Enlighten que te permitirá ver todos los detalles de la misma. Dentro de Enlighten podrás ver el estado de la solicitud, la respuesta, las excepciones, consultas a la base de datos e inclusive un preview de la URL bajo prueba.

Para activar esta característica, ve a tu archivo phpunit.xml y agrega printerClass="Styde\Enlighten\Tests\BasicResultPrinter" dentro de la etiqueta phpunit, de la siguiente manera:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
         printerClass="Styde\Enlighten\Tests\BasicResultPrinter"
>
<!--  ...  -->

¡No borres los otros atributos!

Recuerda configurar la variable de entorno APP_URL de tu proyecto.

Material relacionado

Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.

Lección siguiente Personaliza tu documentación con Laravel Enlighten