🧪 Testes de Integração em SOA

O MVP que cada grupo está construindo para o parceiro de mercado não é um monolito isolado. Ele é, na prática, um pequeno ecossistema de serviços: a API .NET conversa com um banco de dados, talvez com um cache, talvez com uma fila, quase certamente com uma ou duas APIs externas — do parceiro, de um provedor de autenticação, de um gateway de pagamento, de outro squad. Essa arquitetura é o que chamamos de SOA (Service-Oriented Architecture).

Numa arquitetura SOA, a maioria dos bugs caros não aparece quando você testa uma classe isolada. Eles aparecem quando duas peças tentam conversar pela primeira vez: o ORM gera um SQL que o Postgres real recusa; o JSON que vem da API externa tem um campo faltando; o token JWT expira no meio da chamada; o broker de mensagens devolve um erro de schema. Tudo isso é integração.

Esta aula te dá duas ferramentas concretas para atacar esse problema no .NET, sem cair na armadilha do "rodar contra produção" nem na do "mocko tudo e finjo que funciona":

• Testcontainers — para dependências que você possui (BD, broker, cache do seu serviço). Sobe a coisa real em container Docker descartável.
• VCR / WireMock.Net — para dependências que você consome (APIs de outros squads, terceiros). Grava cassetes HTTP e reproduz determinístico.

E te dá também uma conversa honesta sobre os limites de cada uma. Especialmente: por que VCR não substitui contract testing de verdade (que é problema da aula 9, e cuja stack canônica é Pact, não WireMock).

Antes de qualquer ferramenta, precisamos de uma definição operacional clara. A literatura é cheia de variações sutis. Vamos adotar uma e segurá-la firme durante o módulo inteiro:

Compare com as outras duas categorias da pirâmide:

Os três níveis em uma frase cada

O que SÓ teste de integração captura

Existe uma classe inteira de defeitos que nunca aparece em teste unitário, porque ele depende de várias peças tentando conversar. Os principais:

• Wiring entre camadas: controller chama service que chama repository. Cada peça passa em unit isolado, mas a configuração de DI no Startup.cs/Program.cs está errada — o serviço não está registrado, está registrado como Scoped num lugar que precisa de Singleton, ou o middleware de autenticação está antes do middleware de roteamento. Você só descobre quando uma request HTTP de verdade tenta passar pelo pipeline inteiro.
• Contratos com o BD real: o EF Core gera SQL diferente de mocks. Migrations, índices, tipos NUMERIC × DECIMAL, colunas NOT NULL que viraram NULL sem ninguém perceber, JSONB que o SQLite InMemory simplesmente não suporta — tudo isso só aparece quando uma query roda contra um banco de verdade.
• Auth, cache, middleware: JWT, claims, políticas de autorização, headers de cache, CORS. Todo esse aparato só executa quando o pipeline HTTP roda inteiro — algo que unit tests pulam por completo.
• Mapeamento ORM: relações, lazy loading, navigation properties, herança TPH/TPT. Configuração errada do Fluent API só explode quando uma query real tenta materializar o resultado.
• Integração com serviço externo: em SOA, sua app chama a API de outro squad. Headers obrigatórios, timeouts, política de retry, contratos de payload, esquemas de erro — só aparecem em integração, nunca em mocks isolados que você mesmo escreveu.

A pirâmide de testes é o diagrama mais famoso de toda a engenharia de qualidade. Foi popularizado por Mike Cohn em Succeeding with Agile e refinado por Martin Fowler. A ideia: base larga (muitos testes baratos), topo estreito (poucos testes caros).

Proporções saudáveis (rule of thumb)

Não há regra rígida, mas como orientação inicial:

• 70% unitários — base larga, garantem que cada peça funciona isolada.
• ~25% integração — meio, garantem que as peças conversam.
• ~5% E2E — topo, só fluxos críticos de usuário (login → checkout, criação de conta, fluxo principal do MVP).

O anti-padrão: pirâmide invertida (taça de sorvete)

Times que começam pelos testes E2E geralmente entram em um anti-padrão clássico: poucos unitários, alguns integração, muitos E2E. Aparece visualmente como uma taça de sorvete (invertida). Por que é ruim?

• E2E são lentos: 30s a vários minutos cada. CI de 1h+. Time perde a vontade de rodar.
• E2E são frágeis: qualquer mudança de CSS, qualquer microssegundo a mais de latência, qualquer dado de teste fora do lugar quebra. Vira ruído.
• E2E são caros de debugar: quando quebram, você tem 10 camadas para investigar. Em unit, você tem 1.

