Tutorial SpringBoot: Testing controladores REST con json

Test de integración parcial de controlador REST

En las aplicaciones Spring Boot 3, es fundamental garantizar que los controladores REST funcionen correctamente. Para ello, se realizan tests de integración parcial que prueban el controlador en sí, aislándolo del resto de la aplicación. Una herramienta clave para este propósito es la anotación @WebMvcTest, que configura un entorno de prueba enfocado en la capa Web MVC.

Al utilizar @WebMvcTest, se cargan únicamente los componentes relacionados con el contexto web, como los controladores, los conversores y el mapeo de endpoints, pero se excluyen los beans de otros componentes, como los servicios. Esto permite probar el controlador de manera aislada y controlar sus dependencias mediante mocks.

Para simular las dependencias del controlador, se emplea el framework Mockito. Con mockitos, se pueden crear objetos simulados de los servicios que el controlador utiliza, permitiendo definir comportamientos esperados y verificar interacciones. De esta forma, se controlan las respuestas de los servicios y se centran las pruebas en la lógica del controlador.

Además, se utiliza la clase MockMvc para realizar solicitudes HTTP simuladas al controlador y verificar las respuestas. MockMvc permite enviar peticiones como GET, POST, PUT o DELETE, y comprobar aspectos como el código de estado HTTP, el contenido de la respuesta y los encabezados.

A continuación, se presenta un ejemplo práctico de cómo implementar un test de integración parcial de un controlador REST utilizando @WebMvcTest, MockMvc y mocks de servicios:

@WebMvcTest(controllers = UsuarioController.class)
class UsuarioControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UsuarioService usuarioService;

    @Test
    void testObtenerUsuarioPorId() throws Exception {
        Usuario usuario = new Usuario(1L, "Juan", "juan@example.com");
        when(usuarioService.obtenerUsuarioPorId(1L)).thenReturn(Optional.of(usuario));

        mockMvc.perform(get("/api/usuarios/1")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(content().contentType(MediaType.APPLICATION_JSON))
                .andExpect(jsonPath("$.nombre").value("Juan"))
                .andExpect(jsonPath("$.email").value("juan@example.com"));
    }
}

En este ejemplo:

• Se anota la clase de prueba con @WebMvcTest, indicando el controlador a probar: UsuarioController.
• Se inyecta MockMvc con @Autowired para realizar las peticiones simuladas.
• Se crea un mock del servicio UsuarioService con @MockBean.
• Se define el comportamiento esperado del servicio cuando se invoque obtenerUsuarioPorId(1L) utilizando when y thenReturn.
• Se realiza una petición GET a /api/usuarios/1 y se verifican las expectativas con andExpect.

Es importante destacar que, al utilizar @MockBean, se registra el mock en el contexto de Spring, reemplazando cualquier bean existente del mismo tipo. Esto facilita la inyección del mock en el controlador y mantiene el entorno de prueba controlado.

Otro aspecto relevante es la verificación del JSON de respuesta. Con jsonPath, se pueden examinar campos específicos del JSON y validar que contengan los valores esperados. Esto es esencial para asegurarse de que el controlador serializa correctamente los objetos y devuelve la información adecuada.

También es posible probar escenarios en los que el recurso no existe o se produce algún error. Por ejemplo:

@Test
void testObtenerUsuarioNoExistente() throws Exception {
    when(usuarioService.obtenerUsuarioPorId(99L)).thenReturn(Optional.empty());

    mockMvc.perform(get("/api/usuarios/99")
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isNotFound());
}

En este caso, se simula que el servicio no encuentra un usuario con el ID proporcionado y se espera que el controlador devuelva un status HTTP 404 Not Found.

Además de las peticiones GET, se pueden probar otros métodos HTTP. Por ejemplo, para una petición POST que crea un nuevo usuario:

