Escrito por: Sameer Shukla

TestContainers é uma biblioteca que ajuda você a executar contêineres Docker específicos do módulo para simplificar o teste de integração.

Esses contêineres do Docker são leves e, uma vez que os testes são concluídos, os contêineres são destruídos.

Neste artigo, vamos entender o que é o TestContainers e como ele ajuda você a escrever testes mais confiáveis.

Também vamos entender os componentes importantes (anotações e métodos) da biblioteca que ajudam você a escrever os testes.

Finalmente, aprenderemos a escrever um teste de integração adequado no SpringBoot usando a biblioteca TestContainers e seus componentes.

Limitações do teste com um banco de dados H2 na memória

A abordagem mais comum para o teste de integração hoje é usar um banco de dados H2 na memória. Existem, no entanto, certas limitações para esse método.

Em primeiro lugar, digamos que estamos usando a versão 8.0 do MySQL em produção, mas que nossos testes de integração estão usando H2. Nunca poderemos executar nossos testes para a versão do banco de dados em execução em produção.

‌Em segundo lugar, os casos de teste são menos confiáveis porque, em produção, estamos usando um banco de dados totalmente diferente – e os testes estão apontando para o H2. A aplicação pode ter problemas em produção, mas os testes de integração podem ser bem-sucedidos.

Eu estava tentando acessar meu serviço RESTful localmente e me deparei com este erro:

"Caused by: org.postgresql.util.PSQLException: FATAL: database "example_db" does not exist".

Ele aconteceu por causa de um problema de permissão, mas os testes locais funcionaram bem.

Por fim, conforme documentado aqui, na seção Compatibility (documentação em inglês), o H2 é compatível com outros bancos de dados apenas até certo ponto. Existem algumas áreas onde o H2 é incompatível. Se você precisar usar "nativeQueries" em uma aplicação do SpringBoot, por exemplo, usar o H2 pode causar problemas.

Apresentando a biblioteca TestContainers

Ao usar TestContainers, podemos superar as limitações do H2.

• Os testes de integração apontarão para a mesma versão do banco de dados que está em produção. Assim, podemos vincular nossa imagem de banco de dados do TestContainer à mesma versão em execução na produção.
• Os testes de integração são muito mais confiáveis porque a aplicação e os testes estarão usando o mesmo tipo e versão de banco de dados, não havendo problemas de compatibilidade, portanto, nos casos de teste.

O que são os TestContainers?

A biblioteca TestContainers é uma API wrapper sobre o Docker. Quando escrevemos código para criar um contêiner nos bastidores, ele pode ser traduzido para algum comando do Docker como, por exemplo‌:

Este código pode ser traduzido para algo como o seguinte:

docker run -d --env MYSQL_DATABASE=example_db --env MYSQL_USER=test --env MYSQL_PASSWORD=test ‘mysql:latest’ 

O TestContainers tem um nome de método "withCommand". Você o usa para definir o comando que deve ser executado dentro do contêiner do Docker, o que confirma que o TestContainers é uma API wrapper sobre o Docker.

O TestContainers baixa as imagens MySQL, Postgres, Kafka, Redis e as executa em um contêiner. O MySQLContainer executará um banco de dados do MySQL em um contêiner e os casos de teste podem se conectar a ele na máquina local. Uma vez que a execução termina, o banco de dados desaparecerá – ele simplesmente é excluído da máquina. Nos casos de teste, podemos iniciar quantas imagens de contêiner quisermos.

O TestContainers suporta JUnit 4, JUnit 5 e Spock. Se você for ao site TestContainers.org, basta visitar a seção QuickStart que explica como usá-lo:

O TestContainers tem suporte a quase todos os bancos de dados, do MySQL e Postgres ao CockroachDB. Você pode encontrar mais informações sobre isso no site TestContainers.org, na seção Modules:‌

‌O TestContainers também suporta módulos de nuvem como o módulo da GCloud e o módulo do Azure. Se sua aplicação estiver sendo executada no Google Cloud, o TestContainers terá suporte para Cloud Spanner, Firestore, Datastore e assim por diante.‌

Até agora, no artigo, falamos apenas sobre bancos de dados, mas o TestContainers suporta vários outros componentes, como Kafka, SOLR, Redis e muito mais.

Como usar a biblioteca TestContainers

Neste artigo, vamos explorar o TestContainers com o JUnit 5. Para implementar o TestContainers, precisamos entender algumas anotações, métodos e bibliotecas importantes do TestContainers que precisamos implementar em nosso projeto.

