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.

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:
- Cobertura realista da infraestrutura utilizada, incluindo banco e filas ou mecanismos de mensagens.
- Validação da comunicação assíncrona e o comportamento diante de falhas.
- Facilidade de automação e integração no pipeline de CI/CD.
- Garantia de isolamento para evitar interferência entre testes.
- 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
- Estratégias para migração gradual de monólitos para microsserviços usando Event-Driven Architecture: contexto da arquitetura event-driven e testes.
- Integration tests in ASP.NET Core | Microsoft Learn: uso de WebApplicationFactory para integração.
- Testcontainers for .NET: uso de containers para testes com ambiente real.
- Backup por job da aplicação, e não por cron e shell no servidor: importância do backup e rollback no deploy.
- Dump antes do deploy, e a falha dele aborta a publicação: estratégia de rollback em sistemas com migrations.
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
- Do e-mail copiado à mão ao funil num sistema só: cinco decisões e o que cada uma custouUma empresa de comércio exterior, que conduz processos de mudança para os clientes, recebia os pedidos de orçamento por e-mail, enviados por três plataformas de geração de leads. Alguém lia cada mensagem e copiava os dados à mão. Este texto conta cinco decisões que tomei ao construir o sistema que substituiu esse trabalho, e o que cada uma deixou pior.
- Governança e monitoramento de eventos para evitar inconsistências em microsserviçosGerenciar eventos em microsserviços requer governança e monitoramento detalhados para evitar inconsistências como perda e duplicação. Compartilho práticas de auditoria automatizada, dashboards e alertas baseados em minha experiência com sistemas event-driven.
- Event-driven interno: desacoplamento por eventos locais em monólitos moduladosEste texto aprofunda um ponto do post sobre migração gradual de monólitos para microsserviços via event-driven architecture, detalhando como adotar eventos locais dentro do próprio monólito pode ajudar no desacoplamento entre módulos, simplificando evolução e testes.