@Test
void testCrearUsuario() throws Exception {
    Usuario nuevoUsuario = new Usuario(null, "Ana", "ana@example.com");
    Usuario usuarioCreado = new Usuario(2L, "Ana", "ana@example.com");

    when(usuarioService.crearUsuario(any(Usuario.class))).thenReturn(usuarioCreado);

    mockMvc.perform(post("/api/usuarios")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"nombre\":\"Ana\",\"email\":\"ana@example.com\"}")
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andExpect(header().string("Location", "/api/usuarios/2"))
            .andExpect(jsonPath("$.id").value(2))
            .andExpect(jsonPath("$.nombre").value("Ana"))
            .andExpect(jsonPath("$.email").value("ana@example.com"));
}

En este test:

• Se prepara el JSON de entrada con los datos del nuevo usuario.
• Se configura el mock del servicio para que devuelva el usuario creado con un ID asignado.
• Se verifica que el controlador devuelve un status HTTP 201 Created, que incluye el encabezado Location con la URL del nuevo recurso y que el JSON de respuesta contiene los datos correctos.

Es esencial utilizar la anotación @WebMvcTest junto con MockMvc y Mockito para lograr un test de integración parcial efectivo. De esta manera, se enfocan las pruebas en el controlador y se aseguran de que responde adecuadamente a las diversas solicitudes, manejando correctamente las entradas y salidas en formato JSON.

Algunas buenas prácticas a tener en cuenta:

• Verificar siempre el status HTTP de la respuesta para asegurarse de que el controlador responde con el código apropiado.
• Comprobar el contenido de la respuesta, ya sea el tipo de media (Content-Type) o los datos específicos del JSON.
• Utilizar Matchers como jsonPath, content, header, entre otros, para realizar verificaciones detalladas.
• Simular excepciones o casos de error en los servicios para probar cómo el controlador maneja situaciones adversas.

Finalmente, estos tests contribuyen a mantener un alto nivel de calidad en la aplicación, asegurando que los controladores REST cumplen con las especificaciones y ofrecen una API robusta y fiable.

Test de integración completa de controlador REST

En el desarrollo de aplicaciones Spring Boot 3, es esencial garantizar que los controladores REST funcionen correctamente en conjunto con el resto de los componentes de la aplicación. Para lograr esto, se realizan tests de integración completa que abarcan desde la capa web hasta los servicios y repositorios reales. A diferencia de los tests de integración parcial, en los que se aíslan componentes mediante mocks, aquí se utiliza el contexto completo de la aplicación.

La anotación @SpringBootTest es fundamental para este tipo de pruebas. Al aplicarla, se indica que se desea iniciar la aplicación entera en un ambiente de prueba, cargando todos los beans y configuraciones definidas. Esto permite que los tests interactúen con los componentes reales, proporcionando una verificación más exhaustiva del funcionamiento del sistema.

Para simular peticiones HTTP y verificar las respuestas, se utiliza MockMvc junto con la anotación @AutoConfigureMockMvc. Esta configuración permite inyectar el objeto MockMvc en el contexto de pruebas, facilitando la realización de solicitudes y la validación de respuestas sin necesidad de iniciar un servidor real.

A continuación, se presenta un ejemplo de cómo implementar un test de integración completa de un controlador REST utilizando @SpringBootTest, @AutoConfigureMockMvc y servicios reales:

@SpringBootTest
@AutoConfigureMockMvc
class UsuarioControllerIntegrationTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private UsuarioRepository usuarioRepository;

    @BeforeEach
    void setUp() {
        usuarioRepository.deleteAll();
        usuarioRepository.save(new Usuario(1L, "Carlos", "carlos@example.com"));
    }

    @Test
    void testObtenerUsuarioPorId() throws Exception {
        mockMvc.perform(get("/api/usuarios/1")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(content().contentType(MediaType.APPLICATION_JSON))
                .andExpect(jsonPath("$.nombre").value("Carlos"))
                .andExpect(jsonPath("$.email").value("carlos@example.com"));
    }
}

En este ejemplo:

• La clase de prueba está anotada con @SpringBootTest, indicándole a Spring que cargue todo el contexto de la aplicación.
• Se utiliza @AutoConfigureMockMvc para configurar MockMvc y permitir la inyección de este en la prueba.
• Se inyecta UsuarioRepository para interactuar con la base de datos en memoria durante los tests.
• En el método setUp(), anotado con @BeforeEach, se preparan los datos necesarios para la prueba, eliminando cualquier registro previo y agregando un usuario de ejemplo.
• En el test testObtenerUsuarioPorId(), se realiza una petición GET al endpoint /api/usuarios/1 y se verifican las respuestas usando aserciones de MockMvc.

