DEV Community: Marcos Faneli

Spring e Multithreading: Um pouco sobre como Beans Singleton lidam com múltiplas requisições

Marcos Faneli — Sat, 24 Jan 2026 22:42:44 +0000

É comum sabermos que o Spring funciona com todos os seus componentes criados como singleton, mas como é que isso funciona com sua aplicação trabalhando com múltiplas requisições usando a mesma instância de bean singleton? A ideia desta breve explicação é jogar luz sobre como as coisas funcionam de fato por baixo dos panos.

Primeiro, vamos matar uma ideia errada que circula por aí: "Beans singleton significam single-threaded". Isso não é correto.

Um bean singleton significa apenas uma instância dentro do contexto do Spring. Mas essa instância pode ser usada por centenas de threads simultaneamente sem problema algum. Vamos entender o porquê disso.

A Mágica em 3 Camadas

Para realmente compreender isso, precisamos pensar além do nível da aplicação. Vamos descer um pouco:

1. Nível Aplicação (Spring + Java)

No seu servidor rodando Spring, em configuração padrão acontece isso:

Spring usa Tomcat com um pool de threads (padrão: até 200 threads)
Cada requisição HTTP chega em uma thread diferente
Todos os seus beans são singleton (uma única instância cada)
Os beans não carregam estado mutável (são stateless)

Simples assim.

2. Nível JVM

Aqui é onde fica interessante. A JVM divide a memória em algumas regiões, mas vamos abordar as duas regiões principais:

┌─────────────────────────────────────┐
│        MEMÓRIA NA JVM               │
├─────────────────────────────────────┤
│  HEAP (compartilhada)               │
│  • Objetos singleton                │
│  • Código dos métodos               │
│  • Campos de instância              │
│                                     │
│  STACK (isolada por thread)         │
│  • Thread 1: variáveis locais       │
│  • Thread 2: variáveis locais       │
│  • Thread 3: variáveis locais       │
└─────────────────────────────────────┘

A fórmula mágica está aqui: CÓDIGO (heap) + DADOS LOCAIS (stack) = Thread-Safe

O código fica no heap, compartilhado entre todas as threads. Mas os dados locais (variáveis de método) ficam na stack de cada thread isoladamente. Logo, não há conflito.

3. Nível Hardware

No processador, funciona mais ou menos assim:

Seu objeto singleton vive em um endereço fixo na RAM (algo como 0x7f8a2c00)
Todas as threads leem desse endereço simultaneamente
Cada núcleo de CPU mantém uma cópia em cache
Leitura é naturalmente thread-safe, escrita precisa sincronização

Por Que Funciona

Vamos pegar um exemplo real:

@Service
public class CustomerService {
    @Autowired
    private CustomerRepository repository; // ← Fica na HEAP, só leitura ✅

    public CustomerResponse evaluate(String customerName, String locationId) {
        Customer customer = repository.findByName(customerName);  // ← Variável local, STACK ✅
        boolean result = checkConditions(customer, locationId); // ← Variável local, STACK ✅
        return new CustomerResponse(result);              // ← Novo objeto, STACK ✅
    }
}

Veja só o que tá acontecendo:

repository (injetada): Está na heap, todas as threads leem ela. Mas como ninguém tá modificando, fica tranquilo.
customer: É uma variável local, fica na stack de cada thread isoladamente.
result: Mesma coisa, stack isolada.
Retorno: Um novo objeto criado para essa requisição específica.

Zero race conditions. Totalmente isolado.

Visualizando Tudo Junto

Imagina que 3 requisições chegam ao mesmo tempo no seu servidor:

T1: Request 1 → evaluationService.evaluate("feat-x", "client-1")
T2: Request 2 → evaluationService.evaluate("feat-y", "client-2")  
T3: Request 3 → evaluationService.evaluate("feat-x", "client-3")

┌──────────────────────────────┐
│  HEAP                        │
│  EvaluationService @ 0x7f... │  ← 1 instância
│  └─ repository               │
└──────────────────────────────┘

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  STACK T1    │  │  STACK T2    │  │  STACK T3    │
├──────────────┤  ├──────────────┤  ├──────────────┤
│ toggle ref   │  │ toggle ref   │  │ toggle ref   │
│ result       │  │ result       │  │ result       │
│ clientId     │  │ clientId     │  │ clientId     │
└──────────────┘  └──────────────┘  └──────────────┘
   Cada uma isolada

Cada thread tem seu próprio espaço na stack. Não tem colisão.

O Lado Perigoso

Mas claro que tem um "mas". Olha isso:

@Service
public class CounterService {
    private int counter = 0; // ❌ CAMPO MUTÁVEL COMPARTILHADO!

    public void increment() {
        counter++; // ❌ RACE CONDITION!
    }
}

Aqui sim teremos problema. Por quê? Porque counter está na heap, compartilhada entre as threads. Se duas threads tentarem incrementar ao mesmo tempo, uma pode sobrescrever o valor da outra.

Solução: Usar synchronized, AtomicInteger, ou simplesmente não manter estado na classe. Mantenha a classe sempre stateless.

Timeline de Execução Completa

Para deixar cristalino, vamos rastrear uma requisição do começo ao fim:

T0: Requisição chega via HTTP

T1: Tomcat pega uma thread do pool → Thread-123

T2: DispatcherServlet roteia para controller

T3: Controller injeta dependências (todas singleton, heap)
    → Todas as threads acessam o MESMO endereço de memória

T4: Entra no método da service
    → Cria variáveis locais (STACK isolada da T-123)

T5: Faz chamada ao banco
    → Mesma thread, stack isolada

T6: Processa resultado
    → Completamente local

T7: Retorna resposta
    → Nova instância de resposta criada (heap, mas única para essa req)

T8: Response é serializada e enviada
    → Thread-123 volta pro pool, pronta para próxima requisição

Repare: Mesmo que outras threads estejam processando outras requisições ao mesmo tempo, cada uma tem seu próprio contexto de execução isolado. Sem conflito.

A Regra de Ouro

E se tu fosse me resumir tudo em uma frase, seria:

"Mantenha seus beans STATELESS e o Spring cuida do resto automaticamente."

Sem campos mutáveis compartilhados, não tem sincronização necessária. Simples demais para ser verdade, mas é.

Comparação Rápida

Só para consolidar tudo:

Aspecto	Singleton Bean	Comportamento
Instâncias	1 objeto	Compartilhado entre threads
Threads simultâneas	200+	Executam em paralelo tranquilamente
Campos de instância	Heap (compartilhados)	⚠️ Perigoso se mutáveis
Variáveis locais	Stack (isoladas)	✅ Thread-safe automático
Métodos	Heap (código compartilhado)	✅ Seguro, só lê
Objetos retornados	Heap (sempre novos por req)	✅ Isolado por requisição

Resumindo Tudo

A arquitetura do Spring Boot é linda assim:

Singleton beans economizam memória
Design stateless garante segurança
Pool de threads permite processamento paralelo
Isolamento de stack protege variáveis locais

Testes integrados com Wiremock

Marcos Faneli — Tue, 27 Aug 2024 11:33:54 +0000

