Quarkus Dev Services e Testes

Verifique primeiro a versão do Quarkus do projeto. O uso do Testcontainers, independente de framework, pode usar a habilidade opcional java-testcontainers se instalada (caso contrário, veja https://java.testcontainers.org/); esta habilidade cobre apenas recursos específicos do Quarkus.

Dev Services

Nos modos de desenvolvimento e teste, o Quarkus inicia contêineres (PostgreSQL, MySQL, Kafka, Redis, Keycloak, ...) automaticamente quando a extensão relacionada está presente e nenhuma conexão está configurada (Docker ou Podman necessário).

# Global switch
quarkus.devservices.enabled=true
%dev.quarkus.datasource.devservices.image-name=postgres:17
# Reuse container across restarts (also requires testcontainers.reuse.enable=true in ~/.testcontainers.properties)
quarkus.datasource.devservices.reuse=true
# Fixed port (optional)
quarkus.datasource.devservices.port=5432
# Share between apps in dev mode
quarkus.kafka.devservices.shared=true

Desabilite um com quarkus.<ext>.devservices.enabled=false; configurar uma URL/host explicitamente também o desabilita. O Dev UI (/q/dev-ui) lista os serviços em execução.

Testes

@QuarkusTest
class GreetingResourceTest {
    @Test
    void hello() {
        given().when().get("/hello").then().statusCode(200).body(is("Hello"));
    }
}

Dependências, escopo de teste: io.quarkus:quarkus-junit (3.31+, o que o template 3.40 gera) ou quarkus-junit5 (template 3.27; ainda publicado e resolúvel em 3.40) e io.rest-assured:rest-assured. Mantenha o que o projeto já usa.

• Injete beans em testes com @Inject; simule beans CDI com io.quarkus.test.InjectMock (quarkus-junit-mockito, anteriormente quarkus-junit5-mockito; simulação verificada de um bean PanacheRepository em 3.40.1).
• Segurança: @TestSecurity(user="alice", roles="admin") (quarkus-test-security).
• Perfis: @TestProfile(MyProfile.class) com QuarkusTestProfile#getConfigOverrides(); reinicia o aplicativo, então use com moderação.
• Transações: @TestTransaction reverte após o teste.
• @QuarkusIntegrationTest executa contra o artefato empacotado (jar, binário nativo ou contêiner); você não pode injetar beans lá, apenas chamá-lo via HTTP.

Recursos de Teste

public class WireMockResource implements QuarkusTestResourceLifecycleManager {
    public Map<String,String> start() { /* start, return config overrides */ return Map.of(); }
    public void stop() { }
}

@QuarkusTest
@WithTestResource(WireMockResource.class)   // io.quarkus.test.common.WithTestResource
class MyTest { }

@WithTestResource (verificado em 3.40.1) aplica-se à classe de teste anotada; o Quarkus reinicia o aplicativo quando o conjunto de recursos muda. O antigo @QuarkusTestResource ainda compila e executa em 3.40.1, mas se aplica globalmente a todos os testes, a menos que restrictToAnnotatedClass = true. Não coloque pontos de injeção @ConfigProperty para valores fornecidos por recursos em uma classe de teste: as classes de teste são escaneadas como beans, e o aplicativo falha ao iniciar para outras classes de teste que não possuem o recurso. Prefira Dev Services em vez de recursos personalizados quando uma extensão o suportar.

Executando

./mvnw test                 # unit/@QuarkusTest
./mvnw verify -DskipITs=false  # also runs *IT via maven-failsafe-plugin

Atenção: classes *IT (@QuarkusIntegrationTest) são executadas pelo Failsafe na fase verify, e precisam do objetivo quarkus-maven-plugin build e da configuração do failsafe (com propriedades do sistema java.util.logging.manager e maven.home) geradas pelo template do projeto. ./mvnw test as ignora silenciosamente, e os templates 3.27 e 3.40 também definem <skipITs>true</skipITs>, então um simples ./mvnw verify também as ignora (verificado): passe -DskipITs=false (ou -Dnative, cujo perfil o ativa). Com -Dnative e uma construção de contêiner no macOS ou Windows, o binário é um ELF Linux e o IT falha com Exit code is: '126'; use uma construção local do Mandrel/GraalVM para esses casos.

Testes contínuos: execute ./mvnw quarkus:dev e pressione r para iniciar ou reexecutar testes e p para pausá-los (h lista os atalhos); uma vez em execução, os testes são reexecutados em mudanças de código (quarkus.test.continuous-testing=enabled|paused|disabled).

Verificado no Quarkus 3.40.1 (JDK 26, Docker Desktop): @QuarkusTest com Dev Services PostgreSQL (postgres:18 por padrão), @TestTransaction, @TestProfile, @TestSecurity, @InjectMock, *IT via Failsafe. @QuarkusTest e Dev Services em 3.27.6 também.

Checklist

• Use Dev Services antes de escrever um recurso personalizado.

…