Pular para o conteúdo

Testes de integração com WebApplicationFactory e Testcontainers em ambientes event-driven

Testes de integração com WebApplicationFactory e Testcontainers são fundamentais para sistemas event-driven, garantindo que fluxos de eventos e integrações assíncronas funcionem corretamente, evitando falhas de comunicação e possibilitando rollback seguro nas atualizações.

7 min de leitura
Setup de testes de integração usando WebApplicationFactory e Testcontainers para validar fluxos de eventos em sistemas event-driven.

Neste artigo aprofundo um ponto tratado no post sobre migração gradual de monólitos para microsserviços usando Event-Driven Architecture, destacando o papel dos testes de integração robustos com WebApplicationFactory e Testcontainers https://blog.felipemarcianodev.com/estrategias-para-migracao-gradual-de-monolitos-para-microsservicos-usando-event-driven-architecture.

Quando lidamos com sistemas baseados em eventos e integração assíncrona, o desafio não é somente garantir que o código compila ou que as unidades funcionam isoladamente, mas sim assegurar que o conjunto desde a publicação do evento até a reação do consumidor se comporte conforme o esperado. Por isso, ao testar fluxos baseados em eventos, é comum considerar alguns critérios essenciais:

  1. Cobertura realista da infraestrutura utilizada, incluindo banco e filas ou mecanismos de mensagens.
  2. Validação da comunicação assíncrona e o comportamento diante de falhas.
  3. Facilidade de automação e integração no pipeline de CI/CD.
  4. Garantia de isolamento para evitar interferência entre testes.
  5. Possibilidade de simular rollback e recovery em caso de falhas.

Com esses critérios, vamos comparar as duas opções que uso no backend .NET em sistemas como o sistema de gestão de comércio exterior, Planuz e LeadsMap: o uso do WebApplicationFactory e o uso do Testcontainers.

WebApplicationFactory para testes end-to-end da API

WebApplicationFactory é uma classe fornecida pela Microsoft para facilitar o teste de integração da API ASP.NET Core inteira, instanciando a aplicação com seu pipeline de requisição, controladores e middlewares. Ela permite testar a aplicação em memória, simulando as chamadas HTTP reais, o que valida toda a cadeia de processamento HTTP, filtros, autenticação, autorização e execução dos handlers.

O que cobrar dessa abordagem

  • É preciso configurar os serviços para usar bancos em container ou memoria e, no nosso caso, autenticação em TestAuthHandler para substituir o Keycloak.
  • Testa as rotas e endpoints, passando os tokens JWT válidos com claims multi-tenant.
  • Permite verificar autorização por perfil, isolamento entre tenants e integridade dos dados.
  • Cobre o comportamento integrando com jobs e handlers assíncronos presentes na API.
  • Boa para garantir, por meio de cobertura abrangente de endpoints e cenários críticos, que o contrato interno da API e seu ciclo principal de operação estejam funcionando no todo.

Limitações relevantes

  • Sozinha, não dispõe de ambiente externo, por isso banco, filas e serviços integrados devem ser provisionados à parte.
  • Para testes envolvendo eventos assíncronos, a devida provisão e controle do ambiente que processa eventos deve ser externo e orquestrado pelo teste.
  • Pode ser custosa se usada com muitos testes detalhados, exige bom setup para reaproveitamento de host e contexto.

Testcontainers para prover bancos e recursos externos reais

Testcontainers é biblioteca que permite aos testes iniciarem containers Docker de serviços dependentes, como bancos PostgreSQL, MongoDB, e no contexto event-driven, brokers de mensagem (ex.: RabbitMQ, embora nos meus sistemas de comércio exterior ele fique provisionado, não ativo). Ela promove testes com ambiente o mais próximo da produção em containers descartáveis.

O que cobrar dessa abordagem

  • Precisa de Docker instalado e uma infraestrutura capaz de rodar containers rapidamente.
  • Permite controlar o ciclo de vida do banco real por container isolado para cada teste, garantindo dados limpos.
  • É indispensável para testes de integrações que envolvem troca de mensagens assíncronas e validação de efeitos de eventos.
  • Facilita o teste de rollback ao proporcionar um ambiente controlado, onde dumps e restores podem ser feitos antes e depois dos testes.
  • Possibilita verificar os efeitos colaterais distribuídos, como a consistência eventual dos dados processados e o comportamento dos mecanismos de retry e dead-letter, por meio da simulação real do ambiente de mensagens e do controle do estado dos containers durante os testes.

Limitações relevantes

  • Demanda mais tempo de execução devido ao boot dos containers e ao manejo de dados no banco.
  • Exige setup cuidadoso de contexto e disposição da infraestrutura de testes.
  • Para projetos menores, pode aumentar demais a complexidade de build ou CI.

Por que usar os dois em conjunto é o caminho que adoto

No meu pipeline, o mais comum é usar o WebApplicationFactory para simular chamadas HTTP reais da API, enquanto o Testcontainers sobe os bancos PostgreSQL e MongoDB (quando aplicável). Essa combinação cobre tanto a superfície HTTP quanto a camada persistente com ambiente real. Com ela, consigo:

  • Testar fluxos de trabalho event-driven que envolvem jobs Quartz.NET que disparam eventos e escrevem no banco;
  • Garantir que a fila de eventos (mesmo que não usando broker externo, mas em jobs ou polling IMAP, por exemplo) não sofreu falhas no tratamento;
  • Simular nos testes cenários que disparam rollback implícito, verificando que migrations que alteram a base mantém a integridade das informações, por exemplo, aplicando migrations no startup e confirmando no teste a consistência dos dados após falhas controladas; assim garante-se que o rollback na lógica do banco funciona corretamente e o estado permanece consistente.
  • Automatizar o gate de deploy com testes que bloqueiam deploys vermelhos;
  • Substituir o Keycloak por TestAuthHandler para liberar testes que cobrem controle de acesso interno mesmo sem ambiente externo.