A um tempo atrás de escrevi um artigo sobre teste de integração para APIs com spring (https://dev.to/marcosfaneli/testes-integrados-com-spring-4n5d). Neste artigo a ideia era apresentar de maneira simples como começar construir uma aplicação com cobertura de teste desde seu inicio, mas convenhamos nenhuma (ou quase nenhuma) na vida real vai se apresentar assim como o exemplo, um CRUD simples e mais nada.
Este pensamento me levou a pensar em evoluir esse projeto e acrescentar a ele algumas situações de vida real.

Para começar vamos olhar para o projeto inicial:
https://github.com/marcosfaneli/spring-with-integration-test/tree/feat/refactor.

Este é o mesmo projeto usado no artigo anterior, mas para facilitar a vida fiz alguns refactor, para deixar o código mais coeso e para facilitar especialmente nosso trabalho aqui (e por que eu gosto de refatorar código também).

Qual o desafio?

Recapitulando rapidamente o projeto base, a ideia de "negócio" dele. O projeto se trata de aplicação que irá controlar ordens de serviço. Para tal ela recebe uma payload com a descrição do pedido de serviço e persiste numa base dados, no caso um Postgres.

Payload entrada

{
   "description": "Some description"
}

Saída

{
   "id": "xxxxxxxxxxxxx",
   "description": "Some description",
   "created_at": "2024-02-21T23:58:01:000z",
   "updated_at": "2024-02-21T23:58:01:000z",
   "status": "OPENED"
}

Então qual vai ser o desafio? Vamos fazer uma evolução, na criação dessa ordem de serviço queremos que ter informado quem é o cliente que solicitou a criação dela. Então vamos alterar nosso payload de entrada para:

{
  "customerCode": "123456",
  "description": "Some description"
}

Veja que no payload acima temos um novo campo customerCode, este campo irá trazer o código do cliente solicitante e ai começa a diversão. Como é muito comum em nossos cenários do dia-a-dia, precisaremos obter os dados do cliente em uma outra API que irá nos fornecer os dados dos cliente.
Este é um cenário bastante comum em organizações que implementam arquiteturas de microsserviços, onde os dados de clientes provavelmente estarão em outro serviço e consequentemente (ou na maioria das vezes) em outra base de dados.
Um outro cenário comum é construirmos aplicações que precisaram se conectar a alguma outra aplicação, já existente que nos forneça este dados.
Tendo em vista este cenário nosso analista/PO/qualquer outro papel, nos apresentou que iremos consumir uma API Rest "xpto" que irá nos retornar esses dados de cliente com o seguinte formato:

URL: GET http://xpto/customers/{customerCode}

{
  "id": "123456",
  "name": "John Doe",
  "email": "john@doe.com"
}

Mockando nossa API Externa

Neste exemplo falamos acima que iremos usar uma api externa, onde iremos consultar o dados de cliente. Bem este é um cenário bem comum no dia, outro cenário bem comum é precisarmos consumir uma api que ainda não temos acesso, ou mesmo uma api que ainda não existe. Eu sei, o primeiro desejo é cruzar os bracinhos, bater o pezinho e dizer "Se a api nem existe ainda/não temos acesso, por que é que estamos nos adiantamos em consumi-la?". A resposta é alguém te um prazo e você é quem vai cumpri-lo, aceite isso e livre de horas de frustração. Para tal situação há várias estratégias válidas, eu irei apresentar aqui uma que tenho usado à algum tempo e que agiliza muito trabalho, trata-se do Wiremock, esta ferramenta oferece uma série de ferramentas que permite lidar com esse problema (Se você é um feliz usuário de Intellij, ele oferece alguns plugins bem legais, na versão paga é claro). Vamos falar sobre dois usos dele, primeiro como mock externo simulando nossa possível api e segundo fazendo o mock nos nossos teste integrados. Vamos começar então fazendo a configuração standalone, que é basicamente subir um serviço HTTP no meu/no seu computador onde faremos que ele retorne um payload específico quando uma chamada for feita para ele, esses retorno são resultados estáticos que iremos gera-los a partir de arquivos JSON onde poderemos definir qualquer estrutura que nos for necessária. (A documentação detalhada pode ser encontrada em https://wiremock.org/docs/standalone/java-jar/).

Baixaremos o jar no link https://wiremock.org/docs/download-and-installation/

Uma vez baixado, aqui valem duas dicas, se você pretende usa-lo para "mockar"(sim, eu aportuguesei o temos mock) tudo que quiser usar na sua maquina, você pode coloca-lo em uma pasta onde poderá aciona-lo e altera-lo sempre que necessário, particularmente eu uso bastante isso, é bem comum que no dia-a-dia você precise criar diversas integrações com diversas apis e sistemas diversos podem precisar dos mesmos mocks, nesse sentido já cheguei até mesmo colocar uma alias no bash para acionar o Wiremock com apenas uma comando a qualquer momento. Agora uma outra abordagem válida e que pode ajudar a vida do coleguinha que irá mais tarde precisar rodar a sua aplicação é colocar essa configuração a seguir dentro da pasta da sua própria aplicação e documentar muito bem no readme como executar o mock, assim o próximo terá uma vida uma vida um pouco mais fácil.
Vou seguir esse segunda abordagem aqui, sendo assim dentro da pasta raiz do projeto iremos criar uma pasta que chamaremos de mock.

Pronto, agora coloque o .jar baixado dentro desta pasta. E logo após isso vamos criar dentro desta pasta, mais duas outras pastas.

__files
mappings

Vamos criar nosso primeiro mock, dentro da pasta mappings, vamos criar um arquivo customer.json com o seguinte conteúdo:

 {
  "request": {
    "method": "GET",
    "url": "/api/customers/1"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"id\":\"1\",\"name\":\"John Doe\",\"email\":\"john@doe.com\"}"
  }
}

O arquivo já é bem auto-explicativo, mas acho que valem alguns pontos a serem discutidos. Ele é dividido em request e response, na parte do request você pode definir qual será o método HTTP da chamada, podemos usar qualquer um, e qual será o path que o Wiremock irá disponibilizar o endpoint. No response estão dispostos qual o statusCode que desejamos retornar, headers específicos e o body, note que este é um campo string, assim o JSON precisará ser colocado neste formato.
Pronto, com essa simples estrutura já temos nossa API de customers, para testar basta via terminal(use o de seu gosto), navegar atá a pasta mock que criamos acima e digitar o seguinte commando:

java -jar wiremock-standalone-3.8.0.jar --port 9999

Uma vez executado se formos no navegador poderemos ver que ele esta funcionando:

Agora sim, ajustando a aplicação?

Vamos incluir a nossa chamada a api na criação de uma nova ordem de serviço.
Então a primeira coisa que precisaremos alterar nosso Dto, adicionando o novo campo customerCode, como falamos acima, assim o record app.controller.dto.CreateOrderDto de verá ficar com a seguinte estrutura:

public record CreateOrderDto(String description, String customerCode) {
}

Com isso podemos alterar o nosso UseCase CreateOrder. Hoje ele te a seguinte estrutura.


import com.seuprojeto.integrationtest.app.controller.dto.CreateOrderDto;
import com.seuprojeto.integrationtest.domain.Order;
import com.seuprojeto.integrationtest.infra.OrderRepository;
import org.springframework.stereotype.Service;

@Service
public class CreateOrder {

    private final OrderRepository repository;

    public CreateOrder(OrderRepository repository) {
        this.repository = repository;
    }

    public Order execute(CreateOrderDto createOrderDto) {
        final Order order = Order.create(createOrderDto.description());
        return this.repository.save(order);
    }
}

Extremamente simples, simplesmente faz o parser e do DTO para a nossa classe de domínio e persiste na banco.
Então vamos implementar aqui a nossa chamada para a API de customer, que acabamos de "mockar" acima. Vamos usar o RestTemplate, se você esta pensando "Mas o RestTemplate está deprecated", você está certo, fique a vontade para trocar esta chamada por qualquer outro componente e notar qu ainda sim ao fim deste artigo os testes irão funcionar. Para fazer a implementação primeiramente vamos declarar o endereço da nossa api na properties, então no arquivo application.yaml vamos adicionar as seguintes linhas:

customer:
  api:
    url: http://localhost:9999/api/customers

Note que ali adicionamos o endereço da nossa api que subimos com Wiremock, outro ponto importante é que precisamos adicionar no application, tanto do código da aplicação, quanto no application dos test.

Para que possamos usar o RestTemplate melhor vamos criar o DTO que irá receber os dados que serão retornados pela nossa API, assim criaremos uma novo record em com/seuprojeto/integrationtest/app/usecase/dto:

package com.seuprojeto.integrationtest.app.usecase.dto;

public record CustomerDto (String id, String name, String email) {
}

Feito isso voltemos ao código do nosso CreateOrder e altera-lo para o seguinte código:

package com.seuprojeto.integrationtest.app.usecase;

import com.seuprojeto.integrationtest.app.controller.dto.CreateOrderDto;
import com.seuprojeto.integrationtest.app.usecase.dto.CustomerDto;
import com.seuprojeto.integrationtest.domain.Order;
import com.seuprojeto.integrationtest.infra.OrderRepository;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.stereotype.Service;

@Service
public class CreateOrder {

    @Value("${customer.api.url}")
    private String customerApiUrl;

    private final OrderRepository repository;

    public CreateOrder(OrderRepository repository) {
        this.repository = repository;
    }

    public Order execute(CreateOrderDto createOrderDto) {

        final String url = customerApiUrl +"/{id}";

        final CustomerDto customer = new RestTemplateBuilder()
                .build()
                .getForObject(url, CustomerDto.class, createOrderDto.customerCode());

        System.out.println("Customer: " + customer);

        final Order order = Order.create(createOrderDto.description());
        return this.repository.save(order);
    }
}

Bem o foco deste artigo é garantir teste, pois bem, se neste momento vc tentar rodar nossos testes irá notar que eles terão quebrado, especialmente onde instanciamos o nosso record CreateOrderDto. Bem você bem lembra que adicionamos a ele um novo campo, o customerCode, resolver isso é fácil, por favor em todas as linhas onde ele tiver quebrado, a usa IDE deve ter acusado, substitua a linha por isto:

Esta:

final CreateOrderDto createOrderDto = new CreateOrderDto(description);

Por esta:

final CreateOrderDto createOrderDto = new CreateOrderDto(description, "1");

Mas vale uma observação, uma alteração quebrou em vários lugares o nosso código, isso pode estar demonstrando um certo acoplamento, o que nos levanta um possível "code smell", para este caso específico considere o uso de Fixture.

Muito bem, feito todos estes ajustes, considerando que seu Wiremock standalone esteja rodando, se executarmos agora nossos teste eles irão passar sem maiores problemas.

Ainda teríamos que persistir estes dados obtidos na base de dados, mas foge ao foco, deixarei isso feito no código, junto com todo o restante.

Resolvemos todos os nossos problemas?

Bem até aqui conseguimos implementar nossas chamadas e esta funcionando dignamente, mas considere que é bastante comum que os teste sejam executados por exemplo por automatizações durante o deploy da sua aplicação, ai você já deve ter notado que neste cenário talvez o que acabamos de montar não seja satisfatório, já que nosso mock é na verdade uma aplicação sendo executada na nossa maquina, logo teríamos o famoso "Na minha maquina funciona". Não quer dizer que nosso esforço para criar o serviço Wiremock foi em vão, isso pode ser bastante útil em tempo de desenvolvimento da aplicação.

Precisamos garantir que nossos testes possam ser executados independente de integrações externas, isso permitirá que os teste possam ser utilizados em pipelines de deploy automatizadas por exemplo. Para esta solução iremos continuar utilizando o poder do Wiremock, mas agora a sua lib. Para começar vamos adicionar uma nova dependência no pom.xml.

<dependency>
  <groupId>org.wiremock</groupId>
  <artifactId>wiremock-standalone</artifactId>
  <version>3.9.1</version>
  <scope>test</scope>
</dependency>

Com a dependência do Wiremock adicionadas precisaremos configurar no arquivo OrderControllerIntegrationTest uma instancia do WireMockServer para execução dos nossos teste. Esta instancia do WireMockServer irá responder as chamadas externas do nossos serviços, vamos inserir o seguinte trecho de código:


    private static WireMockServer wireMockServer;

    @BeforeAll
    static void setUpWireMock() {
        wireMockServer = new WireMockServer(WireMockConfiguration.wireMockConfig().port(9999));
        wireMockServer.start();

        final CreateOrderDto createOrderDto = CreateOrderFixture.createOrderDto();
        final String customerCode = createOrderDto.customerCode();

        wireMockServer.stubFor(get(urlEqualTo("/api/customers/" + customerCode))
                .willReturn(aResponse()
                        .withHeader("Content-Type", "application/json")
                        .withBody("{\"id\": \"" + customerCode + "\", \"name\": \"John Doe\"}")));
    }

O importante neste método é a annotation @BeforeAll, ela irá garantir que este método será executado antes de todos os outros, obrigatoriamente este método é static, por que ele precisa esta acessível para toda a execução de teste, o método anotado com beforeAll terá sua execução compartilhada por todas a classes de teste durante a execução deste. Uma alternativa pode ser coloca-lo em um classe separada, especialmente se houverem mais recursos a serem compartilhados.

Neste trecho iremos subir um serviço HTTP que irá responder como se fosse a nossa chamada ao o serviço externo, assim não precisaremos mais do serviço Wiremock standalone para a execução dos teste. Note que a porta informada na linha wireMockServer = new WireMockServer(WireMockConfiguration.wireMockConfig().port(9999));é exatamente a mesma porta configurada no arquivo application.yaml na pasta de tests.

Antes de executarmos novamente os teste e verificarmos que eles terão funcionado é importante pensarmos que o beforeAll criou uma instancia de um serviço Http, então é importante ao fim da execução dos teste finalizarmos isso, por isso vamos incluir mais um trecho de código que irá garantir isso:

    @AfterAll
    static void tearDownWireMock() {
        wireMockServer.stop();
    }

Pronto com este último método implementado podemos executar nossos testes sem problemas, veremos que eles irão passar com sucesso, mesmo sem fazer a chamada para serviços externos.

Pontos importantes aqui não abordamos alterações na persistência de dados, incluindo as novas informações que obtivemos da api, tão pouco também fizemos teste para o comportamento esperado da aplicação caso essa api falhe, podemos abordar isso em um novo artigo(bem presunçoso chamar de artigo, não?).

Toda a implementação pode ser observada no repositório do projeto:

https://github.com/marcosfaneli/spring-with-integration-test/tree/feat/article-02

Obs.: Atenção que essas alterações estão na branch feat/article-02.

Testes integrados com Spring

Marcos Faneli — Fri, 23 Aug 2024 13:42:34 +0000

Qual a ideia aqui?

A ideia deste artigo é mostrar que é possível desenvolver uma aplicação com Spring iniciando já com cobertura de teste, dando maior segurança no que está sendo desenvolvido já esteja funcionando como o esperado, e evitando a aquela preguiça de implementar teste “depois que tudo já está pronto”, só para atingir o quality gate da firma.

Então vamos lá, por partes…

Teste de integração

Permite testar a aplicação de forma transversal, atravessar toda ela, passando por todos os pontos, assim uma chamada HTTP, ira passar por todos os seus componentes de código e testando como ele funcionam entre si. Isso vai lhe dar garantia que todo o fluxo da aplicação está funcionando, no entanto, normalmente é um tipo de teste mais caro, sim, caro, pois consome muito mais recursos, uma medida disso é só observar o tempo que estes teste levam para executar.

TDD

Fiquem a vontade para questionar minha visão aqui

A intenção aqui embora seja começar a construir sua aplicação a partir de teste de integração, não é necessariamente TDD, a ideia do TDD é construir testes de unidade, como falamos anteriormente teste de unidade tem uma granularidade maior, pretende testar cada unidade de código sem depender de componentes a ele integrados, logo não ficar sujeitos a comportamentos externos ao componente testado.

Tendo isso em vista, pode ser uma maneira de construir sua aplicação, mas importante se ter em vista que os testes de integração tomam mais tempo para ser executados, logo atrasando o ciclo de feedback rápido proposto pelo TDD. Bem, mas ainda, sim, você tem um desenvolvimento coberto por testes.

O Projeto

A ideia aqui é prover um projeto simples, uma API Rest e suas 4 operações básicas (o bom e velho CRUD, você sabe o que é CRUD certo? Não sabe, tudo bem leia aqui) e construir cada endpoint a partir de seu devido teste.

Teremos então uma API de ordens de serviço:

POST /orders: Irá receber a seguinte request:

{
  "description": "Some description"
}

Irá criar no banco de dados uma ordem de serviço e retornar a ordem criada conforme abaixo:

{
  "id": "xxxxxxxxxxxxx",
  "description": "Some description",
  "created_at": "2024-02-21T23:58:01:000z",
  "updated_at": "2024-02-21T23:58:01:000z",
  "status": "OPENED"
}

GET /orders: Listar todas as ordens do banco (listar tudo errado, claro, mas vamos por partes).

Irá retornar uma lista das ordens de serviços do banco de dados com o seguinte formato:

```json
[
  {
    "id": "xxxxxxxxxxxxx",
    "description": "Some description",
    "created_at": "2024-02-21T23:58:01:000z",
    "updated_at": "2024-02-21T23:58:01:000z",
    "status": "OPENED"
  }
]
```

PUT /orders/:id: Irá receber a seguinte request conforme abaixo e o id de uma ordem já existente informado no path da request.
```
{
  "description": "Some description",
  "status": "CLOSED"
}
```

Irá criar no banco de dados uma ordem de serviço e retornar a ordem criada conforme abaixo:

```json
{
  "id": "xxxxxxxxxxxxx",
  "description": "Some description",
  "created_at": "2024-02-21T23:58:01:000z",
  "updated_at": "2024-02-23T13:35:09:135z",
  "status": "OPENED"
}
```

Caso seja informado um id de uma ordem inexistente deverá retornar um erro com StatusCode 404.

GET /orders/:id
Irá receber o id de uma ordem já existente informado no path da request, irá consulta no banco de dados e retornar um registro conforme abaixo:

{
  "id": "xxxxxxxxxxxxx",
  "description": "Some description",
  "created_at": "2024-02-21T23:58:01:000z",
  "updated_at": "2024-02-23T13:35:09:135z",
  "status": "OPENED"
}

Caso seja informado um id de uma ordem inexistente deverá retornar um erro com status code 404.

DELETE /orders/:id: Irá receber id de uma ordem já existente informado no path da request. Não há payload aqui.

Quais tecnologias?

Usaremos o aqui o imortal Java

E algumas de suas parcerias de sucesso:

Spring
PostgreSQL

Isso será o core da nossa aplicação, mas adicionaremos alguma libs para nosso propósito. Primeiro o banco de dados H2, aqui você deve se perguntar: “- Dois banco de dados?”. O H2 será usado somente para os nossos testes, ele é um banco que funciona em memória e será ideal para o nosso propósito aqui, e em muito cenários de aplicações reais, desde que o banco seja usado para o seu correto propósito, armazenar dados (cabe sua discordância aqui também, só a minha traumatizada opinião).

Para criar o projeto usaremos o site do próprio Spring Initializr. Criando algo assim:

Bastante atenção para as libs aqui adicionadas e para as versões escolhidas, veja:

Spring: 3.3.1
Java: 21

Usaremos o Maven para gerenciar dependências e o build do nosso projeto.

Conforme podemos ver na imagem acima ao clicar no botão “Generate” um arquivo será gerado .zip com um projeto base, descompactaremos em lugar de preferência e iremos abri-lo na nossa IDE preferida, aqui usaremos Intellij CE. Isso pode ser importante ressaltar por que alguns exemplos podem ser dados estritamente usando a ferramenta, por simples questão de agilidade, mas tendo o conhecimento necessário, qualquer ferramenta serve.

A estrutura resultante dentro da pasta deve ser algo assim:

Veja que por padrão já teremos um package test, será nele que iremos criar nosso teste. Vamos criar um package e chamá-lo de integration:

Vamos começar por um teste simples que nos permita estruturar nossa classe de teste, vamos testar nosso primeiro endpoint que irá nos retornar uma lista vazia das nossas ordens. Primeiro momento vamos criar um teste somente para efetuar toda a configuração necessária para nosso teste.

Sabendo que temos um teste de integração e nosso contexto terá um banco de dados, vamos começar fornecendo ao Spring as configurações que ele precisa para alcançar estes recursos, no nosso caso o banco de dados H2(lembra dele, mas fixando, somente para os nosso testes). Assim criaremos um arquivo application.yaml em src/test/resources com o seguinte conteúdo:

spring:
  datasource:
    driver-class-name: org.h2.Driver
    url: jdbc:h2:mem:testdb
    username: sa
    password: password
  jpa:
    database-platform: org.hibernate.dialect.H2Dialect
    hibernate:
    ddl-auto: create-drop
    show-sql: true
  h2:
    console:
    enabled: true

Dentro da pasta acima que acabamos de criar vamos criar uma classes que chamaremos OrderControllerIntegrationTest, ela tera a seguinte estrutura:

package com.seuprojeto.integrationtest.integration;

import org.junit.jupiter.api.TestInstance;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.annotation.DirtiesContext;
import org.springframework.test.web.servlet.MockMvc;

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@AutoConfigureMockMvc
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class OrderControllerIntegrationTest {

    private static final String ORDER_URL = "/orders";

    @Autowired
    MockMvc mockMvc;
}

Vamos falar sobre cada uma das linhas:

@TestInstance(TestInstance.Lifecycle.PER_CLASS): Garantir que somente uma instância da classe de teste será criada. Mais especificamente, o Junit5 por padrão cria uma nova instância da classe para cada teste que implementamos, isso especialmente para garantir total isolamento entra cada caso de teste, no entanto, isso é um tanto quanto custoso se você tem cenário que exigem muita configuração para serem executados. Isso nos remete ao início deste artigo, onde falamos que testes de integração podem ser custosos, dessa forma usaremos essa anotação para que uma instância seja criada para cada classe, assim permitindo compartilhar o estado de alguns objetos (não serão criados e destruídos a cada teste), neste caso o MockMvc, que é o que usaremos para fazer nossas chamadas HTTP. Ops, meio que começamos a falar da linha seguinte. Isso irá nos permitir economizar um pouco de recursos na execução dos nossos testes, tornando um pouco mais rápidos também.
@AutoConfigureMockMvc: Fará a configuração automática do objeto MockMvc, que usaremos para fazer nossas chamadas HTTP.
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD): Informar que o contexto do Spring foi alterado a cada teste, assim garante que o contexto do Spring seja reiniciado a cada caso de teste. Isso impede que alterações no contexto do Spring feitas em um teste não impacte em outro teste. Neste ponto aqui é importante compreender o que o contexto do Spring e como ele funciona, o que não iremos aprofundar.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT): Indica que iremos usar testes de integração do spring, garantindo assim que o Spring faça a devida manipulação do contexto.