Es importante destacar que, al utilizar servicios y repositorios reales, se está interactuando con una base de datos. Para evitar efectos secundarios y garantizar la consistencia de las pruebas, es recomendable utilizar una base de datos en memoria como H2. Además, se puede utilizar la anotación @Transactional para asegurar que los cambios realizados en cada test se reviertan al finalizar.

Por ejemplo, para garantizar la limpieza de los datos después de cada test:

@SpringBootTest
@AutoConfigureMockMvc
@Transactional
class UsuarioControllerIntegrationTest {
    // ...
}

Al aplicar @Transactional a nivel de clase, cada test se ejecutará dentro de una transacción que se revertirá automáticamente al finalizar, manteniendo la base de datos en un estado consistente.

Otro aspecto relevante es la posibilidad de probar operaciones más complejas, como la creación de un nuevo usuario mediante una petición POST:

@Test
void testCrearUsuario() throws Exception {
    String nuevoUsuarioJson = "{\"nombre\":\"Laura\",\"email\":\"laura@example.com\"}";

    mockMvc.perform(post("/api/usuarios")
            .contentType(MediaType.APPLICATION_JSON)
            .content(nuevoUsuarioJson)
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.id").isNumber())
            .andExpect(jsonPath("$.nombre").value("Laura"))
            .andExpect(jsonPath("$.email").value("laura@example.com"));

    List<Usuario> usuarios = usuarioRepository.findAll();
    assertThat(usuarios).hasSize(2);
}

En este test:

• Se prepara un JSON con los datos del nuevo usuario.
• Se realiza una petición POST al endpoint /api/usuarios.
• Se verifica que la respuesta tenga un status HTTP 201 Created y que el cuerpo contenga los datos correctos.
• Se consulta el repositorio para asegurarse de que el nuevo usuario ha sido almacenado en la base de datos.

Al trabajar con servicios reales, también es posible probar la lógica completa de la aplicación, incluyendo validaciones, reglas de negocio y accesos a datos. Por ejemplo, si el controlador tiene validaciones para evitar la creación de usuarios con correos electrónicos duplicados, se puede escribir un test para verificar este comportamiento:

@Test
void testCrearUsuarioEmailDuplicado() throws Exception {
    String usuarioDuplicadoJson = "{\"nombre\":\"Carlos\",\"email\":\"carlos@example.com\"}";

    mockMvc.perform(post("/api/usuarios")
            .contentType(MediaType.APPLICATION_JSON)
            .content(usuarioDuplicadoJson)
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.mensaje").value("El email ya está en uso"));
}

En este caso, se intenta crear un usuario con un email que ya existe en la base de datos, y se espera que el controlador responda con un status HTTP 400 Bad Request y un mensaje de error adecuado.

Es crucial manejar adecuadamente las excepciones y los mensajes de error en los controladores REST. Al utilizar servicios reales en los tests, se puede verificar que las excepciones lanzadas por los servicios sean correctamente capturadas y transformadas en respuestas HTTP significativas.

Además, se pueden probar operaciones que modifiquen o eliminen datos. Por ejemplo, para actualizar un usuario:

@Test
void testActualizarUsuario() throws Exception {
    String usuarioActualizadoJson = "{\"nombre\":\"Carlos Pérez\",\"email\":\"carlosp@example.com\"}";

    mockMvc.perform(put("/api/usuarios/1")
            .contentType(MediaType.APPLICATION_JSON)
            .content(usuarioActualizadoJson)
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.nombre").value("Carlos Pérez"))
            .andExpect(jsonPath("$.email").value("carlosp@example.com"));

    Usuario usuario = usuarioRepository.findById(1L).orElseThrow();
    assertThat(usuario.getNombre()).isEqualTo("Carlos Pérez");
    assertThat(usuario.getEmail()).isEqualTo("carlosp@example.com");
}

Y para eliminar un usuario:

@Test
void testEliminarUsuario() throws Exception {
    mockMvc.perform(delete("/api/usuarios/1")
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isNoContent());

    boolean existe = usuarioRepository.existsById(1L);
    assertThat(existe).isFalse();
}

Al ejecutar estos tests, se está verificando no solo el funcionamiento del controlador, sino también la interacción con los servicios, repositorios y la persistencia de datos.

Es relevante mencionar el uso de perfiles de configuración para las pruebas. En muchos casos, se define un perfil específico para tests, utilizando una base de datos en memoria y configuraciones que faciliten la ejecución de las pruebas sin afectar al entorno de desarrollo o producción. En el archivo application-test.properties, se pueden definir propiedades como:

spring.datasource.url=jdbc:h2:mem:testdb
spring.jpa.hibernate.ddl-auto=create-drop

Y en la clase de prueba, especificar el perfil a utilizar:

@SpringBootTest
@AutoConfigureMockMvc
@ActiveProfiles("test")
class UsuarioControllerIntegrationTest {
    // ...
}

De esta forma, se asegura que las pruebas se ejecuten en un entorno controlado y aislado.

Otra herramienta útil para facilitar las pruebas es la inicialización de datos mediante scripts SQL o clases de configuración. Por ejemplo, se puede utilizar data.sql para cargar datos iniciales en la base de datos al iniciar el contexto de pruebas.

En cuanto a la configuración de MockMvc, es posible personalizarla si se requieren ajustes específicos. Sin embargo, en la mayoría de los casos, @AutoConfigureMockMvc proporciona una configuración adecuada para realizar las pruebas de integración completa.

Al realizar tests de integración completa, es fundamental tener en cuenta el tiempo de ejecución y el consumo de recursos. Dado que se carga todo el contexto de la aplicación, las pruebas pueden ser más lentas en comparación con los tests unitarios o de integración parcial. Por ello, es recomendable equilibrar el número de tests de integración completa y considerarlos para verificar flujos críticos de la aplicación.

Finalmente, los tests de integración completa con @SpringBootTest y servicios reales permiten asegurar que todos los componentes de la aplicación funcionan correctamente en conjunto. Esto proporciona una mayor confianza en la calidad del software y ayuda a detectar problemas que podrían no ser evidentes al probar los componentes de manera aislada.

Explicación de todos los métodos de MockMvc específicos para json

La clase MockMvc es una herramienta fundamental en Spring Boot 3 para realizar pruebas exhaustivas de controladores REST y verificar el intercambio de datos en formato JSON. Proporciona una variedad de métodos que permiten simular peticiones HTTP y validar las respuestas de manera detallada. A continuación, exploraremos los métodos más relevantes de MockMvc y cómo utilizarlos para asegurar el correcto funcionamiento de nuestros controladores REST.

Para comenzar, es importante entender que MockMvc permite realizar solicitudes HTTP simuladas utilizando el método perform(). Este método acepta una instancia de MockHttpServletRequestBuilder, que se obtiene mediante los RequestBuilders específicos para cada tipo de petición: get(), post(), put(), delete(), entre otros. Por ejemplo:

mockMvc.perform(get("/api/usuarios"));

Al realizar una solicitud, es posible configurar diversos aspectos de la misma utilizando métodos encadenados. Algunos de los métodos más utilizados son content(), contentType() y accept(). El método content(String content) establece el cuerpo de la petición con el contenido proporcionado, siendo especialmente útil para enviar datos en formato JSON en peticiones POST o PUT. Por su parte, contentType(MediaType mediaType) define el tipo de contenido del cuerpo de la solicitud, como MediaType.APPLICATION_JSON, y accept(MediaType... mediaTypes) especifica los tipos de contenido que el cliente acepta como respuesta.

Por ejemplo, para realizar una petición POST enviando un objeto JSON:

String usuarioJson = "{\"nombre\":\"María\",\"email\":\"maria@example.com\"}";

mockMvc.perform(post("/api/usuarios")
    .contentType(MediaType.APPLICATION_JSON)
    .content(usuarioJson)
    .accept(MediaType.APPLICATION_JSON));

Tras realizar la petición con perform(), es posible verificar la respuesta utilizando diferentes ResultMatchers encadenados con el método andExpect(). Algunos de los métodos más comunes para validar la respuesta incluyen status(), content(), jsonPath() y header(). El método status() permite verificar el código de estado HTTP devuelto por el controlador, como status().isOk() para comprobar un código 200.

El método content() se utiliza para verificar tanto el tipo de contenido como el cuerpo de la respuesta. Por ejemplo, content().contentType(MediaType mediaType) comprueba el tipo de contenido de la respuesta, y content().json(String json) compara el contenido JSON de la respuesta con uno esperado. Esto es vital para asegurarse de que el controlador devuelve los datos en el formato correcto y con la estructura adecuada.

La utilización de jsonPath() es muy útil para validar campos específicos dentro del JSON de respuesta sin necesidad de comparar todo el objeto. Utiliza expresiones de JsonPath, que permiten navegar por la estructura del JSON y comprobar valores concretos. Por ejemplo:

mockMvc.perform(get("/api/usuarios/1")
    .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.nombre").value("María"))
    .andExpect(jsonPath("$.email").value("maria@example.com"));

Además, es posible verificar encabezados en la respuesta utilizando el método header(). Esto es especialmente relevante cuando el controlador devuelve información adicional a través de encabezados HTTP, como la ubicación de un recurso recién creado. Por ejemplo:

mockMvc.perform(post("/api/usuarios")
    .contentType(MediaType.APPLICATION_JSON)
    .content(usuarioJson)
    .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isCreated())
    .andExpect(header().string("Location", "/api/usuarios/1"));

También es posible configurar parámetros y encabezados personalizados en la solicitud mediante los métodos param() y header(). El método param(String name, String... values) agrega parámetros de consulta a la URL, mientras que header(String name, Object... values) añade encabezados personalizados a la petición. Por ejemplo:

mockMvc.perform(get("/api/usuarios")
    .param("page", "0")
    .param("size", "10")
    .header("X-Custom-Header", "valorPersonalizado")
    .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk());

El uso de ResultActions permite encadenar acciones y verificaciones, mejorando la legibilidad de las pruebas. Además, el método andDo() se puede utilizar para realizar operaciones adicionales, como imprimir detalles de la solicitud y la respuesta con print(), lo cual es útil para depuración.

Si el controlador utiliza cookies, estas se pueden verificar con el método cookie(). Por ejemplo:

mockMvc.perform(get("/api/usuarios/1")
    .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andExpect(cookie().exists("sessionId"))
    .andExpect(cookie().value("sessionId", "abc123"));

En ocasiones, es necesario realizar verificaciones más complejas que las proporcionadas por los matchers predeterminados. Para ello, se pueden combinar los matchers de MockMvc con los de Hamcrest, utilizando importaciones estáticas para mejorar la legibilidad. Por ejemplo:

import static org.hamcrest.Matchers.*;

mockMvc.perform(get("/api/usuarios")
    .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$", hasSize(greaterThan(0))))
    .andExpect(jsonPath("$[0].email", containsString("@example.com")));

Para pruebas que involucren datos binarios, como la descarga de archivos, es posible utilizar content().bytes(byte[] bytes) para verificar el contenido de la respuesta. Esto permite comparar los bytes recibidos con los esperados, asegurando la integridad de los datos.

La configuración avanzada de la solicitud se puede lograr mediante métodos adicionales en el MockHttpServletRequestBuilder, como characterEncoding(), locale() y sessionAttr(). Estos métodos permiten simular diferentes escenarios y configuraciones regionales.

Es fundamental también probar cómo el controlador maneja excepciones y errores. MockMvc permite verificar que se lancen las excepciones esperadas y que se devuelvan respuestas adecuadas. Por ejemplo, para comprobar que se devuelve un código 404 cuando no se encuentra un recurso:

mockMvc.perform(get("/api/usuarios/99")
    .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isNotFound())
    .andExpect(result -> assertTrue(result.getResolvedException() instanceof UsuarioNoEncontradoException))
    .andExpect(result -> assertEquals("Usuario no encontrado", result.getResolvedException().getMessage()));