Segue um exemplo genérico ilustrativo básico (não é o código do sistema):

public class ApiIntegrationTests : IClassFixture<WebApplicationFactory<Api.Startup>>, IAsyncLifetime
{
    private readonly WebApplicationFactory<Api.Startup> _factory;
    private readonly PostgreSqlTestcontainer _pgContainer;
    private HttpClient _client;

    public ApiIntegrationTests(WebApplicationFactory<Api.Startup> factory)
    {
        _factory = factory;
        _pgContainer = new TestcontainersBuilder<PostgreSqlTestcontainer>()
            .WithDatabase(new PostgreSqlTestcontainerConfiguration { Database = "testdb", Username = "postgres", Password = "password" })
            .Build();
    }

    public async Task InitializeAsync()
    {
        await _pgContainer.StartAsync();

        _client = _factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureServices(services =>
            {
                // Replace DbContext with container connection string, replace Auth, etc.
            });
        }).CreateClient();
    }

    public async Task DisposeAsync()
    {
        await _pgContainer.StopAsync();
        _client.Dispose();
    }

    [Fact]
    public async Task EventoDisparadoDeveSerProcessadoComSucesso()
    {
        // Arrange: criar dados ou contexto

        // Act: chamar endpoint que dispara evento
        var response = await _client.PostAsync("/api/eventos", eventPayload);

        // Assert: validar resultado, efeito no banco e estado pós-processamento
        response.EnsureSuccessStatusCode();
        // Consulta banco via contexto ou Dapper para validar mudanças esperadas
    }
}

Quando usar cada uma - e quando a combinação pode pesar

Se você está desenvolvendo ou migrando um sistema modular event-driven em .NET, com integrações pesadas e fluxos assíncronos entre bounded contexts, o uso combinado de WebApplicationFactory + Testcontainers para backend robusto é fundamental para evitar surpresas em produção, validar rollback seguro e cobrir integrações no pipeline CI/CD.

Por outro lado, se o sistema é simples sem dependência de banco real ou mensageria para a lógica dos eventos, ou se a prioridade é velocidade de feedback em dev, usar WebApplicationFactory com SGBD em memória pode bastar. Entretanto, nesse cenário o risco está em não testar integração real, o que pode deixar falhas silenciosas para depois.

Também vale destacar que, para sistemas event-driven com microsserviços separados, testes de contrato seriam outra opção, mas nos nossos monolitos modulares preferimos testes de integração isolados para cobrir toda a operação interna num deploy só. Isso contrasta com testes baseados em contratos para provedores e consumidores desacoplados, estratégia que não uso por não ter deploy independente.

O trade-off deste caminho é o custo em tempo e complexidade: testes com containers podem levar de 15 a 40 minutos para rodar devido ao boot dos containers e ao manejo de dados, demandando infraestrutura e planejamento para execução em paralelo ou no agente CI, evitando assim bloqueios na produtividade. O ganho, para mim, é a segurança operacional e a confiança nas integrações event-driven, essencial na migração gradual e na complexidade distribuída dos sistemas sob minha responsa.

Referências

Receba o resumo da semana

Um e-mail por semana com o que foi publicado. Sem spam, e você sai quando quiser.

Perguntas frequentes

Para que serve o WebApplicationFactory nos testes de integração em .NET?

WebApplicationFactory permite testar em memória a API ASP.NET Core inteira, simulando chamadas HTTP reais, validando pipeline, autenticação, autorização e handlers com cobertura dos endpoints e cenários críticos.

Como o Testcontainers ajuda nos testes de integração com componentes externos?

Testcontainers sobe containers Docker reais para bancos e serviços, fornecendo ambiente isolado e controlado para testes que validam a integração assíncrona, rollback, consistência dos dados e mecanismos de retry.

Qual a vantagem de usar WebApplicationFactory junto com Testcontainers no pipeline de CI/CD?

A combinação permite testar a superfície HTTP com WebApplicationFactory e o ambiente persistente real com Testcontainers, garantindo testes robustos de fluxos event-driven, rollback seguro e bloqueio de deploy em falhas.

Quando é desaconselhável usar containers nos testes de integração em sistemas .NET?

Para sistemas simples sem dependência de banco real ou mensageria, ou quando a prioridade é rápida resposta em desenvolvimento, usar containers pode aumentar a complexidade e o tempo dos testes desnecessariamente.

Por que não utilizar teste de contrato em monolitos modulares para arquitetura event-driven?

Nos monolitos modulares com deploy único, testes de integração isolados cobrem toda a operação interna; teste de contrato é mais adequado para microsserviços desacoplados com deploys independentes, que não são o caso aqui.

Continue lendo

Receba o resumo da semana

Um e-mail por semana com o que foi publicado. Sem spam, e você sai quando quiser.

Blog do Felipe Marciano

Decisões de arquitetura, .NET e sistemas distribuídos, escritas por quem vive com as consequências delas.

© 2026 Felipe Marciano. Todos os direitos reservados. · v1.54.0