Passamos mais detalhadamente por essas linhas por que no contexto de configuração de testes essa classes são bastante importantes e requerem um pouco de detalhamento sobre elas, as demais classes são coisas mais “simples” e vamos falar em blocos.

private static final String ORDER_URL = "/orders";

@Autowired
MockMvc mockMvc;

Declaramos uma propriedade estática para o uri, porque iremos repeti-la algumas vezes e por boa prática vamos guardá-la em uma variável e na sequência injetamos o objeto MockMvc que usaremos para fazer nossas chamadas HTTP e fazer nossos testes.

Primeiro teste

Este primeiro só irá garantir que todo o aparato de configurações estejam funcionando, então neste momento não iremos no aprofundar muito, iremos fazer isso a medida que nossos cenários de teste se tornem mais maduros.

@Test
void shouldReturn200WhenGetAllOrders() throws Exception {
    mockMvc.perform(MockMvcRequestBuilders.get(ORDER_URL))
            .andExpect(status().isOk())
            .andReturn();
}

Considerando que não temos nenhuma entidade qualquer criada em nossa aplicação, então este teste espera que ao fazer uma chamada GET para a URI /orders devemos ter como retorno um StatusCode 200.

Uma adendo aqui, ao construir o caso de teste na nossa classe, para executar basta clicar no botão exibido pela IDE (Eu disse que usaríamos dos recursos da IDE):