Quando você escreve um teste de integração, tem uma escolha fundamental: vai espiar dentro do sistema (white-box) ou só observar o que entra e sai (black-box)? Em SOA, a resposta correta é quase sempre black-box — e este capítulo explica por quê.

As duas perspectivas

O que é "contrato" em SOA

Em arquitetura orientada a serviços, o contrato é o que o outro lado consegue ver. Para um endpoint HTTP, isso significa:

• O verbo + path (POST /api/pedidos);
• O schema do payload de entrada (campos obrigatórios, tipos, formatos);
• O schema do payload de saída (estrutura, headers, content-type);
• Os códigos de status HTTP possíveis e o que cada um significa (200, 201, 400, 401, 422, 503…);
• Os side effects observáveis: uma mensagem publicada num broker, um arquivo gravado, um e-mail disparado.

Essa é a superfície pública do seu serviço. É o que outro squad consome. É o que precisa ser estável.

Sinais de que você está testando white-box sem querer

Olhe seus testes de integração existentes (ou os primeiros que vai escrever) e verifique se aparecem esses padrões. Se sim, refatore para black-box:

Este capítulo é o coração da aula. Se você sair daqui dominando apenas uma coisa, que seja esta: antes de escrever qualquer teste de integração em SOA, classifique cada dependência em uma das duas colunas abaixo. A ferramenta de teste sai do mapa, não da preferência pessoal.

Como classificar na prática

Quando bater dúvida sobre uma dependência específica, faça-se 3 perguntas:

1. Quem controla o deploy? Se é o seu time → possuída. Se é outro time ou terceiro → consumida.
2. Posso subir uma cópia idêntica numa máquina nova em 5 minutos? Se sim → possuída. Se não (precisa de credenciais externas, contratos comerciais, infra de outro time) → consumida.
3. Quando o schema muda, eu fico sabendo antes ou depois? Antes (eu controlo a migration) → possuída. Depois (descubro porque quebrou) → consumida.

Exemplo prático: anatomia de um MVP típico

Imagine que seu grupo está construindo um serviço de recomendações para o parceiro. Vamos mapear as dependências:

O exercício recomendado antes de começar

Pegue uma folha de papel (ou um README do projeto) e desenhe duas colunas: possuídas e consumidas. Liste todas as dependências do MVP do seu grupo. Esse é o mapa de testes de integração do projeto. A partir dele, você consegue planejar quais testes escrever e qual ferramenta usar para cada um.

O Testcontainers for .NET é uma biblioteca que sobe containers Docker descartáveis dentro do ciclo de vida do teste. PostgreSQL real, Redis real, RabbitMQ real — não um mock, não um in-memory, não uma versão simplificada. O processo de verdade, com o dialeto de verdade, com o protocolo de verdade.

6.1 · Quando usar (e quando não)

6.2 · Pré-requisitos

Antes de começar, garanta que estes itens estão prontos:

1. .NET SDK 8.0+ instalado (dotnet --version deve responder).
2. Docker Desktop rodando (no Windows/Mac) ou Docker Engine ativo no Linux (docker ps deve listar containers).
3. Conexão com a internet na primeira execução, para baixar a imagem do banco.
4. O projeto da API já configurado, com pelo menos um DbContext ou repositório implementado.

6.3 · Passo a passo · configurando o projeto

1. Criar o projeto de testes

   No diretório raiz do projeto, ao lado da pasta da API, crie um projeto de testes xUnit:

   terminalbash

   # do diretório raiz da solution
   dotnet new xunit -n Pedidos.IntegrationTests
   dotnet sln add Pedidos.IntegrationTests/Pedidos.IntegrationTests.csproj
   # adicionar referência ao projeto da API
   dotnet add Pedidos.IntegrationTests reference Pedidos.Api

2. Instalar os pacotes NuGet necessários

   Você precisa do core de Testcontainers + o módulo específico para o seu banco. Aqui usamos PostgreSQL como exemplo:

   terminalbash

   cd Pedidos.IntegrationTests
   dotnet add package Testcontainers
   dotnet add package Testcontainers.PostgreSql
   dotnet add package Microsoft.AspNetCore.Mvc.Testing
   dotnet add package Microsoft.EntityFrameworkCore.Design
   # opcional, mas recomendado:
   dotnet add package Respawn
   dotnet add package Bogus

   Resumo do que cada um faz:

   • Testcontainers — núcleo da biblioteca.
   • Testcontainers.PostgreSql — builder específico do Postgres (existem módulos para MsSql, MySql, MongoDB, Redis, RabbitMQ, Kafka, etc.).
   • Microsoft.AspNetCore.Mvc.Testing — fornece WebApplicationFactory se você quiser testar via HTTP.
   • Respawn — limpeza rápida do banco entre testes.
   • Bogus — gerador de dados faker com seed determinístico.

