O backend publica uma atualização, todos os testes locais passam e uma integração deixa de funcionar. O campo continua no JSON, mas passou a aceitar nulo; um enum ganhou um valor que o consumidor não reconhece; ou a paginação mudou. A falha aparece na fronteira entre sistemas, onde cada equipe tinha uma interpretação diferente do acordo.
Um teste de contrato verifica expectativas compartilhadas sobre a comunicação entre consumidor e provedor. Ele não prova que todo o processo funciona, mas ajuda a detectar incompatibilidades antes de uma publicação conjunta ou de um incidente.
1. Identifique quem depende de quem
Liste os consumidores de cada endpoint, evento ou arquivo. Inclua aplicações internas, parceiros e tarefas agendadas. Uma API sem inventário pode ser alterada com segurança aparente enquanto um consumidor pouco visível continua usando um comportamento antigo.
Para cada relação, registre responsável, ambiente, operações, dados obrigatórios e tolerância a mudanças. O contrato deve refletir necessidades reais. Um consumidor que verifica centenas de campos que não utiliza torna a integração mais rígida sem aumentar a proteção útil.
2. Diferencie descrição e verificação
Uma especificação descreve a interface; a verificação confirma se uma implementação cumpre expectativas. Os dois artefatos se complementam. Ter um documento atualizado não garante que o servidor publicado corresponda a ele. Testar apenas um mock criado pela própria equipe também não confirma o provedor real.
O Pact documenta uma abordagem de testes de contrato para interações HTTP e mensagens. O ponto central é tornar expectativas verificáveis. A escolha da ferramenta depende da arquitetura e da capacidade de incorporar a verificação ao ciclo de entrega.
3. Escreva contratos sobre comportamento relevante
Defina método, rota, parâmetros, códigos de resposta e estrutura de dados necessária. Descreva os cenários de erro que o consumidor realmente trata. Uma resposta 200 com formato inesperado pode ser tão incompatível quanto um erro de transporte.
| Elemento | Exemplo de expectativa | Consequência de quebra |
|---|---|---|
| Identificador | Texto estável | Relações deixam de funcionar |
| Nulabilidade | Campo pode faltar ou ser nulo | Erro de renderização |
| Estado | Valores reconhecidos | Fluxo interrompido |
| Paginação | Próximo cursor e ordenação | Registros perdidos ou repetidos |
| Erro | Código de domínio conhecido | Tratamento incorreto |
Evite exigir a igualdade exata de valores variáveis quando o requisito é um tipo ou uma regra. Datas, identificadores gerados e ordem irrelevante precisam de matchers apropriados. A precisão deve existir onde protege o consumidor, não onde apenas torna o teste frágil.
4. Prepare estados de teste reproduzíveis
Um cenário de consulta de pedido precisa de um pedido com condições conhecidas. O provedor deve conseguir preparar esse estado sem depender de dados aleatórios de produção. Separe fixtures, limpeza e isolamento para que a ordem de execução não determine o resultado.
Inclua pedido inexistente, acesso negado e estado intermediário. Não use dados de clientes para facilitar a montagem. O contrato deve poder ser executado em uma esteira de desenvolvimento com dados sintéticos e credenciais limitadas.
5. Verifique os dois lados da mudança
O consumidor publica suas expectativas e o provedor verifica se consegue satisfazê-las. O processo precisa identificar versões: qual contrato, de qual consumidor, foi verificado contra qual implementação. Um resultado verde antigo não autoriza automaticamente uma versão nova.
Defina um bloqueio de entrega para incompatibilidades relevantes e um procedimento de exceção documentado. Se um teste falhar por mudança intencional, coordene a migração. Apagar o teste apenas para liberar o deploy retira justamente a proteção que ele oferecia.
6. Evolua de forma compatível
Adicionar um campo opcional costuma ser menos arriscado do que remover um campo utilizado, mas o efeito depende dos consumidores. Alguns rejeitam propriedades desconhecidas. Renomeações, alterações de significado e novos valores de enum exigem atenção mesmo quando o tipo formal permanece igual.
Uma estratégia de transição pode manter o campo antigo enquanto o novo é adotado, monitorar uso e estabelecer um prazo acordado para retirada. A versão da API não substitui esse trabalho: duas versões sem política de suporte apenas duplicam a manutenção.
7. Exemplo hipotético de quebra evitada
Um portal usa saldoDisponivel para habilitar uma ação. O backend quer retornar nulo enquanto um cálculo está pendente. O contrato do portal espera um número. A verificação detecta a incompatibilidade antes da publicação.
A solução pode ser ensinar o consumidor a representar “em cálculo”, acrescentar um campo de estado e coordenar a transição. Substituir nulo por zero apenas para satisfazer o teste pode introduzir uma mentira de negócio. O contrato expõe a decisão; não deve escondê-la.
8. Preserve outros tipos de teste
Testes de contrato não confirmam desempenho sob carga, autorização completa, comportamento do navegador ou correção de todas as regras. Mantenha testes unitários para lógica, integração para componentes reais e alguns fluxos ponta a ponta para jornadas críticas.
Para segurança, a OWASP API Security Top 10 oferece um inventário de riscos que pode orientar cenários adicionais. Conformidade de formato não impede acesso indevido a um objeto de outra empresa.
Checklist de adoção
- Inventariar consumidores e responsáveis.
- Selecionar uma integração com incidentes ou mudanças frequentes.
- Documentar campos realmente utilizados.
- Cobrir sucesso e erros relevantes.
- Criar estados de teste reproduzíveis.
- Relacionar contratos e verificações a versões.
- Integrar a decisão de compatibilidade à entrega.
- Definir migração e retirada de comportamentos antigos.
Checklist para usar com sua equipe
Baixe o checklist editável em CSV e registre responsáveis, verificações e observações da implantação.
Perguntas frequentes
Basta validar um esquema JSON?
Isso ajuda, mas não cobre necessariamente expectativas de interação, semântica e estados relevantes para o consumidor.
Preciso testar todos os campos?
Teste o que o consumidor utiliza e as invariantes necessárias. Acoplamento desnecessário torna a evolução mais difícil.
Isso elimina homologação integrada?
Não. Reduz determinadas incompatibilidades e torna a homologação mais focada, mas outros riscos continuam existindo.
Para reduzir quebras entre sistemas da empresa, avalie suas integrações com a A2CR.
Autoria: Agência A2CR. Revisão editorial: 9 de novembro de 2026. Roteiro de adoção e exemplo elaborados pela A2CR; referências indicadas junto aos conceitos correspondentes.
