A compilação fica vermelha, alguém clica em “executar novamente”, ela é aprovada e todos seguem em frente. Parece inofensivo, mas testes instáveis destroem lentamente o que há de mais valioso em um conjunto de testes: a confiança das pessoas nele. Quando as falhas geralmente são barulhentas, bugs reais também são eliminados.

Este guia aborda por que os testes ficam instáveis ​​e como corrigir cada causa adequadamente. Executamos as demonstrações de tempo e estado compartilhado no Python 3.13, e os números mostrados vêm dessas execuções. São pequenas demonstrações projetadas para facilitar a visualização da instabilidade, de modo que suas próprias taxas de falha serão diferentes.

O que é um teste instável?

Um teste instável fornece resultados diferentes no mesmo código. Ele passa em uma execução e falha na próxima, mesmo que nada tenha mudado no produto. O teste pode estar errado ou o código pode conter um bug intermitente real. Essa segunda possibilidade é exatamente a razão pela qual você não deve simplesmente descartá-los.

Por que os testes instáveis são tão caros

• Confiança perdida. Quando as pessoas presumem que vermelho significa “provavelmente esquisito”, elas param de investigar falhas reais.
• Perda de tempo. Os desenvolvedores passam horas reexecutando pipelines e examinando falhas que não têm nada a ver com suas alterações.
• Entrega mais lenta. Fusões e liberações aguardam repetições, minando o ponto de CI/CD.
• Bugs ocultos. As condições de corrida no produto podem parecer ruídos de teste, e são essas que prejudicam a produção.

Resumo das causas comuns

Causa 1: tempo e sono fixo

Esta é a causa mais comum. Um teste pressupõe que o trabalho em segundo plano será concluído após um atraso fixo. Para ver o efeito, escrevemos um pequeno teste no qual o trabalho leva até 2 ms, enquanto o teste espera apenas 1 ms antes de verificar:

def flaky_timing():
    result = {}
    def work():
        time.sleep(random.uniform(0, 0.002))
        result["done"] = True
    threading.Thread(target=work).start()
    time.sleep(0.001)        # hope it has finished
    assert result.get("done")

A solução é aguardar a condição real, com um limite superior generoso:

def fixed_timing():
    result = threading.Event()
    def work():
        time.sleep(random.uniform(0, 0.002))
        result.set()
    threading.Thread(target=work).start()
    assert result.wait(timeout=1)   # continues as soon as it is ready

Executamos cada versão 200 vezes:

O resultado é mais do que apenas confiabilidade. A versão fixa avança no momento em que o trabalho é concluído, por isso geralmente também é mais rápida. Um sono mais longo faria com que a primeira versão falhasse com menos frequência, mas cada execução seria mais lenta e ainda poderia falhar em uma máquina de CI ocupada.

Nos testes de navegador, o mesmo princípio se aplica. Use a espera automática de Playwright ou Esperas de Selenium explícitas, em vez de time.sleep:

# Playwright: retries until true or a timeout is reached
expect(page.get_by_text("Order placed")).to_be_visible()

# Selenium: an explicit wait for a condition
WebDriverWait(driver, 10).until(
    EC.visibility_of_element_located((By.ID, "confirmation"))
)

Causa 2: estado compartilhado e ordem de teste

Quando os testes compartilham dados, um pode afetar o outro, e o resultado depende da ordem em que são executados. Esses dois testes usam uma lista compartilhada:

store = []

def test_add():
    store.append("x")
    assert len(store) == 1

def test_empty():
    assert store == []

Nossa execução confirmou isso, e é por isso que uma suíte pode passar meses e depois quebrar quando alguém adiciona execuções paralelas ou um plugin de pedido aleatório. A cura é o isolamento:

• Forneça dados atualizados a cada teste, usando um acessório que os configura e limpa. Nosso tutorial pytest mostra como.
• Crie registros exclusivos, como um email com um sufixo aleatório, no lugar de um “usuário de teste” compartilhado.
• Envolva testes de banco de dados em uma transação e reverta-a, onde sua configuração permitir.
• Execute testes regularmente em ordem aleatória, para que esses problemas apareçam mais cedo.

Causa 3: Datas, fusos horários e aleatoriedade

Um teste que passa a semana toda pode ser reprovado no sábado, à meia-noite ou no último dia do mês. Faça do tempo uma entrada, em vez de ler o relógio dentro da sua lógica:

def is_weekend(today=None):
    today = today or datetime.date.today()
    return today.weekday() >= 5

