Como testar caminhos de erro e timeouts em chamadas de saída

Objetivo

Testar o código que roda quando uma dependência falha com o mesmo rigor do caminho feliz. Esse código raramente é executado durante o desenvolvimento e roda sem parar durante incidentes, justamente quando menos se pode arcar com a descoberta de que ele nunca funcionou.

Pré-requisitos

As chamadas de saída passam por um cliente ou adaptador injetável; os timeouts são configuráveis por chamada; o framework de testes consegue verificar exceções e a saída de logs ou métricas.

Passos

1. Para cada dependência de saída, liste as classes de falha: conexão recusada, conexão reiniciada (reset), timeout na conexão, timeout na leitura, HTTP 5xx, HTTP 429 com Retry-After, corpo malformado, corpo truncado, corpo lento. Cada uma vira pelo menos um teste com nome próprio.
2. No nível de unidade, injete a falha com um test double. O unittest.mock do Python documenta o side_effect: uma exceção é lançada quando o mock é chamado, e um iterável devolve resultados sucessivos; assim, "falha duas vezes e depois funciona" se configura em uma linha.
3. Verifique o comportamento que o projeto promete, e não o texto da exceção: o chamador para após N tentativas, espera com backoff e jitter, lança um erro tipado, registra uma métrica, não deixa escrita parcial e devolve a conexão ao pool.
4. Teste o próprio timeout com um relógio falso ou com um servidor que nunca responde: um socket em escuta que aceita a conexão e permanece em silêncio exercita o timeout de leitura; um endereço não roteável exercita o timeout de conexão. Mantenha pequeno o timeout em teste para que o teste continue rápido.
5. No nível de integração, coloque um proxy de injeção de falhas entre o serviço e a dependência. O README do Toxiproxy descreve toxics que adicionam latência com jitter, limitam a largura de banda, interrompem os dados e fecham a conexão após um atraso (timeout), simulam um reset de TCP (reset_peer) ou atrasam o fechamento (slow_close), cada um ligado e desligado por meio de uma API HTTP; assim, um teste pode ativar uma falha, executar o cenário e desativá-la.
6. Teste a limpeza após a falha: uma requisição que estourou o timeout não pode manter uma conexão do pool nem um lock; leia as estatísticas do pool ao fim do teste.
7. Adicione um teste para cada incidente passado, reproduzindo seu gatilho, e mantenha-o.

Resultado esperado

Toda classe de falha tem um teste nomeado; alterar um timeout ou uma política de retry quebra um teste, em vez de surpreender quem opera o sistema.

Limites e base de verificação

Mocks testam a lógica do chamador, não o comportamento da biblioteca real sob um timeout real; mantenha pelo menos um teste por cliente com um socket real. Testes com proxy são mais lentos e exigem orquestração no CI. Este é um protocolo proposto; nenhuma medição é alegada.