3. Criar a fixture do container

   A fixture é a classe que gerencia o ciclo de vida do container. Implementa IAsyncLifetime para que o xUnit chame InitializeAsync antes da suite e DisposeAsync ao final.

   Pedidos.IntegrationTests/Fixtures/PostgresFixture.csC#

   using Testcontainers.PostgreSql;
   using Xunit;
   
   namespace Pedidos.IntegrationTests.Fixtures;
   
   public class PostgresFixture : IAsyncLifetime
   {
       private readonly PostgreSqlContainer _db = new PostgreSqlBuilder()
           .WithImage("postgres:16-alpine")
           .WithDatabase("pedidos_test")
           .WithUsername("app")
           .WithPassword("app")
           .WithCleanUp(true)
           .Build();
   
       public string ConnectionString => _db.GetConnectionString();
   
       public async Task InitializeAsync()
       {
           await _db.StartAsync();
           // rodar migrations contra o BD recém-criado
           await using var ctx = new AppDbContext(
               new DbContextOptionsBuilder<AppDbContext>()
                   .UseNpgsql(ConnectionString).Options);
           await ctx.Database.MigrateAsync();
       }
   
       public Task DisposeAsync() => _db.DisposeAsync().AsTask();
   }

4. Marcar a fixture para reuso na collection

   Se múltiplas classes de teste precisam compartilhar o mesmo container (recomendado, porque startup do container é caro), defina uma collection:

   Pedidos.IntegrationTests/Fixtures/DatabaseCollection.csC#

   using Xunit;
   
   namespace Pedidos.IntegrationTests.Fixtures;
   
   [CollectionDefinition("database")]
   public class DatabaseCollection : ICollectionFixture<PostgresFixture> { }

5. Escrever o teste de sucesso (black-box)

   Aqui vai um teste integrado que valida o fluxo de criar pedido + recuperar pedido — só pelo contrato observável:

   Pedidos.IntegrationTests/PedidosFlowTests.csC#

   using Pedidos.IntegrationTests.Fixtures;
   using Xunit;
   
   namespace Pedidos.IntegrationTests;
   
   [Collection("database")]
   public class PedidosFlowTests
   {
       private readonly PostgresFixture _fix;
   
       public PedidosFlowTests(PostgresFixture fix) => _fix = fix;
   
       [Fact]
       public async Task DeveCriarPedidoEListarComItens()
       {
           // Arrange — Postgres REAL rodando, schema migrado
           await using var ctx = new AppDbContext(
               new DbContextOptionsBuilder<AppDbContext>()
                   .UseNpgsql(_fix.ConnectionString).Options);
   
           var svc = new PedidoService(ctx);
           var dto = new NovoPedidoDto(ClienteId: 42,
               Itens: [new(1, 2), new(3, 1)]);
   
           // Act — passa pelo wiring real + query real
           var pedidoId = await svc.CriarAsync(dto);
           var achado   = await svc.ObterAsync(pedidoId);
   
           // Assert — só pelo contrato observável
           Assert.NotNull(achado);
           Assert.Equal(42, achado!.ClienteId);
           Assert.Equal(2, achado.Itens.Count);
       }
   }

6. Escrever o teste de erro / exceção

   Todo fluxo importante precisa de um teste de cenário ruim. Aqui testamos que pedido com cliente inexistente lança a exceção esperada — sem inspecionar estado interno:

   Pedidos.IntegrationTests/PedidosFlowTests.cs (cont.)C#

   [Fact]
   public async Task DeveRecusarPedidoComClienteInexistente()
   {
       await using var ctx = new AppDbContext(
           new DbContextOptionsBuilder<AppDbContext>()
               .UseNpgsql(_fix.ConnectionString).Options);
       var svc = new PedidoService(ctx);
   
       var dto = new NovoPedidoDto(
           ClienteId: 99999, // não existe
           Itens: [new(1, 1)]);
   
       var ex = await Assert.ThrowsAsync<ClienteNaoEncontradoException>(
           () => svc.CriarAsync(dto));
   
       Assert.Contains("99999", ex.Message);
   }

7. Garantir isolamento entre testes (Respawn)

   Se múltiplos testes escrevem no banco, eles podem se sujar mutuamente. Use Respawn para "voltar ao estado inicial" rápido antes de cada teste, sem dropar e recriar o banco:

   Pedidos.IntegrationTests/Fixtures/PostgresFixture.cs (adição)C#

   using Respawn;
   using Npgsql;
   
   // dentro da classe PostgresFixture, adicione:
   private Respawner? _respawner;
   
   public async Task ResetAsync()
   {
       await using var conn = new NpgsqlConnection(ConnectionString);
       await conn.OpenAsync();
       _respawner ??= await Respawner.CreateAsync(conn,
           new RespawnerOptions { DbAdapter = DbAdapter.Postgres });
       await _respawner.ResetAsync(conn);
   }

   E em cada classe de teste:

   usoC#

   public PedidosFlowTests(PostgresFixture fix)
   {
       _fix = fix;
       _fix.ResetAsync().GetAwaiter().GetResult();
   }

