Testando com Spring

Introdução ao Spring MVC Test Framework e MockMvcTester

Publicado em: 01/11/2026

Ao concluirmos esta aula, nós:

  • Saberemos o que é o Spring MVC Test Framework.
  • Seremos capazes de identificar os componentes principais do Spring MVC Test Framework (MockMvc, MockMvcBuilders, MockMvcRequestBuilders, MockMvcResultMatchers, além da evolução moderna MockMvcTester integrada ao AssertJ).
  • Saberemos como declarar as dependências necessárias com Maven e Gradle 9 tanto para aplicações Spring Framework puras quanto para aplicações Spring Boot 4.1.

O Que É o Spring MVC Test Framework?

O Spring MVC Test é um framework de testes que fornece suporte completo para testar controladores Spring MVC (@Controller e @RestController). Ao escrevermos testes unitários utilizando o Spring MVC Test Framework, devemos saber que:

  • Ele suporta qualquer motor de execução na plataforma JUnit (JUnit Jupiter 6, Kotest etc.) e TestNG.
  • Como o Spring MVC Test é construído sobre os objetos mock da Servlet API (MockHttpServletRequest, MockHttpServletResponse) fornecidos pelo módulo spring-test, ele não precisa subir um container Servlet real (como Tomcat ou Jetty), executando cada teste em poucos milissegundos!
  • Ele utiliza a classe DispatcherServlet real por baixo dos panos, oferecendo suporte fiel ao comportamento de tempo de execução do Spring MVC (roteamento de URLs, resolução de argumentos, serialização JSON, validação @Valid, tratamento de exceções e resolução de views).
  • Podemos configurar o Sistema Sob Teste utilizando a configuração standalone (standaloneSetup) ou a configuração baseada no contexto de aplicação web (webAppContextSetup). Conversaremos sobre qual escolher para testes unitários na próxima aula deste tópico.

A seguir, conheceremos os componentes principais do Spring MVC Test Framework.

Os Componentes Principais do Spring MVC Test Framework

1. Componentes de Configuração e Ponto de Entrada

Quando queremos configurar o Spring MVC Test Framework, utilizamos estes componentes:

  • MockMvc: Atua como o ponto de entrada principal que utilizamos para enviar as requisições HTTP que serão processadas pelo controlador testado.
  • MockMvcBuilders: Fornece métodos fábrica estáticos que utilizamos para criar novas instâncias de MockMvc.
  • StandaloneMockMvcBuilder: Retornado pelo método MockMvcBuilders.standaloneSetup(controller). Utilizamos esse builder quando queremos configurar a infraestrutura do Spring MVC programaticamente em modo isolado (ideal para testes unitários).
  • DefaultMockMvcBuilder: Retornado pelo método MockMvcBuilders.webAppContextSetup(webApplicationContext). Utilizamos esse builder quando queremos configurar a infraestrutura do Spring MVC a partir de um contexto completo do Spring (ideal para testes de integração).

[!TIP] Novidade no Spring Framework 6.2+ / Spring Boot 4.1: MockMvcTester Além do MockMvc clássico, o Spring moderno introduziu o MockMvcTester (org.springframework.test.web.servlet.assertj.MockMvcTester), que envolve o MockMvc (via MockMvcTester.of(controller) ou MockMvcTester.create(mockMvc)) para oferecer asserções fluentes nativas baseadas em AssertJ (assertThat(mvc.get().uri("/"))...), além da DSL Kotlin mockMvc.get("/") { ... }. Neste curso você aprenderá a API canônica do MockMvc (amplamente usada em código existente) e também verá como o MockMvcTester se conecta a ela!

2. Componentes de Requisição e Verificação de Resposta

