Skip to main content

Introducción

Laravel ofrece una API muy completa para simular peticiones HTTP y verificar sus respuestas. Puedes reproducir las peticiones dentro de los tests sin necesidad de levantar un servidor HTTP real.
El método get() envía una petición GET a la aplicación y assertStatus() valida el código HTTP de la respuesta.
Durante las pruebas el middleware CSRF se desactiva automáticamente. No hace falta desactivarlo de forma explícita.

Cómo crear peticiones

Dentro de los tests puedes enviar peticiones con los métodos get, post, put, patch y delete. Estos métodos no realizan una petición real por la red: simulan la petición internamente en la aplicación. El valor devuelto es una instancia de Illuminate\Testing\TestResponse, que expone muchos métodos de aserción.
Se recomienda enviar una única petición por cada método de test. Ejecutar varias peticiones dentro del mismo test puede provocar comportamientos inesperados.

Personalizar cabeceras

Con withHeaders() puedes personalizar las cabeceras de la petición.

Cookies

Los métodos withCookie() o withCookies() permiten definir cookies antes de la petición.

Sesión y autenticación

Con withSession() puedes preparar los datos de sesión antes de la petición.
actingAs() envía la petición como un usuario autenticado. Se combina con las factorías de modelos.
Si pasas el nombre de un guard como segundo argumento de actingAs(), se autenticará con ese guard. Además, ese guard pasa a ser el predeterminado durante la prueba.
Para enviar una petición sin autenticar utiliza actingAsGuest().

Depurar la respuesta

Cuando quieras inspeccionar el contenido de la respuesta durante un test, usa dump, dumpHeaders o dumpSession.
Para detener la ejecución al mismo tiempo, utiliza dd, ddHeaders, ddBody, ddJson y ddSession.

Probar excepciones

Para comprobar que se lanza una excepción concreta, utiliza el facade Exceptions.
Para comprobar que no se ha lanzado una excepción utiliza assertNotReported o assertNothingReported.
Para enviar la petición desactivando el manejo de excepciones, utiliza withoutExceptionHandling().
Para probar si el código dentro de una closure lanza una excepción, utiliza assertThrows().
Para comprobar que no se lanza excepción, utiliza assertDoesntThrow().

Pruebas de API JSON

Laravel ofrece muchos helpers para probar APIs JSON. Utiliza los métodos json, getJson, postJson, putJson, patchJson, deleteJson y optionsJson.
Los datos de la respuesta JSON son accesibles como si fueran un array.
assertJson() convierte la respuesta a array y comprueba que el array indicado esté contenido en la respuesta JSON. Aunque la respuesta contenga otras propiedades, la prueba pasa si aparece el fragmento indicado.

Aserción de coincidencia exacta

Con assertExactJson() verificas que el JSON devuelto coincide exactamente con el array indicado.

Aserción por path JSON

Con assertJsonPath() verificas el valor en un path concreto.
También puedes pasar una closure para una validación más flexible.

Pruebas JSON fluidas

Pasando una closure a assertJson() puedes escribir aserciones fluidas mediante una instancia de AssertableJson.
El método etc() permite que existan propiedades no aseveradas. Si no se usa etc(), la aserción falla si aparecen propiedades no verificadas. Así se evita filtrar accidentalmente información sensible en la respuesta.
Para comprobar la presencia o ausencia de propiedades utiliza has() y missing().
Para varias propiedades a la vez, hasAll() y missingAll().

Aserciones sobre colecciones JSON

Cuando la ruta devuelve una respuesta con varios elementos, has() permite comprobar el número de elementos y el contenido de la colección.
Para aplicar la misma aserción a todos los elementos, usa each().

Aserción de tipos JSON

Con whereType() y whereAllType() puedes validar el tipo de las propiedades.
Se pueden combinar varios tipos con |. La aserción pasa si el valor coincide con alguno.
Los tipos disponibles son string, integer, double, boolean, array y null.

Tests de autenticación

Con actingAs() puedes enviar peticiones como usuario autenticado.
Para autenticar con un guard concreto, pasa su nombre como segundo argumento.

Ejemplo: prueba del flujo de registro de usuarios

Ejemplo de test del endpoint de registro de usuarios.

Pruebas de sesión

Con withSession() puedes preparar la sesión antes de la petición. Con assertSessionHas() compruebas la existencia de valores en la sesión.

Aserciones sobre la sesión

Pruebas de subida de archivos

El método fake() de la clase Illuminate\Http\UploadedFile genera archivos e imágenes ficticios. Combinado con Storage::fake() puedes probar la subida de archivos con facilidad.
Para comprobar que un archivo no existe utiliza assertMissing().

Personalizar el archivo ficticio

Puedes indicar el tamaño de la imagen y del archivo, útil para probar reglas de validación.

Pruebas de vistas

Puedes probar vistas renderizándolas directamente sin simular la petición HTTP. view() acepta el nombre de la vista y, opcionalmente, un array de datos, y devuelve una instancia de Illuminate\Testing\TestView.
La clase TestView expone los siguientes métodos de aserción. Para obtener el HTML renderizado como cadena, castea la instancia TestView.
Para pasar errores de validación a la vista utiliza withViewErrors().

Probar componentes

Con blade() puedes renderizar una plantilla Blade en bruto.
Con component() renderizas un componente Blade y obtienes una instancia de Illuminate\Testing\TestComponent.

Lista de aserciones sobre la respuesta

Métodos principales que ofrece la clase Illuminate\Testing\TestResponse.

Estado HTTP

Redirecciones

Contenido

JSON

Cabeceras y cookies

Vistas

Validación

Recomendaciones para hacer TDD

Las pruebas HTTP encajan muy bien con TDD (desarrollo guiado por tests). Ten en cuenta los siguientes puntos para sacarles el máximo partido.
Los tests HTTP se sitúan en tests/Feature/. Empezar por el comportamiento externo (petición → respuesta) deja claro qué funcionalidad debes implementar.
En los tests que usen base de datos, aplica el trait RefreshDatabase. La base de datos se reinicia tras cada prueba y se evitan interferencias entre tests, lo que permite construir una suite estable independiente del orden de ejecución.
Con User::factory()->create() y demás factorías es muy fácil crear datos de prueba. Definir estados (state) para casos concretos mejora mucho la legibilidad.
Cada método de test debería verificar, en la medida de lo posible, una única cosa. Así resulta más fácil identificar la causa cuando falla. Aplicar el patrón AAA (Arrange, Act, Assert) hace los tests más legibles.
En las rutas que requieran autenticación, cubre siempre tanto el caso «autenticado» como el «no autenticado». Detectarás pronto problemas de seguridad.

Páginas relacionadas

Introducción a los tests

Repasa los fundamentos del testing en Laravel y el uso de php artisan test.
Última modificación el 13 de julio de 2026