8. Rodar localmente

   Tudo configurado, rode os testes:

   terminalbash

   dotnet test Pedidos.IntegrationTests

   Na primeira execução, o Docker baixa a imagem (~80 MB para Postgres alpine). Demora um pouco. Da segunda em diante, startup do container leva ~3–5 segundos. Cada teste em si roda em milissegundos depois do container estar de pé.

6.4 · Configurando no CI

GitLab CI

integration_tests:
  stage: test
  image: mcr.microsoft.com/dotnet/sdk:8.0
  services:
    - name: docker:dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  script:
    - dotnet restore
    - dotnet test Pedidos.IntegrationTests --logger "trx;LogFileName=tests.trx"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

GitHub Actions

name: tests
on: [pull_request]
jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'
      # Docker já vem instalado no ubuntu-latest runner
      - run: dotnet test Pedidos.IntegrationTests

6.5 · Troubleshooting comum

Para dependências consumidas — APIs de outros squads, terceiros, gateways externos — a estratégia é completamente diferente. Você não vai subir o serviço externo num container (você não tem o código dele e não controla o deploy). Você vai gravar a interação HTTP numa primeira execução e reproduzir deterministicamente nas próximas.

7.1 · O conceito do cassete (VCR)

O conceito veio originalmente do VCR.py (Ruby, depois portado para Python). A metáfora é a de uma fita VHS dos anos 90: você grava o programa uma vez e assiste quantas vezes quiser depois, sempre exatamente igual.

• 1ª execução · gravação: o teste roda contra a API real. A biblioteca intercepta o HTTP, grava request + response num arquivo (o cassete, geralmente JSON ou YAML).
• Execuções seguintes · replay: o teste roda contra o stub. O HTTP é interceptado e a resposta vem do cassete. Não chama a API real. Não depende de rede. Não depende de uptime.

Em .NET, a biblioteca padrão de mercado é o WireMock.Net. Ela suporta os dois modos: criar mappings manualmente em código (modo stub) ou gravar via proxy (modo recording).

7.2 · Pré-requisitos

1. .NET SDK 8.0+ instalado.
2. O projeto da sua API já configurado, com pelo menos uma classe que faz uma chamada HTTP externa via HttpClient.
3. A URL da API externa (a real) — para gravar o cassete pela primeira vez.
4. Docker NÃO é necessário — WireMock.Net roda em-process.

7.3 · Passo a passo · setup do projeto

1. Instalar o pacote

   No projeto de testes:

   terminalbash

   cd Pedidos.IntegrationTests
   dotnet add package WireMock.Net

2. Criar a fixture do WireMock

   Igual ao Testcontainers, usamos IAsyncLifetime para gerenciar o ciclo de vida do servidor de stub:

   Pedidos.IntegrationTests/Fixtures/CatalogoApiFixture.csC#

   using WireMock.Server;
   using WireMock.Settings;
   using Xunit;
   
   namespace Pedidos.IntegrationTests.Fixtures;
   
   public class CatalogoApiFixture : IAsyncLifetime
   {
       public WireMockServer Server { get; private set; } = null!;
   
       public string Url => Server.Url!;
   
       public Task InitializeAsync()
       {
           Server = WireMockServer.Start(new WireMockServerSettings
           {
               // porta dinâmica — evita conflito com outras suites
               Port = 0,
               ReadStaticMappings = true,
               StaticMappingsPath = "Mappings/Catalogo"
           });
           return Task.CompletedTask;
       }
   
       public Task DisposeAsync()
       {
           Server.Stop();
           Server.Dispose();
           return Task.CompletedTask;
       }
   }