Anotações em TestContainers

Duas anotações importantes são necessárias em nossos testes para que o TestContainers funcione: @TestContainers e @Container.

@TestContainer é uma extensão do JUnit-Jupiter que inicia e interrompe automaticamente os contêineres usados nos testes. Essa anotação encontra os campos que são marcados com @Container e chama os métodos específicos do ciclo de vida do contêiner. Aqui, os métodos do ciclo de vida do MySQLContainer serão invocados.‌

O MySQLContainer é declarado como estático, pois, se declararmos o contêiner como estático, um único contêiner será iniciado e será compartilhado entre todos os métodos de teste.

Se for uma variável de instância, um contêiner será criado para cada método de teste.

Métodos da biblioteca TestContainers

Existem alguns métodos importantes na biblioteca TestContainers que você usará nos testes. É bom conhecê-los antes de usar a biblioteca.

• withInitScript: usando 'withInitScript', podemos executar o .SQL para definir o esquema, tabelas e também adicionar os dados ao banco de dados. Resumindo, esse método é usado para executar o .SQL para popular o banco de dados.
• withReuse (true): usando o método 'withReuse', podemos habilitar a reutilização de contêineres. Esse método funciona bem em conjunto com a habilitação da propriedade "testcontainers.reuse.enable:true" no arquivo ".testcontainers.properties".
• start: usamos isso para iniciar o contêiner.
• withClasspathResourceMapping: usamos para mapear um recurso (arquivo ou diretório) no classpath para um caminho dentro do contêiner. Isso só funcionará se você estiver executando seus testes fora de um contêiner do Docker.
• withCommand: define o comando que deve ser executado dentro do contêiner do Docker.
• withExposedPorts: usado para definir a porta na qual o contêiner escuta.
• withFileSystemBind: usado para mapear um arquivo/diretório do sistema de arquivos local para o contêiner.

Caso de uso do TestContainers

No exemplo que veremos agora, a aplicação se comunicará apenas com o banco de dados e escreverá os testes de integração para ele usando o TestContainers. Em seguida, estenderemos o caso de uso implementando o Redis no meio.

Se os dados existirem no cache do Redis, eles serão retornados; caso contrário, ele mergulhará no banco de dados para salvar e recuperar com base na chave.

O serviço é simples. Ele tem 2 endpoints – o primeiro é para criar um usuário e o segundo é para encontrar um usuário por e-mail. Se o usuário for encontrado, ele será retornado; caso contrário, obteremos um 404. O código da classe de serviço tem esta aparência:‌

Vamos escrever os testes para essa classe. Você pode encontrar toda a base de código aqui:‌

A classe de teste é marcada com a anotação @TestContainers, que inicia/para o contêiner. Usamos a anotação @Container para chamar os métodos específicos do ciclo de vida do contêiner.

Além disso, o "MySQLContainer" é declarado como estático porque, então, um único contêiner é iniciado. Em seguida, ele é compartilhado entre todos os métodos de teste (já discutimos a importância dessas anotações).

Em seguida, precisamos escrever um método de configuração marcado com @BeforeAll, onde habilitamos o método "withReuse". Isso nos ajuda a reutilizar os contêineres existentes. Estamos usando o método "withInitScript" para executar o arquivo ".sql" e, em seguida, iniciar o contêiner.‌

‌@DynamicPropertySource nos ajuda a sobrescrever as propriedades declaradas no arquivo properties. Escrevemos esse método para permitir que o TestContainers crie o URL, o nome de usuário e a senha por conta própria – caso contrário, podemos enfrentar erros.

Por exemplo, ao remover o nome de usuário e a senha, podemos enfrentar um erro 'Access denied' (acesso negado, em português), que pode nos confundir. Portanto, é melhor permitir que o TestContainer atribua essas propriedades dinamicamente por conta própria.

É isso – estamos prontos para executar os casos de teste:

Execute @AfterAll para parar o contêiner. Caso contrário, ele poderá continuar sendo executado em sua máquina local se você não o parar explicitamente.‌

Como usar o GenericContainer

‌‌GenericContainer é o contêiner mais flexível. Ele facilita a execução de quaisquer imagens de contêiner dentro do GenericContainer.

Agora que temos o Redis em seu devido lugar, tudo o que precisamos fazer em nosso caso de teste é ativar um GenericContainer com a imagem do Redis.

Em seguida, iniciamos o contêiner genérico do Redis em @BeforeAll e o paramos com o método de desmontagem @AfterAll.

Conclusão