Quando queremos criar uma requisição HTTP usando o objeto MockMvc criado, enviá-la ao controlador testado e escrever asserções sobre a resposta retornada, utilizamos estes quatro componentes:

  • MockMvcRequestBuilders: Fornece métodos fábrica estáticos (get(), post(), put(), delete(), patch(), multipart()) que utilizamos para criar as requisições HTTP processadas pelo controlador testado.
  • MockHttpServletRequestBuilder e MockMultipartHttpServletRequestBuilder: Objetos retornados pelos métodos de MockMvcRequestBuilders que nos ajudam a configurar a “entrada” enviada ao controlador (corpo da requisição, cabeçalhos HTTP, cookies, parâmetros de query/formulário, Content-Type etc.).
  • MockMvcResultMatchers: Fornece métodos fábrica estáticos (status(), view(), model(), content(), jsonPath(), header(), flash(), forwardedUrl(), redirectedUrl()) que utilizamos dentro de .andExpect(...) para escrever asserções sobre a resposta HTTP retornada.
  • MockMvcResultHandlers: Fornece métodos fábrica estáticos (print(), log()) que utilizamos dentro de .andDo(...) para imprimir detalhes completos da requisição e da resposta no console ou nos arquivos de log durante a depuração de um teste.

Falaremos em detalhes sobre como usar cada um desses componentes nas próximas aulas deste tópico. Agora vamos descobrir como obter as dependências necessárias no projeto!

Obtendo as Dependências Necessárias

Esta seção descreve como declarar as dependências necessárias tanto em uma aplicação web Spring Framework tradicional quanto em uma aplicação web que utiliza Spring Boot 4.1.

1. Dependências em uma Aplicação Web Spring Framework Tradicional

Se estivermos escrevendo testes unitários para uma aplicação web Spring Framework sem Spring Boot, precisamos declarar a dependência spring-test (e jakarta.servlet-api) no nosso script de build.

Se estivermos utilizando Maven, adicionamos o seguinte trecho ao nosso arquivo pom.xml:

1
2
3
4
5
6

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <version>7.0.5</version>
    <scope>test</scope>
</dependency>

Se estivermos utilizando Gradle 9 (Kotlin DSL), adicionamos o seguinte trecho ao nosso arquivo build.gradle.kts:

1
2
3

dependencies {
    testImplementation("org.springframework:spring-test:7.0.5")
}

2. Dependências em uma Aplicação Web com Spring Boot 4.1

Se estivermos escrevendo testes unitários para uma aplicação web que utiliza Spring Boot 4.1, basta incluir o starter de testes spring-boot-starter-test (e spring-boot-starter-webmvc-test se modularizado) em nosso script de build — ele já traz automaticamente spring-test, JUnit Jupiter 6, AssertJ, Hamcrest e JsonPath!

Se estivermos utilizando Maven, adicionamos o seguinte trecho ao nosso arquivo pom.xml:

1
2
3
4
5

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

Se estivermos utilizando Gradle 9 (Kotlin DSL), adicionamos o seguinte trecho ao nosso arquivo build.gradle.kts:

1
2
3

dependencies {
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

[!NOTE] Em projetos Kotlin com Spring Boot, lembre-se também de incluir io.mockk:mockk (como vimos no Tópico 05) e com.fasterxml.jackson.module:jackson-module-kotlin para serialização/desserialização perfeita de data classes em testes de APIs REST.

Vamos resumir o que aprendemos nesta aula!

Resumo

Nesta aula, aprendemos cinco pontos fundamentais:

  • O Spring MVC Test Framework não requer um container Servlet em execução (rodando em memória com altíssima velocidade).
  • O Spring MVC Test Framework utiliza o DispatcherServlet internamente, oferecendo suporte completo ao comportamento real do Spring MVC em tempo de execução.
  • Identificamos os componentes-chave do framework (MockMvc, MockMvcBuilders, StandaloneMockMvcBuilder, MockMvcRequestBuilders, MockMvcResultMatchers, MockMvcResultHandlers e MockMvcTester) e quando utilizá-los.
  • Para testar uma aplicação web Spring pura, declaramos a dependência org.springframework:spring-test.
  • Para testar uma aplicação web com Spring Boot, declaramos a dependência org.springframework.boot:spring-boot-starter-test.