Ao executar este teste receberemos um caloroso 404, obviamente, já que não implementamos esta rota em nossa aplicação ainda.

Então vamos fazer este teste passar. Para isso iremos criar a controller que irá responder a nossa chamada, ignore aqui a maneira com que classes e packages serão criados, não iremos discutir sobre isso neste artigo, além do mais considerando que o spring é responsável por gerenciar a injeção de dependência, a estrutura de como as packages são criadas não é necessariamente importante. Vamos lá, iremos criar a seguinte package com/seuprojeto/integration/app/controller:

Dentro dela iremos criar nossa controller, como abaixo:

package com.seuprojeto.integrationtest.app.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping
    public List<?> getAllOrders() {
        return List.of();
    }
}

Não é o que pretendemos, mas essa simples implementação fará nossos testes passarem com sucesso, isso irá validar que nosso testes estão, por hora, configurados com sucesso.

Segundo teste

Bem, agora vamos um pouco mais fundo, começar a fazer testes que, de fato, irão atravessar camadas da nossa aplicação. Vamos implementar o caso de para criação de uma ordem e persistir no banco de dados.

Este será nosso segundo caso de teste, mais uma vez vamos por partes aqui, não é um teste conforme esperado e iremos melhora-lo:

@Test
void shouldReturn201WhenCreateOrder() throws Exception {
    var response = mockMvc.perform(MockMvcRequestBuilders.post(ORDER_URL).content("{\"description\": \"some description\"}").contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andReturn();

    System.out.println(response.getResponse().getContentAsString());

    Assertions.assertTrue(response.getResponse().getContentAsString().contains("description"));
    Assertions.assertTrue(response.getResponse().getContentAsString().contains("some description"));
    Assertions.assertTrue(response.getResponse().getContentAsString().contains("id"));
    Assertions.assertTrue(response.getResponse().getContentAsString().contains("createdAt"));
    Assertions.assertTrue(response.getResponse().getContentAsString().contains("updatedAt"));
    Assertions.assertTrue(response.getResponse().getContentAsString().contains("status"));
    Assertions.assertTrue(response.getResponse().getContentAsString().contains("OPENED"));
}

Se executarmos agora teremos um StatusCode 405, ou seja, o rota /orders foi encontrada, mas o método POST não esta implementado, vamos cuidar disso.

Primeiro vamos criar nossa classe de domínio Order, ela será nossa e também nosso entidade para banco de dados. Criaremos em um novo package com/seuprojeto/integration/domain e dentro dele as classes abaixo:

package com.seuprojeto.integrationtest.domain;

import jakarta.persistence.*;

import java.time.LocalDateTime;
import java.util.UUID;

@Entity
@Table(name = "orders", schema = "public")
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;
    private String description;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    private Status status;

    public Order() {
    }

    public Order(UUID id, String description, LocalDateTime createdAt, LocalDateTime updatedAt, Status status) {
        this.id = id;
        this.description = description;
        this.createdAt = createdAt;
        this.updatedAt = updatedAt;
        this.status = status;
    }

    public static Order create(String description) {
        return new Order(UUID.randomUUID(), description, LocalDateTime.now(), LocalDateTime.now(), Status.OPENED);
    }

    public UUID getId() {
        return id;
    }

    public String getDescription() {
        return description;
    }

    public LocalDateTime getCreatedAt() {
        return createdAt;
    }

    public LocalDateTime getUpdatedAt() {
        return updatedAt;
    }

    public Status getStatus() {
        return status;
    }
}