3. Modo manual · criar mappings em código

   A forma mais simples (e geralmente recomendada para começar) é definir os stubs em código C#. Você ganha autocomplete, validação de compilador e facilidade de debug:

   Pedidos.IntegrationTests/CatalogoTests.csC#

   using Pedidos.IntegrationTests.Fixtures;
   using WireMock.RequestBuilders;
   using WireMock.ResponseBuilders;
   using Xunit;
   
   namespace Pedidos.IntegrationTests;
   
   public class CatalogoTests : IClassFixture<CatalogoApiFixture>
   {
       private readonly CatalogoApiFixture _fix;
   
       public CatalogoTests(CatalogoApiFixture fix) => _fix = fix;
   
       [Fact]
       public async Task DeveRetornarItemQuandoCatalogoResponde200()
       {
           // Arrange — define o stub do catálogo
           _fix.Server
               .Given(Request.Create()
                   .UsingGet()
                   .WithPath("/catalogo/42"))
               .RespondWith(Response.Create()
                   .WithStatusCode(200)
                   .WithHeader("Content-Type", "application/json")
                   .WithBodyAsJson(new
                   {
                       id = 42,
                       nome = "Notebook X",
                       estoque = 7
                   }));
   
           var http = new HttpClient { BaseAddress = new Uri(_fix.Url) };
           var svc  = new CatalogoService(http);
   
           // Act
           var item = await svc.ObterAsync(42);
   
           // Assert — black-box
           Assert.Equal(42, item.Id);
           Assert.Equal("Notebook X", item.Nome);
           Assert.Equal(7, item.Estoque);
       }
   }

4. Cenário de erro · stub de 503 e timeout

   Para testar como o consumer reage a falhas do provider, defina mappings de erro. Aqui simulamos uma indisponibilidade e validamos que o serviço propaga uma exceção tipada:

   CatalogoTests.cs (cont.)C#

   [Fact]
   public async Task DeveLancarQuandoCatalogoIndisponivel()
   {
       _fix.Server
           .Given(Request.Create().UsingGet().WithPath("/catalogo/99"))
           .RespondWith(Response.Create()
               .WithStatusCode(503)
               .WithBody("service unavailable"));
   
       var http = new HttpClient { BaseAddress = new Uri(_fix.Url) };
       var svc  = new CatalogoService(http);
   
       var ex = await Assert.ThrowsAsync<CatalogoIndisponivelException>(
           () => svc.ObterAsync(99));
   
       Assert.Contains("503", ex.Message);
   }
   
   [Fact]
   public async Task DeveRespeitarTimeoutDoCatalogo()
   {
       _fix.Server
           .Given(Request.Create().UsingGet().WithPath("/catalogo/lento"))
           .RespondWith(Response.Create()
               .WithStatusCode(200)
               .WithDelay(TimeSpan.FromSeconds(10))
               .WithBodyAsJson(new { id = 1 }));
   
       var http = new HttpClient
       {
           BaseAddress = new Uri(_fix.Url),
           Timeout = TimeSpan.FromMilliseconds(500)
       };
       var svc = new CatalogoService(http);
   
       await Assert.ThrowsAsync<TaskCanceledException>(
           () => svc.ObterAsync(1));
   }

5. Modo recording · gravar cassete da API real

   Quando a API externa é complexa e você quer capturar a resposta exata (com headers, datas, formatos), use o modo proxy. Você define a URL real, o servidor faz proxy, e grava o roundtrip em JSON:

   Tools/RecordCatalogoCassette.cs (utilitário, roda 1× manual)C#

   using WireMock.Server;
   using WireMock.Settings;
   
   var server = WireMockServer.Start(new WireMockServerSettings
   {
       Port = 8088,
       ProxyAndRecordSettings = new ProxyAndRecordSettings
       {
           Url = "https://api.catalogo-real.com",
           SaveMapping = true,
           SaveMappingToFile = true
       }
   });
   
   Console.WriteLine("WireMock recording em http://localhost:8088");
   Console.WriteLine("Faça as requests que quer gravar e tecle Enter para sair");
   Console.ReadLine();
   server.Stop();

   Depois rode curl http://localhost:8088/catalogo/42. O WireMock proxia pra API real, retorna a resposta verdadeira e grava o mapping em __admin/mappings/. Mova esses arquivos para Pedidos.IntegrationTests/Mappings/Catalogo/ e versione no Git.

6. Versionar cassetes no repositório

   Os mappings JSON devem ficar versionados junto com o código. Estrutura recomendada:

   estrutura de pastastree

   Pedidos.IntegrationTests/
   ├── Fixtures/
   │   ├── PostgresFixture.cs
   │   └── CatalogoApiFixture.cs
   ├── Mappings/
   │   └── Catalogo/
   │       ├── get-item-42.json
   │       ├── get-item-not-found.json
   │       └── post-item-success.json
   ├── CatalogoTests.cs
   ├── PedidosFlowTests.cs
   └── Pedidos.IntegrationTests.csproj

   Configure no .csproj para copiar os mappings para o output:

   Pedidos.IntegrationTests.csprojXML

   <ItemGroup>
     <None Update="Mappings\**\*.json">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>
   </ItemGroup>