É extremamente fácil usar o TestContainers em nossa aplicação para escrever testes melhores. A curva de aprendizado não é muito íngreme e tem suporte para vários módulos diferentes de uma variedade de bancos de dados, como Kafka, Redis e outros.

Escrever testes usando o TestContainers torna nossos testes muito mais confiáveis. O único lado negativo é que os testes são lentos em comparação aos do H2. Isso ocorre porque o H2 está na memória e o TestContainers leva tempo para baixar a imagem, executar o contêiner e executar toda a configuração que discutimos neste artigo.

Escrito por: Clark Jason Ngo

Instalar o VSCode

Configuração aqui: Configurando o Visual Studio Code

Instalar e criar um projeto do Maven

Guia de instalação completo aqui: Maven – Maven em 5 minutos (em inglês)

Se você tem o Maven instalado, siga estas etapas:

Gerar o projeto

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Mudar para o diretório do projeto

cd my-app

Construir o projeto

mvn package

Testar e compilar o projeto

java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App

Você deve obter uma saída com: Hello World!

Modificar nosso projeto

Vamos começar criando funções matemáticas simples

Procure o arquivo App.java e substitua o conteúdo por este código:

package com.mycompany.app;

public class App 
{
  public static int add(int firstNumber, int secondNumber) {
    return firstNumber + secondNumber;
  }

  public static int multiply(int multiplicand, int multiplier) {
    return multiplicand * multiplier;
  }

  public static int divide(int dividend, int divisor) {
    if (divisor == 0)
      throw new IllegalArgumentException("Cannot divide by zero (0)."); // Não pode dividir por zero (0).

    return dividend / divisor;
  }
  public static void main( String[] args )
  {
    System.out.println(App.add(3, 3)); 
  }
}

Procure por AppTest.java e substitua o conteúdo por este código:

package com.mycompany.app;

import static org.junit.Assert.assertTrue;

import org.junit.Assert;
import org.junit.Test;

/**
* Teste unitário para App simples. 
*/ 
public class AppTest 
{
    /**
    *Teste Rigoroso :-)
    */
    @Test
    public void shouldAnswerWithTrue() // deveResponderComVerdadeiro
    {
        assertTrue( true );
    }
    @Test
    public void add_TwoPlusTwo_ReturnsFour() { // adicionar_DoisMaisDois_RetornaQuatro
      // Organizar
      final int expected = 4;

      // Agir
      final int actual = App.add(2, 2);

      // Afirmar
      Assert.assertEquals(expected, actual);
    }    
    @Test
    public void multiply_FourTimesTwo_ReturnsEight() { // multiplicar_QuatroVezesDois_RetornaOito
      // Organizar
      final int expected = 8;

      // Agir
      final int actual = App.multiply(4, 2);

      // Afirmar
      Assert.assertEquals(expected, actual);
    }        

    @Test
    public void divide_TenDividedTwo_ReturnsFive() { // dividir_DezDivididoPorDois_RetornaCinco
      // Organizar
      final int expected = 5;

      // Agir
      final int actual = App.divide(10, 2);

      // Afirmar
      Assert.assertEquals(expected, actual);
    }           
}

Você pode continuar criando testes como, por exemplo:

@Test    
public void multiply_FiftyTimesTwo_ReturnsOneHundred()  // multiplicar_CinquentaVezesDois_RetornaCem
{      
  // // Organizar
  final int expected = 100;        
  // // Agir
  final int actual = App.multiply(50, 2);        
  // // Afirmar
  Assert.assertEquals(actual, expected);    
}

Construir o projeto

mvn package

Saída:

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.mycompany.app.AppTest
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.026 s - in com.mycompany.app.AppTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0

Testar e compilar o projeto

java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App

Saída:

6
Hello World!

Uma maneira alternativa de executar os testes é clicar em Run Test dentro de AppTest.java

No exemplo abaixo, Run Test está localizado logo abaixo da linha de código 44.

Visualizar testes e relatório de teste

Migrando do JUnit 4 para o JUnit 5

Altere as dependências do seu pom.xml para:

  <dependencies>
      <dependency>
          <groupId>org.junit.jupiter</groupId>
          <artifactId>junit-jupiter-api</artifactId>
          <version>5.4.2</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.junit.jupiter</groupId>
          <artifactId>junit-jupiter-engine</artifactId>
          <version>5.4.2</version>
          <scope>test</scope>
      </dependency>
  </dependencies>

Altere seu AppTest.java para:

package com.mycompany.app;

import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.Assertions.assertEquals;