is_weekend(datetime.date(2026, 11, 7))   # True  (a Saturday)
is_weekend(datetime.date(2026, 11, 9))   # False (a Monday)

Esses testes dão a mesma resposta em qualquer dia. Da mesma forma, defina uma semente fixa para valores aleatórios em testes e registre-a ao usar dados aleatórios para poder reproduzir uma falha. Não assuma uma ordem específica de conjuntos, dicionários de fontes externas ou consultas de banco de dados sem ORDER BY.

Causa 4: Seletores frágeis

Um teste que encontra um botão com div:nth-child(3) > span quebra com qualquer ajuste de layout e pode falhar apenas para alguns tamanhos de tela ou variantes. Prefira localizadores baseados no que os usuários veem ou atributos de teste dedicados. Nosso guia para Localizadores de dramaturgos explica a ordem para testá-los. As animações são outra fonte frequente de problemas, então considere desativá-las em ambientes de teste.

Causa 5: Serviços e redes externas

Se um teste chamar um provedor de pagamento real ou uma API de terceiros, seu resultado dependerá do tempo de atividade e dos limites de taxa de outra pessoa. Simule essas chamadas para a maioria dos testes e mantenha um pequeno número de verificações de contrato separadas em relação ao serviço real, para que você ainda saiba se ele mudar. Nosso guia para testes de unidade versus testes de integração explica como dividi-los.

Como diagnosticar um teste escamoso

1. Confirme. Execute o teste várias vezes sem alterações. Com o pytest, um simples loop de shell funciona, e um plugin como pytest-repeat fornece --count=100.
2. Registre evidências. Salve logs, capturas de tela e rastreamentos para cada falha. O visualizador de rastreamento do Playwright é particularmente útil aqui.
3. Enfatize as condições. Execute-o com CPU limitada, em paralelo ou em ordem aleatória. Fazê-lo falhar com mais frequência torna mais fácil estudar.
4. Teste sozinho. Se ele sempre passar sozinho, mas falhar no conjunto, suspeite do estado compartilhado.
5. Procure padrões. Verifique quais máquinas, horários do dia e testes vizinhos estão envolvidos.
6. Verifique o produto. Pergunte honestamente se isso poderia ser uma condição de corrida real em sua aplicação.

As tentativas automáticas são uma solução?

As novas tentativas são uma rede de segurança útil a curto prazo e não são uma cura. Uma única nova tentativa automática no CI pode manter o trabalho em andamento enquanto você investiga, mas um teste que precisa de uma nova tentativa para ser aprovado ainda está lhe dizendo algo. Pior ainda, um bug real e intermitente do produto que falha 20% das vezes geralmente passa por uma nova tentativa despercebido.

Use novas tentativas com estas regras: limite-as a uma ou duas, registre todos os testes que precisaram de uma e trate essa lista como sua lista de tarefas pendentes. Um teste relatado como “aprovado na nova tentativa” deve contar como um problema a ser investigado, e não como um sucesso.

Um processo de equipe para testes instáveis

1. Avalie. Rastreie quais testes falham e depois passe o mesmo commit. Muitas ferramentas de CI e repórteres de teste podem mostrar isso.
2. Quarentena. Retire um teste instável confirmado da execução de bloqueio, para que ele pare de atrapalhar a todos, mas continue executando-o e monitorando-o.
3. Atribua um proprietário e um prazo. Uma quarentena sem prazo vira apenas um cemitério.
4. Corrija ou exclua. Se não vale a pena corrigir um teste, remova-o e verifique se sua cobertura ainda existe em outro lugar.
5. Prevenir. Execute novos testes várias vezes antes de mesclar. Um teste que falha uma vez em cinquenta execuções é melhor detectado agora do que em seis meses.

Trate um teste instável como um bug com prioridade, e não como ruído de fundo. A gravidade e a prioridade também se aplicam aqui, conforme abordado em gravidade versus prioridade. Se a instabilidade for generalizada, leia sobre erros mais amplos de automação de testes e considere se você tem muitos testes no nível do navegador.

Considerações finais

Os testes instáveis ​​parecem aleatórios, mas raramente são. Quase todos se resumem a uma suposição sobre tempo, ordem, dados ou ambiente que nem sempre é verdadeira. Escolha o teste que falha com mais frequência em seu pipeline esta semana. Execute-o cinquenta vezes, encontre a suposição e corrija-a para sempre. Uma solução real ensina a uma equipe mais do que cem repetições.

Perguntas frequentes

Continue aprendendo