7. Integrar com HttpClient via DI

   Para que a sua API real use o WireMock no teste e a URL verdadeira em produção, configure HttpClientFactory com um nome lógico no DI:

   Program.cs (API real)C#

   builder.Services.AddHttpClient("Catalogo", c =>
   {
       c.BaseAddress = new Uri(builder.Configuration["Catalogo:BaseUrl"]!);
       c.Timeout = TimeSpan.FromSeconds(5);
   });

   No teste, sobrescreva a config apontando para o WireMock:

   uso no teste com WebApplicationFactoryC#

   var factory = new WebApplicationFactory<Program>()
       .WithWebHostBuilder(b => b.ConfigureAppConfiguration((_, cfg) =>
       {
           cfg.AddInMemoryCollection(new Dictionary<string, string?>
           {
               ["Catalogo:BaseUrl"] = _fix.Url // aponta para o stub
           });
       }));
   
   var client = factory.CreateClient();
   // agora as chamadas internas para "Catalogo" vão para o WireMock

8. Rodar localmente e no CI

   WireMock.Net roda em-process: não precisa de Docker. O comando é idêntico ao do Testcontainers:

   terminalbash

   dotnet test Pedidos.IntegrationTests

   No CI, qualquer runner com .NET SDK funciona — não precisa de configuração especial:

   .github/workflows/test.ymlYAML

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-dotnet@v4
           with: { dotnet-version: '8.0.x' }
         - run: dotnet test

7.4 · Troubleshooting comum

Agora que você conhece as duas ferramentas em profundidade, a decisão de qual usar deve sair quase automaticamente do mapa SOA que você desenhou no capítulo 5. Esta tabela é a referência rápida:

Este capítulo é um aviso pedagógico. Sem ele, você sai da aula com a impressão errada de que VCR resolve "contrato em SOA" — e na primeira entrevista técnica vai pagar mico. Vamos ser explícitos: VCR / WireMock.Net resolve isolamento, NÃO resolve contrato. Os dois problemas são diferentes, exigem ferramentas diferentes, e confundi-los é fonte de bugs caros em produção.

9.1 · O que VCR faz bem

9.2 · Os 4 pecados de usar VCR como "contract testing"

Se você (ou o tech lead) começar a chamar o cassete WireMock de "teste de contrato", surge um conjunto de problemas estruturais. Eles não são teóricos — são reais e quebram em produção:

9.3 · O que faz contract testing de verdade

Existe uma família de ferramentas que realmente resolve o problema do contrato em SOA. A mais conhecida e canônica é Pact:

Pact em 60 segundos

1. Consumer-side: o squad consumidor define no teste o contrato que espera do provider (request específica + response esperada). Pact gera um arquivo de contrato (JSON).
2. Broker: o contrato é publicado num Pact Broker (serviço central). Múltiplos consumers podem publicar contratos contra o mesmo provider.
3. Provider-side: o build do provider verifica que ele cumpre todos os contratos publicados pelos seus consumers. Se um consumer espera /items/42 com um schema X e o provider não responde isso, o build do provider quebra.
4. Versionamento: contratos têm versões. Provider pode estar em v2, mas continuar atendendo o contrato v1 enquanto consumers migram.

O resultado é verificação bidirecional: tanto consumer quanto provider falham cedo quando o contrato é violado. Esse é o problema que VCR não resolve.

Outras ferramentas válidas

• Spring Cloud Contract — equivalente do Pact no ecossistema Java/Spring.
• OpenAPI + Schemathesis — quando o spec OpenAPI é fonte da verdade, Schemathesis gera testes que verificam se o provider respeita o spec declarado.
• Postman + Newman — para times menos maduros, postman collections rodando no CI podem fazer um contract testing leve.

9.4 · Como falar disso em entrevista (sem se enrolar)

Diga isso com tranquilidade. Vai ficar claro pro entrevistador que você conhece os limites das ferramentas — que é exatamente o que separa engenheiro júnior de engenheiro pleno.

Conhecer as ferramentas é metade do caminho. A outra metade é evitar armadilhas comuns e seguir padrões que outros times já validaram. Esta seção lista os principais.

10.1 · Anti-padrões a evitar

10.2 · Padrões recomendados

AAA · Arrange, Act, Assert

Todo teste tem 3 fases. Separe explicitamente, com comentários ou linhas em branco. Facilita leitura, debug e manutenção:

[Fact]
public async Task NomeDescritivoDoComportamento()
{
    // Arrange — preparar dados, mocks, estado
    var input = ...;

    // Act — executar a operação testada
    var result = await svc.FazerAlgo(input);

    // Assert — verificar o contrato observável
    Assert.Equal(esperado, result);
}

Nome descritivo do teste

O nome do teste é a documentação. Convenções comuns:

• DeveFazerXQuandoY — em português, direto.
• Should_DoX_When_Y — equivalente em inglês.
• UnitOfWork_StateUnderTest_ExpectedBehavior — formato Roy Osherove.

Um teste, uma asserção lógica

Vários Assert no mesmo teste estão ok se todos validam o mesmo comportamento. Múltiplos comportamentos? Múltiplos testes:

// ❌ Ruim — dois comportamentos no mesmo teste
[Fact]
public async Task TesteDoFluxoDePedido()
{
    var pedido = await svc.CriarAsync(...);
    Assert.NotNull(pedido);

    var cancelado = await svc.CancelarAsync(pedido.Id);
    Assert.True(cancelado);
}

// ✅ Bom — dois testes separados
[Fact]
public async Task DeveCriarPedidoQuandoDadosValidos() { ... }

[Fact]
public async Task DeveCancelarPedidoAposCriacao() { ... }

Theory para cenários parametrizados

Mesmo comportamento com inputs diferentes? Use [Theory] + [InlineData]:

[Theory]
[InlineData(0, "quantidade deve ser positiva")]
[InlineData(-1, "quantidade deve ser positiva")]
[InlineData(10001, "quantidade máxima é 10000")]
public async Task DeveRecusarQuantidadeInvalida(int qty, string msg)
{
    var ex = await Assert.ThrowsAsync<ValidationException>(
        () => svc.CriarAsync(new(qty)));
    Assert.Contains(msg, ex.Message);
}

A ponderada da aula 8 é individual, em sala, 90 minutos. A entrega é via Merge Request no repositório oficial do grupo. Testcontainers e WireMock.Net (VCR) são obrigatórios na entrega — você usa as duas ferramentas no mesmo teste. Além disso, cada aluno do grupo cobre um fluxo diferente: fluxos duplicados são inválidos.

11.1 · Checklist da entrega · 10 passos

1. 🤝 Coordenar no grupo · registrar fluxo único

   Antes de codar, alinhe com seus colegas qual fluxo cada um vai testar. Registre a divisão numa tabela no README do repositório, com 3 colunas: aluno, fluxo escolhido, link do MR (preenchido depois). Fluxos duplicados entre alunos do mesmo grupo são considerados não-conformes — quem chega primeiro pega.

   seção sugerida no README do repoMarkdown

   ## 🧪 Tracker · Testes de Integração (Aula 8)
   
   | Aluno              | Fluxo testado            | MR                 |
   |--------------------|--------------------------|--------------------|
   | Ana Silva          | POST /pedidos            | !127               |
   | Bruno Costa        | GET /catalogo/{id}       | !128               |
   | Carla Dias         | POST /pagamentos/charge  | (em desenvolvim.)  |
   | Diego Souza        | PUT /pedidos/{id}/cancel | (em desenvolvim.)  |

2. Identificar as duas dependências do fluxo

   Olhe o fluxo escolhido e mapeie: qual é a dependência possuída (geralmente o BD do serviço, mas pode ser cache ou broker)? E qual é a dependência consumida (geralmente uma API externa do parceiro ou de outro squad)? Anote as duas — vão pra descrição do MR.

3. Identificar o RF correspondente

   Vá no artefato de requisitos do grupo e ache o RF (regra de negócio) que esse fluxo valida. Anote o código exato (ex.: "RF05") — vale ⭐ Excelência na rastreabilidade.

4. Identificar o eixo RNF (ISO 25010)

   Qual eixo da ISO/IEC 25010 esse teste atende ou impacta? Eficiência de desempenho? Segurança? Confiabilidade? Manutenibilidade? Anote o código RNF do artefato (ex.: "RNF02").

5. Criar a branch

   Padrão: test/integration-{nome-do-fluxo}. Ex.: test/integration-criar-pedido.

6. 🐳 Configurar Testcontainers (dependência possuída)

   Crie a fixture do container conforme o capítulo 6. PostgreSqlBuilder (ou módulo equivalente do seu BD) + IAsyncLifetime. Migrations rodando no setup. Verifique que o container sobe local.

7. 📼 Configurar WireMock.Net (dependência consumida)

   Crie a fixture do stub HTTP conforme o capítulo 7. WireMockServer.Start com porta dinâmica + mappings das responses esperadas da API externa. Aponte o HttpClient da sua app para a URL do WireMock no teste.

8. Implementar 1 teste de sucesso + 1 teste de erro

   Sucesso: fluxo feliz com BD real (TC) + API externa respondendo 200 (WireMock). Erro: pode ser tanto regra de negócio violada (BD recusa) quanto falha do provider (WireMock devolve 503/timeout). Padrão AAA. Black-box: só interage pelo contrato observável.