import org.junit.jupiter.api.Test;

/** 
* Teste unitário para App simples. 
*/
public class AppTest 
{
    /**
    * Teste Rigoroso :-)
    */ 
    @Test
    public void shouldAnswerWithTrue() // deveResponderComVerdadeiro
    {
        assertTrue( true );
    }
    @Test
    public void add_TwoPlusTwo_ReturnsFour() { // adicionar_DoisMaisDois_RetornaQuatro
      // Organizar
      final int expected = 4;

      // Agir
      final int actual = App.add(2, 2);

      // Afirmar
      assertEquals(expected, actual);
    }    
    @Test
    public void multiply_FourTimesTwo_ReturnsEight() { // multiplicar_QuatroVezesDois_RetornaOito
      // Organizar
      final int expected = 8;

      // Agir
      final int actual = App.multiply(4, 2);

      // Afirmar
      assertEquals(expected, actual);
    }        

    @Test
    public void divide_TenDividedTwo_ReturnsFive() { // dividir_DezDivididoPorDois_RetornaCinco
      // Organizar
      final int expected = 5;

      // Agir
      final int actual = App.divide(10, 2);

      // Afirmar
      assertEquals(expected, actual);
    }           
}

Adicionando cobertura de teste

Verifique o relatório de cobertura de teste

No VSCode, abra o Extension MarketPlace e pesquise Coverage Gutters

Clique no botão Instalar (ou Install)

Abra o arquivo pom.xml na sua pasta raiz e substitua o conteúdo pelo pom.xml no GitHub para adicionar suporte a um plug-in.

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>my-app</name>
  <!-- IMPORTANTE troque este endereço pelo do site do projeto -->
  <url>http://www.exemplo.com</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.4.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>5.4.2</version>
        <scope>test</scope>
    </dependency>
  </dependencies>


  <build>
    <pluginManagement><!-- faça o lockdown das versões dos plug-ins para evitar o uso dos padrões do Maven (pode ser movido para o pom pai) -->
      <plugins>
        <plugin>
          <groupId>org.jacoco</groupId>
          <artifactId>jacoco-maven-plugin</artifactId>
          <version>0.8.2</version>
          <executions>
              <execution>
                  <goals>
                      <goal>prepare-agent</goal>
                  </goals>
              </execution>
              <execution>
                  <id>report</id>
                  <phase>prepare-package</phase>
                  <goals>
                      <goal>report</goal>
                  </goals>
              </execution>
          </executions>
        </plugin>
        <!-- Ciclo de vida limpo; consulte https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle (em inglês) -->
        <plugin>
          <artifactId>maven-clean-plugin</artifactId>
          <version>3.1.0</version>
        </plugin>
        <!-- Ciclo de vida padrão, empacotamento em jar; consulte https://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_jar_packaging (em inglês) -->
        <plugin>
          <artifactId>maven-resources-plugin</artifactId>
          <version>3.0.2</version>
        </plugin>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.8.0</version>
        </plugin>
        <plugin>
          <artifactId>maven-surefire-plugin</artifactId>
          <version>2.22.1</version>
        </plugin>
        <plugin>
          <artifactId>maven-jar-plugin</artifactId>
          <version>3.0.2</version>
        </plugin>
        <plugin>
          <artifactId>maven-install-plugin</artifactId>
          <version>2.5.2</version>
        </plugin>
        <plugin>
          <artifactId>maven-deploy-plugin</artifactId>
          <version>2.8.2</version>
        </plugin>
        <!-- Ciclo de vida do site; consulte https://maven.apache.org/ref/current/maven-core/lifecycles.html#site_Lifecycle (em inglês) -->
        <plugin>
          <artifactId>maven-site-plugin</artifactId>
          <version>3.7.1</version>
        </plugin>
        <plugin>
          <artifactId>maven-project-info-reports-plugin</artifactId>
          <version>3.0.0</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Abra o terminal no VSCode e execute

mvn install
mvn clean jacoco:prepare-agent install jacoco:report

Abra seu arquivo App.java na pasta main/java/com/mycompany/app e clique no botão Watch para verificar o relatório

Barra vermelha: código de teste não coberto

Barra amarela: condição não coberta

Barra verde: código coberto

Abra o arquivo index.html na sua pasta root/target/site/jacoco.

Para abrir:

Eme seguida, cole (Ctrl + V para Windows e Command + V para MacOS) o caminho no seu navegador.

Você pode ver um relatório de cobertura de teste muito detalhado:

Obrigado pela leitura! 😉