Uma implantação recente quebrou três microsserviços, embora todos os testes unitários, testes de integração e verificações de mock-server tenham passado. A equipe substituiu seus mocks de API por testes de contrato. Em seis meses, a contagem de contratos subiu de três para 47 e a taxa mensal de falhas de integração caiu de dois incidentes para zero.

Por que mocks não podem proteger você

Um servidor de mock apenas imita o formato que um consumidor espera; ele nunca verifica se o provedor realmente fornece esse formato. Se um provedor renomeia um campo — por exemplo, de name para display_name — o mock ainda retorna o payload antigo, os testes do consumidor continuam passando e o sistema em produção trava. A falha de produção às 14h de uma terça-feira foi exatamente isso: o mock "mentiu" sobre o contrato real.

Testes de contrato preenchem essa lacuna

O teste de contrato força os dois lados de uma API a concordarem com uma definição compartilhada antes que qualquer código chegue à produção. Existem duas abordagens comuns:

  • Contratos orientados pelo consumidor (Consumer-driven contracts) – o serviço consumidor escreve as expectativas; o serviço provedor as valida. Isso funciona bem para microsserviços internos que evoluem juntos.
  • Contratos orientados pelo provedor (Provider-driven contracts) – o provedor publica uma especificação; os consumidores verificam seu código em relação a ela. Este é o padrão usual para APIs públicas.

A primeira abordagem geralmente evita integrações quebradas dentro de uma arquitetura de microsserviços.

Como funciona um contrato orientado pelo consumidor

  1. O consumidor escreve um teste que descreve exatamente o que precisa do provedor.
  2. A execução do teste gera um pact file – um documento JSON que registra essas expectativas.
  3. O provedor executa seu serviço real contra o arquivo pact em seu pipeline de CI.
  4. Se o provedor alterar um campo, a verificação falha e o build é bloqueado.

Como a verificação é executada no código real do provedor, qualquer alteração que cause quebra é detectada precocemente, não após a implantação.

Onde os testes de contrato se encaixam na sua pirâmide de testes

  • Testes unitários – rápidos, testam a lógica isolada.
  • Testes de contrato – velocidade média, confirmam se os acordos de API se mantêm.
  • Testes de ponta a ponta (E2E) – lentos, exercitam fluxos de negócio completos.

Trate os testes de contrato como uma ponte entre o feedback rápido dos testes unitários e a ampla cobertura das suítes de ponta a ponta. Foque nos pontos de integração que quebram com mais frequência e comece com dois ou três endpoints críticos.

História de adoção no mundo real

A equipe que inspirou este artigo começou com três contratos cobrindo suas chamadas mais frágeis. Seis meses depois, eles tinham 47 contratos cobrindo a maior parte do tráfego entre serviços. Durante esse período, os incidentes de quebra de API caíram de dois por mês para zero.

Quando o teste de contrato pode não valer a pena

  • Você é um desenvolvedor solo mantendo todos os serviços em um único repositório.
  • A API é excepcionalmente estável e não muda há anos.
  • Você está construindo um protótipo descartável que será descartado em breve.

Nesses cenários, a sobrecarga de manter contratos pode superar o benefício.

Possíveis desvantagens e como mitigá-las

  • Mantenha os contratos versionados junto com o código que eles descrevem.
  • Automatize a verificação em cada execução de CI para evitar contratos obsoletos.
  • Revise as mudanças nos contratos em pull requests para detectar quebras acidentais.

Conclusão

Se você ainda depende de mocks criados manualmente para se convencer de que seus serviços conseguem se comunicar, você está apostando em uma falsa promessa. O teste de contrato transforma essa aposta em um acordo verificável, detectando alterações que causam quebras antes que cheguem à produção e, como mostram os números da equipe, pode eliminar completamente as falhas de integração.