Uma integração pode passar nos testes unitários e ainda falhar quando o provedor muda um campo, revoga uma credencial ou se comporta de outra forma no sandbox. Uma boa estratégia combina verificações locais determinísticas, contratos explícitos e uma pequena dose de evidência ao vivo, sob controle. Nenhuma camada, sozinha, prova tudo sobre a relação entre os sistemas.
Comece separando o código que você controla do comportamento que pertence a outra organização. Testes unitários devem ser numerosos: mapeamento, validação, repetição e idempotência são decisões suas. Testes de contrato tornam explícitas as suposições entre consumidor e provedor. Depois vêm verificações mais amplas em ambiente de homologação e, por fim, uma sonda pequena de produção para detectar problemas de credencial, rota ou configuração ausentes nos ambientes de teste.
Um contrato não é uma cópia do esquema inteiro do provedor. Registre as interações usadas pelo consumidor: método, caminho, campos relevantes da requisição, status e formato mínimo da resposta. Ferramentas de contrato orientadas pelo consumidor podem gerar essas expectativas a partir dos testes do cliente e permitir que o provedor as verifique na própria implementação. Escolha os critérios de comparação deliberadamente: exemplos exatos ajudam com identificadores e enums; correspondências flexíveis podem servir para datas e IDs gerados.
O contrato não prova semântica de negócio, disponibilidade, nem as necessidades de todos os consumidores. Ele verifica compatibilidade com suposições declaradas. Trate mudanças como mudanças de API, publique versão e ambiente e exija verificação bem-sucedida do provedor para a versão em produção.
| Camada | Boa evidência para | Não comprova |
|---|---|---|
| Unitário | Transformações locais, retries e casos de borda | Compatibilidade no fio ou comportamento remoto |
| Contrato | Compatibilidade das suposições do cliente com provedor verificado | Disponibilidade, latência ou configuração real da conta |
| Sandbox | Credenciais e requisições representativas de ponta a ponta | Dados, limites, integrações ou comportamento idênticos aos de produção |
| Sonda de produção | Alcance atual e uma transação segura e limitada | Todos os fluxos, correção em escala ou ausência de falhas ocultas |
Sandboxes podem omitir recursos, usar dados artificiais ou reagir de forma diferente à limitação de taxa. Registre essas lacunas e cubra localmente o que for possível. Um teste verde no sandbox não deve virar uma afirmação vaga de que “a integração foi testada”. Mantenha um registro curto de evidências: ambiente, escopo das credenciais, cenários e exclusões conhecidas.
Para APIs externas, teste timeout, conexão interrompida, limite de requisições, credencial expirada, payload inválido, entrega duplicada, loop de paginação e sucesso parcial. Verifique o que o usuário ou operador consegue observar: retries limitados, gravações idempotentes, visibilidade em dead-letter, erros úteis e preservação dos dados de origem. Relógios e adaptadores de transporte injetáveis tornam esses cenários determinísticos e independentes da disponibilidade do fornecedor.
Use fixtures realistas sem dados pessoais. Remova tokens, identificadores e campos sensíveis dos exemplos versionados. Mantenha contratos pequenos para que revisores compreendam a promessa descrita.
Execute testes unitários e de contrato a cada alteração. Rode suítes de sandbox de forma agendada ou antes de um release quando o ambiente estiver estável, em vez de bloquear todo pull request por uma indisponibilidade externa. Uma verificação controlada em produção deve ser somente leitura sempre que possível, usar uma conta dedicada de baixa permissão e alertar sobre falhas persistentes, não sobre um timeout isolado.
Diferencie teste reprovado de dependência externa indisponível. Registre checagens bloqueadas ou ignoradas explicitamente. Guarde segredos no sistema protegido da CI, limite seu escopo e impeça que cabeçalhos ou corpos sejam impressos nos logs.
Uma equipe pequena pode começar pelos testes de mapeamento e idempotência, adicionar contratos para consumidores críticos, documentar um checklist de sandbox e criar uma sonda sintética para o caminho de leitura mais importante. Acompanhe a idade da verificação do contrato, o sucesso no sandbox, a disponibilidade da sonda e incidentes causados por mudanças de esquema. São indicadores de confiança e operação, não uma nota universal de qualidade.
Para padrões relacionados, veja confiabilidade de webhooks, chaves de idempotência e limites de API.
A pirâmide de testes de integração é um mapa de responsabilidade e incerteza. Mantenha a maioria dos testes rápidos e determinísticos, use contratos para compatibilidade explícita, trate sandboxes como evidência parcial e reserve produção para sinais seguros e restritos. O objetivo não é simular toda a internet na CI, mas entender qual falha cada camada consegue encontrar antes do cliente.