package com.seuprojeto.integrationtest.domain;

public enum Status {
    OPENED, CLOSED, CANCELED;
}

Pensando no isolamento das nossas classes de domínio das extremidades da nossa aplicação não iremos expor-las nas bordas do sistema, então criaremos dois records DTO para fazer a comunicação com partes eternas de nossos sistemas, no caso a interface HTTP Rest, assim criaremos duas classes em com/seuprojeto/integration/app/controller/dto .

Este primeiro é a estrutura que irá receber o JSON para criação de uma ordem, conforme contrato estabelecido.

public record CreateOrderDto(String description) {
}

Este segundo tem o contrato conforme esperado para saída do método de criação.

package com.seuprojeto.integrationtest.app.controller.dto;

import com.seuprojeto.integrationtest.domain.Order;

public record OrderCreatedDto(String id, String description, String status, String createdAt, String updatedAt) {
    public static OrderCreatedDto from(Order order) {
        return new OrderCreatedDto(
                order.getId().toString(),
                order.getDescription(),
                order.getStatus().name(),
                order.getCreatedAt().toString(),
                order.getUpdatedAt().toString());
    }
}

E agora iremos criar a classe de acesso a banco de dados, normalmente aqui eu adicionaria mais uma camada, de usecase, para que cada fluxo da aplicação ficasse devidamente separado, mas não irei me alongar ainda mais.