9. Garantir dotnet test verde no pipeline

   O CI do repositório precisa estar verde. Se falhou, o critério 2 do barema vai cair. Push para a branch e veja o resultado antes de abrir o MR.

10. Abrir o MR com descrição completa + postar link na plataforma

    A descrição do MR é parte da nota. Use o modelo abaixo. Depois de abrir o MR, atualize a tabela do README com o número do MR e cole o link direto na plataforma da disciplina antes do fim dos 90 min.

    modelo da descrição do MRMarkdown

    ## Fluxo testado
    Criação de pedido via POST /api/pedidos.
    
    ## Coordenação no grupo
    Registrado na tabela do README como meu fluxo (linha 1).
    Sem duplicação com colegas do grupo.
    
    ## Classificação das dependências
    
    ### Dependência possuída · Testcontainers
    **PostgreSQL do serviço de pedidos** — o grupo controla schema,
    migrations e deploy. Testado com `PostgreSqlBuilder` rodando
    postgres:16-alpine em container descartável.
    
    ### Dependência consumida · WireMock.Net (VCR)
    **API de catálogo do parceiro** — serviço externo que valida
    estoque antes de criar o pedido. Testado com stub HTTP que
    devolve 200 (sucesso) e 503 (cenário de erro).
    
    ## Rastreabilidade
    - **RF05** — Pedido deve ter ao menos 1 item válido e estoque
      positivo no catálogo (artefato de requisitos, seção 3.2).
    - **RNF02** — Eixo: Confiabilidade · o teste previne corrupção
      de dados em fluxo crítico (criação de pedido) e garante
      comportamento correto quando o catálogo externo cai. Sem
      este teste, uma alteração no schema do pedido ou queda do
      catálogo pode passar invisível e causar perda de pedidos.
    
    ## Cenários implementados
    - ✅ DeveCriarPedidoQuandoCatalogoConfirmaEstoque (sucesso)
    - ⚠️ DeveRecusarPedidoQuandoCatalogoIndisponivel (erro · 503)
    
    ## Pipeline
    - [x] `dotnet test` verde no CI
    - [x] Migrations rodam no setup da fixture do Postgres
    - [x] WireMock.Net devolve stubs determinísticos
    - [x] Container Postgres + WireMock descartáveis a cada execução

11.2 · Barema · 10 pontos · 5 critérios

Cada referência abaixo está anotada com o capítulo onde foi usada e por que vale a leitura. Use isso para aprofundar onde fez mais sentido.

• Martin Fowler — Testing Strategies in a Microservice Architecture

  O artigo de referência sobre a pirâmide de testes adaptada para microsserviços. Lê-se em 30 minutos e dá uma base sólida para todos os capítulos 2–4 deste material. Especialmente útil a discussão sobre contract tests, que liga ao capítulo 9.

• Testcontainers for .NET — Documentação oficial

  Documentação canônica da biblioteca usada no capítulo 6. Veja especialmente a seção Modules para os builders específicos (PostgreSql, MsSql, Redis, RabbitMQ, Kafka, MongoDB, MinIO). Tem exemplos completos prontos para copiar.

• WireMock.Net — Wiki

  Referência da biblioteca usada no capítulo 7. Veja em ordem: Getting Started, Request Matching, Response Templating, Admin REST API, Proxying. A seção sobre Static Mappings mostra como versionar cassetes JSON no repo.

• Microsoft Learn — Integration tests in ASP.NET Core

  Documentação oficial da Microsoft sobre WebApplicationFactory<Program>. Útil quando você quer testar pela camada HTTP em vez de chamar a service diretamente. Combina muito bem com Testcontainers (capítulo 6).

• Pact — Documentação oficial

  A referência canônica para contract testing real (capítulo 9). Veja Getting Started e Consumer-Driven Contracts. Esta é a stack que resolve o problema que VCR não resolve. Fica como aprofundamento para quem quer ir além da aula 8.

• ISO/IEC 25010 — Quality model

  Referência rápida dos 8 eixos de qualidade (functional suitability, performance efficiency, compatibility, usability, reliability, security, maintainability, portability). Use para justificar o RNF na ponderada (capítulo 11).

• Jay Fields — Working Effectively with Unit Tests

  Livro pago, mas vale o investimento se você quer levar testes a sério na carreira. Trata especialmente bem dos padrões AAA, nomenclatura de testes, e a distinção entre solitary tests (unit puro) e sociable tests (integração).

• Vladimir Khorikov — Unit Testing Principles, Practices, and Patterns

  Outro livro fundamental. Especial atenção ao capítulo sobre Integration testing best practices — alinha quase perfeitamente com o que está nesta aula. Útil para aprofundar a discussão sobre black-box (capítulo 4).