Então vamos ajustar nossa controller para permitir atender nossos requisitos de teste, assim nossa classe ficará assim:

package com.seuprojeto.integrationtest.app.controller;

import com.seuprojeto.integrationtest.app.controller.dto.CreateOrderDto;
import com.seuprojeto.integrationtest.app.controller.dto.OrderCreatedDto;
import com.seuprojeto.integrationtest.domain.Order;
import com.seuprojeto.integrationtest.infra.OrderRepository;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/orders")
public class OrderController {

    private final OrderRepository repository;

    public OrderController(OrderRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public List<?> getAllOrders() {
        return List.of();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderCreatedDto createOrder(@RequestBody CreateOrderDto createOrderDto) {
        final Order order = Order.create(createOrderDto.description());
        final Order orderSaved = this.repository.save(order);
        return OrderCreatedDto.from(orderSaved);
    }
}

E voilá, nosso teste irá passar com sucesso.

Mas voltemos a composição do nosso teste, ele não muito apresentável, e além de tudo passível de algumas falhas. Primeiro que não esta legal é o fato de que estamos usando muitas validações com string, isso fica ruim para mater além de um tanto verboso. Vamos fazer algumas melhorias então, veja que nossa classe controller recebe e retorna classes, podemos utilizar as mesmas para compor nosso teste. Então vamos fazer alterações na nossa classe de teste, primeiro adicionando um novo objeto:

package com.seuprojeto.integrationtest.integration;

import com.fasterxml.jackson.databind.ObjectMapper;
...
class OrderControllerIntegrationTest {

    private static ObjectMapper objectMapper = new ObjectMapper();
...

Obs.: Algumas partes da classe foram omitidas, para dar enfase ao que foi adicionado.

ObjectMapper usaremos para fazer a serialização das nossas classes(records) de entrada e saída, melhorando a compreensão de nossos testes. Vamos refatorar nosso caso de teste conforme abaixo:

...
import java.util.regex.Pattern;
...
@Test
void shouldReturn201WhenCreateOrder() throws Exception {
    final String description = "some description";
    final CreateOrderDto createOrderDto = new CreateOrderDto(description);
    final String payload = objectMapper.writeValueAsString(createOrderDto);

    final MvcResult response = this.mockMvc.perform(MockMvcRequestBuilders.post(ORDER_URL).content(payload).contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andReturn();

    OrderCreatedDto orderCreatedDto = objectMapper.readValue(response.getResponse().getContentAsString(), OrderCreatedDto.class);

    Pattern pattern = Pattern.compile("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$");

    Assertions.assertNotNull(orderCreatedDto.id());
    Assertions.assertTrue(pattern.matcher(orderCreatedDto.id()).matches());
    Assertions.assertEquals(description, orderCreatedDto.description());
    Assertions.assertNotNull(orderCreatedDto.createdAt());
    Assertions.assertNotNull(orderCreatedDto.updatedAt());
    Assertions.assertEquals("OPENED", orderCreatedDto.status());
}

Agora nosso teste estão diretamente vinculados a nossas classes, assim quando houverem alterações nessas, será mais fácil identificar onde os teste foram quebrados, tão quanto fazer os ajustes necessários, tão como ficou mais legível o que está sendo testado.

Terceiro teste

Vamos agora testar nosso endpoint de alteração, neste endpoint vimos que necessário informar o campo status, então vamos criar um record específico para este endpoint, conforme abaixo:

package com.seuprojeto.integrationtest.integration.app.controller.dto;

public record UpdateOrderDto(String description, String status) {
}

Vamos também alterar uma classe já existe, a classe order, adicionando a ela um método que irá atualizar os dados da classe. Adicionaremos o método abaixo:

...
public void update(String description, String status) {
    this.description = description;
    this.status = Status.valueOf(status.toUpperCase());
    this.updatedAt = LocalDateTime.now();
}
...

E então criaremos o método na controller

...
@PutMapping("/{id}")
public OrderCreatedDto updateOrder(@PathVariable String id, @RequestBody UpdateOrderDto updateOrderDto) {
    final UUID uuid = UUID.fromString(id);
    final Order order = this.repository.findById(uuid).orElseThrow();
    order.update(updateOrderDto.description(), updateOrderDto.status());
    final Order orderSaved = this.repository.save(order);
    return OrderCreatedDto.from(orderSaved);
}

Neste teste teremos uma peculiaridade, pois para alterar uma ordem precisamos primeiro, precisamos primeiro saber de uma ordem já existente, pois a uri para atualizar um ordem exige como parâmetro um id, então faremos a chamada do endpoint de criação de ordem e usaremos o retorno deste para fazer a chamada no nosso endpoint PUT.

@Test
void shouldReturn200WhenPutAnExistentOrder() throws Exception {
    final String description = "some description";
    final CreateOrderDto createOrderDto = new CreateOrderDto(description);
    final String payload = objectMapper.writeValueAsString(createOrderDto);

    final MvcResult response = this.mockMvc.perform(MockMvcRequestBuilders.post(ORDER_URL).content(payload).contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andReturn();

    final OrderCreatedDto orderCreatedDto = objectMapper.readValue(response.getResponse().getContentAsString(), OrderCreatedDto.class);

    final String newDescription = "new description";
    final String newStatus = "CLOSED";
    final UpdateOrderDto updateOrderDto = new UpdateOrderDto(newDescription, newStatus);
    final String updatePayload = objectMapper.writeValueAsString(updateOrderDto);

    final MvcResult updateResponse = this.mockMvc.perform(MockMvcRequestBuilders.put(ORDER_URL + "/" + orderCreatedDto.id()).content(updatePayload).contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andReturn();

    final OrderCreatedDto updatedOrderCreatedDto = objectMapper.readValue(updateResponse.getResponse().getContentAsString(), OrderCreatedDto.class);
    Assertions.assertEquals(newDescription, updatedOrderCreatedDto.description());
    Assertions.assertEquals(newStatus, updatedOrderCreatedDto.status());
}

Voltando para o primeiro caso de teste

Embora este teste com certeza esta passando sem erro, voltemos a ele. Este teste faz uma simples validação se é retornado um StatusCode 200, vamos alterar ele já que agora temos de fato nossa aplicação persistindo em banco de dados, então vamos alterar primeiramente o método que retorna a lista de ordens persistida no banco:

@GetMapping
public List<OrderCreatedDto> getAllOrders() {
    return this.repository.findAll().stream()
            .map(OrderCreatedDto::from)
            .toList();
}

E nossa classe de teste iremos alterar assim:

@Test
void shouldReturn200WhenGetAllOrders() throws Exception {
    final MvcResult response = mockMvc.perform(MockMvcRequestBuilders.get(ORDER_URL))
            .andExpect(status().isOk())
            .andReturn();

    Assertions.assertTrue(response.getResponse().getContentAsString().contains("[]"));
}

Executando todos os testes veremos que eles passarão com sucesso.

E ai deve vir a sua cabeça, ao executar todos os testes veremos que método que criação de ordens são escutados antes, no entanto, vimos que testamos um retorno de lista vazia, por que? É importante compreender isso, primeiro lembra-se da annotation DirtiesContext? Bem, ela garante que a cada teste nosso contexto seja reiniciado, assim os dados criados em cada um dos teste são “descartados”, a cada teste o banco que é um banco H2 em memória, é recriado, isso nos garantes isolamentos dos testes, impedindo que um caso de teste influencie outro, causando o que chamamos de flaky test. Essa hipótese pode ser testa simplesmente comentando a linha:

//@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)

E executando os testes novamente. Veja embora isso causa esta falta de isolamento dos teste reiniciar o contexto do Spring consome mais recursos. É uma opção não habilitar esta opção, mas isso nos exigirá algumas configurações adicionais em nossos testes.

Tempo de execução com annotation que reinicia o contexto do Spring

Tempo de execução sem o annotation que reinicia o contexto Spring

Podemos ver que temos um ganho de tempo na execução considerável, em uma suíte de testes extensa, este ganho pode ser considerável, vamos então fazer as configurações necessário e vamos seguir assim para ser mais rápida a nossa execução. Esta é uma decisão que tem alguns tradeoffs, então antes de tomar essa decisão avalie os riscos. Vamos as configurações na nossa classe de testes:

package com.seuprojeto.integrationtest.integration;

...
import com.seuprojeto.integrationtest.infra.OrderRepository;
...
import org.junit.jupiter.api.BeforeEach;
...
import org.springframework.beans.factory.annotation.Autowired;
...

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@AutoConfigureMockMvc
@EnableConfigurationProperties
//@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OrderControllerIntegrationTest {

    @Autowired
    OrderRepository orderRepository;

    ...

    @Autowired
    MockMvc mockMvc;

    @BeforeEach
    void setUp() {
         this.orderRepository.deleteAll();
    }
    ...
}

O que mudamos aqui é o seguinte, injetamos a nossa classe OrderRepository e adicionamos o método setup. O método setup possui a annotation @BeforeEach, isso irá fazer com que o conteúdo dele seja executado sempre antes de executar um novo caso de teste. Dentro dele chamamos um método que remove todos os registros da tabela, assim evitando que nosso casos de teste tenham implicações uns sobre os outros (ao menos neste caso).

Quarto teste

Vamos testar o endpoint capaz de retornar uma única ordem com base em seu id. Este será um teste mais fácil visto que não teremos nada de novo para criar aqui para que o teste funcione. Vejamos como fica o método que retorna a ordem de serviço na controller:

@GetMapping("/{id}")
public OrderCreatedDto getOrder(@PathVariable String id) {
    final UUID uuid = UUID.fromString(id);
    final Order order = this.repository.findById(uuid).orElseThrow();
    return OrderCreatedDto.from(order);
}

E o teste será implementado assim:

@Test
void shouldReturn200WhenGetAnExistentOrder() throws Exception {
    final String description = "some description";
    final CreateOrderDto createOrderDto = new CreateOrderDto(description);
    final String payload = objectMapper.writeValueAsString(createOrderDto);

    final MvcResult response = this.mockMvc.perform(MockMvcRequestBuilders.post(ORDER_URL).content(payload).contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andReturn();

    final OrderCreatedDto orderCreatedDto = objectMapper.readValue(response.getResponse().getContentAsString(), OrderCreatedDto.class);

    final MvcResult getResponse = this.mockMvc.perform(MockMvcRequestBuilders.get(ORDER_URL + "/" + orderCreatedDto.id()))
            .andExpect(status().isOk())
            .andReturn();

    final OrderCreatedDto getOrderCreatedDto = objectMapper.readValue(getResponse.getResponse().getContentAsString(), OrderCreatedDto.class);
    Assertions.assertEquals(orderCreatedDto.id(), getOrderCreatedDto.id());
    Assertions.assertEquals(orderCreatedDto.description(), getOrderCreatedDto.description());
    Assertions.assertEquals(orderCreatedDto.status(), getOrderCreatedDto.status());
}

Note que mais uma vez usamos a estratégia de adicionar um item através do método de criação e depois consulta-lo. É possível fazer essa inserção de dados diretamente no banco, já que o repository foi injetado em nossa classe de teste, particularmente acredito que isso é manipular diretamente os dados e fugiria o objetivo deste teste que é fazer testar somente através da interface que a aplicação irá exposta.

Quinto teste

Este é o teste de irá remover um registro do banco de dados, vamos ao método da controller:

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void deleteOrder(@PathVariable String id) {
    final UUID uuid = UUID.fromString(id);
    this.repository.deleteById(uuid);
}

Nosso caso de teste:

@Test
void shouldReturn204WhenDeleteAnExistentOrder() throws Exception {
    final String description = "some description";
    final CreateOrderDto createOrderDto = new CreateOrderDto(description);
    final String payload = objectMapper.writeValueAsString(createOrderDto);

    final MvcResult response = this.mockMvc.perform(MockMvcRequestBuilders.post(ORDER_URL).content(payload).contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isCreated())
            .andReturn();

    final OrderCreatedDto orderCreatedDto = objectMapper.readValue(response.getResponse().getContentAsString(), OrderCreatedDto.class);

    this.mockMvc.perform(MockMvcRequestBuilders.delete(ORDER_URL + "/" + orderCreatedDto.id()))
            .andExpect(status().isNoContent());

}

Mais uma vez chamamos o método que cria uma ordem e somente depois executamos o método que irá excluir/deletar o registro.

Veremos que este caso de teste passa sem problema, aqui basicamente fechamos todos o métodos do nosso CRUD. Mas vamos pensar no seguinte cenário, para este último caso, embora ele tenho funcionado corretamente podemos fazer uma validação adicional, pense que se a ordem foi removida, então significa que que se eu fizer aquele GET pelo id eu deveria ter um retorno 404. A implementação ficaria algo assim, este código adicionado ao fim do mesmo caso de teste:

@Test
void shouldReturn204WhenDeleteAnExistentOrder() throws Exception {
    ...

    this.mockMvc.perform(MockMvcRequestBuilders.get(ORDER_URL + "/" + orderCreatedDto.id()))
            .andExpect(status().isNotFound())
            .andReturn();
}

Porém ao executar o teste novamente com esta nova parte implementação teste deixará de passar, pois não fizemos nenhuma implementação que nos retorne o StatusCode 404. Na verdade é retornada uma exceção. Bem é isso que implementamos no método de consulta:

Se lembramos na nossa proposta de implementação este mesmo método 404 é pedido também em outros métodos no próprio DELETE e no PUT também. Então vamos aplicar uma solução que possa ser aplicada em todas as situações.

Para isso iremos gerar uma exception personalizada, que será usada sempre que eu tiver essa situação de ordem não encontrada. Na package com/seuprojeto/integration/domain iremos criar a seguinte classe:

package com.seuprojeto.integrationtest.domain;

public class OrderNotFoundException extends RuntimeException {
    public OrderNotFoundException(String id) {
        super("Order not found with id: " + id);
    }
}

E agora vamos refatorar nosso método GET para gerar esse nossa exception:

@GetMapping("/{id}")
public OrderCreatedDto getOrder(@PathVariable String id) {
    final UUID uuid = UUID.fromString(id);
    final Order order = this.repository.findById(uuid).orElseThrow(() -> new OrderNotFoundException(id));
    return OrderCreatedDto.from(order);
}

Legal, mas isso não irá resolver todos os nosso problemas, só mudamos o sabor do nosso erro. Agora iremos fazer o nossa aplicação interpretar que toda vez que essa exceção for gerada, nós iremos captura-la e gerar uma saída personalizada com o formato que desejamos. Para isso iremos criar uma nova classe para gerar essa configuração. Criaremos uma nova classe em com/seuprojeto/integration/app:

package com.seuprojeto.integrationtest.app.controller;

import com.seuprojeto.integrationtest.domain.OrderNotFoundException;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.util.Map;

@RestControllerAdvice
public class HandlerException {

    @ExceptionHandler(OrderNotFoundException.class)
    @ResponseStatus(code = HttpStatus.NOT_FOUND)
    public Map<String, String> handleOrderNotFoundException(OrderNotFoundException e) {
        return Map.of("message", e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    @ResponseStatus(code = HttpStatus.INTERNAL_SERVER_ERROR)
    public Map<String, String> handleException(Exception e) {
        System.out.println(e.getMessage());
        return Map.of("message", "Internal server error");
    }
}

Esta classe irá capturar nossas exceções, vamos começar falando do método:

public Map<String, String> handleException(Exception e)

Este método irá fazer com o nosso framework capture quando uma exceção é gerada. Especificamente este método irá capturar qualquer exceção que ocorra e olhando mais atentamente vemos que irá retornar uma mensagem padrão com o seguinte formato:

{
  "message": "Internal server error"
}

Aqui teremos um StatusCode 500. É uma boa prática este método pois isso evita que toda a stack da exception seja retornada ao usuário final que fez seja lá chamada para nosso aplicação, evitando expor detalhes técnicos da aplicação. Veja que antes do retorno “logamos”(Não necessariamente o estado da arte de logs de aplicação, certo?) a mensagem de erro original para facilitar possíveis investigações posteriores.

Porém este método é bastante genérico e não trata diretamente da nosso necessidade que é tratar nossa exceção personalizada OrderNotFoundException, por isso criamos um método específico para capturar e tratar nossa exception:

public Map<String, String> handleOrderNotFoundException(OrderNotFoundException e)

Note que este método em sim tem uma annotation que define o StatusCode 404 (not found). Uma vez implementada nossa classe podemos chamar novamente nosso caso de teste que agora irá funcionar com total sucesso.

Sexto teste

Tendo em vista a implementação anterior sobre o retorno do 404 quando uma ordem não é encontrada, vamos implementar uma caso de teste para isso chamando o nosso GET com o id de uma ordem não existente.


@Test
void shouldReturn404WhenGetAnNonExistentOrder() throws Exception {
    this.mockMvc.perform(MockMvcRequestBuilders.get(ORDER_URL + "/123"))
            .andExpect(status().isNotFound())
            .andReturn();
}

Se simplesmente implementarmos o caso de teste acima e executa-lo, teremos um StatusCode 500, vamos refatorar o método em busca do nosso código 404. Mas por que este erro, se método na prática já foi refatorado e vimos anteriormente que ele funcionou corretamente, retornando 404?

Bem nosso método espera que seja informado um valor UUID válido para o id, como o valor informado é foi 123, ele não pode ser convertido em um UUID válido, gerando um exception do tipo java.lang.IllegalArgumentException. Poderíamos adicionar um tratativa para este tipo de exception no nosso handler de erro, mas está é uma classe que pode ser gerada em vários pontos da aplicação por outros motivos, trata-la de forma a retornar um 404, pode gerar uma informação de retorno imprecisa para um cliente da aplicação em alguns momentos, então vamos abordar de outra forma.

Veja a decisão tomada aqui visa não expor ao cliente muitos detalhes sobre a nossa aplicação e tenta manter de forma coerente a abordagem da nossa aplicação, outras decisões técnicas aqui pode ser adotadas, isso vai variar do seu negócio. Em nossa solução iremos criar um método na nosso controller:

package com.seuprojeto.integrationtest.app.controller;

...
import java.util.UUID;

@RestController
@RequestMapping("/orders")
public class OrderController {
   ...

    @GetMapping("/{id}")
    public OrderCreatedDto getOrder(@PathVariable String id) {
        final UUID uuid = getUuid(id);
        final Order order = this.repository.findById(uuid).orElseThrow(() -> new OrderNotFoundException(id));
        return OrderCreatedDto.from(order);
    }
  ...
    private static UUID getUuid(String id) {
        try {
            return UUID.fromString(id);
        } catch (IllegalArgumentException e) {
            throw new OrderNotFoundException(id);
        }
    }
}

Veja que teremos o método getUuid e este método irá encapsular a conversão da nosso String recebida em um UUID válido, nosso contexto, desta classe especificamente, podemos considerar que toda vez que um id não puder ser convertido com sucesso isso implica que esta ordem não existirá, já que estabelecemos que nossas ordem serão sempre gravadas com o formato UUID, assim podemos “tranquilamente” retornar nossa exception personalizada OrderNotFoundException, que fatalmente irá implicar no retorno de um StatusCode 404, o que nos leva ao sucesso do nosso sexto caso de teste.

Não se esqueça de refatorar os demais métodos da controller que também faziam conversão do UUID, assim garantimos o mesmo funcionamento a todos.

Colocando o projeto para rodar

Note que até o momento toda aplicação foi construída sem ela de fato seja colocada em execução “nenhuma vez”(Na verdade toda vez que executamos o testes a aplicação de fato é executado, mas dentro de container controlado). Chegou a hora de colocar a aplicação em execução de fato e ver se toda nossa tentativa de criar uma aplicação com base primeiramente em testes funcionou.

Para isso vale lembra que inicialmente dissemos que nosso banco de dados de fato seria o Postgres, então vamos começar colocado ele para executar. Aqui faça como preferir, eu usarei o docker, e um arquio docker-compose para iniciar uma instancia localmente, vou compartilhar o arquivo, mas não vou entrar em detalhes sobre este passo. Basicamente criei uma nova pasta docker na raiz do projeto e dentro dela criei o arquivo:

version: '3'

services:
  postgres:
    image: postgres:14
    container_name: postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres

Para quem conhece basta entrar no seu console favorito, navegar até a pasta e digitar o comando (Claro, você precisa do docker instalado na sua maquina):

docker compose up

Após digitar o comando ele deverá subir uma instancia de postgres na sua maquina com sucesso:

Agora precisamos apontar nosso aplicação para conectar com o banco postgres, tal como fizemos com o ambiente de teste. Para isso dentro da pasta resource iremos encontrar um arquivo application.properties, somente por gosto pessoal iremos renomeá-lo para application.yaml (basicamente, o yaml é mesmos, verbosos e não precisamos repetir algumas coisas vária vezes). Uma vez renomeado iremos substituir conteúdo dele pelo seguinte:

spring:
  application:
  name: integration-test
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://localhost:5432/postgres?currentSchema=public
    username: postgres
    password: postgres
  jpa:
    ddl-auto: update
    show-sql: true

Com isso agora podemos rodar nossa aplicação, aqui vamos usar a facilidade do Intellij, indo ao até classe IntegrationtestApplication e clicando no botão:

Pronto agora pode fazer um curl no console e ver que a aplicação funcionou com sucesso:

Os fontes para o projeto completo está disponível no Github

https://github.com/marcosfaneli/integrationtest