A Shopify chamou a escotilha de UNSAFE_ e saiu de 50% para 98%

Algumas semanas depois de a Shopify promover uma nova API de testes ponta a ponta em mobile para o CI bloqueante, a suíte do aplicativo Shopify registrou 98% de estabilidade, medida como sucessos individuais de teste divididos pelo total de execuções. Com a API antiga, o número era 50%.

O número anterior à reescrita é o mais útil dos dois. Em 50%, a suíte “havia chegado ao ponto de bloquear mais PRs bons do que ruins”, escreve Michael Garfinkle, e “ficou tão ruim que tivemos que tirar a suíte E2E dos nossos PR checks por completo”. Uma suíte de testes fora do CI é uma suíte pela qual ninguém responde.

O que faz o texto valer duas leituras é o diagnóstico que antecedeu a reescrita. O time de Garfinkle vinha tratando instabilidade como problema de manutenção: tirar a água do barco, corrigir os piores casos, repetir. A conclusão depois desse ciclo: “O problema não era que fôssemos ruins em tirar a água da suíte; era que o próprio framework continuava criando as mesmas falhas. Nenhuma quantidade de limpeza resolveria isso. Tínhamos que consertar o sistema subjacente.”

O framework fabricava as falhas. Então eles trocaram o framework, e as decisões de projeto que tomaram generalizam muito além de teste mobile.

Mecânica 1: Torne o caminho inseguro caro de nomear

É fácil construir uma guarda como proibição. A opção ruim some, e o engenheiro que realmente precisa dela contorna o framework inteiro, o que joga a gambiarra para fora do alcance da sua ferramenta.

A Shopify escolheu o outro caminho. As escotilhas de emergência existem e são batizadas para constranger: “Escotilhas de emergência recebem o prefixo UNSAFE_. Existem opções que passam por cima das guardas (como timeouts customizados ou injeção de script), mas o nome delas desencoraja o uso. UNSAFE_timeoutInSeconds em um teste é um sinal para revisão.”

Três propriedades saem dessa única convenção. O desvio continua dentro do framework, em vez de empurrar a pessoa para fora dele. O desvio é rastreável por grep, então a contagem de chamadas com UNSAFE_ vira métrica de verdade, que o time pode ver subir ou descer. E o desvio é legível no diff, então a revisão pega o caso sem linter, sem documento de política e sem reunião.

Essa é a parte que transfere direto. Se o seu repositório tem uma operação perigosa que ocasionalmente é legítima, mantenha a operação e troque o nome neutro. Renomeie de modo que usá-la seja um ato público. force_delete soa como uma opção. UNSAFE_force_delete_bypasses_audit soa como algo que você vai precisar defender na revisão.

Mecânica 2: Valide o validador

A segunda decisão ataca o modo de falha que torna suítes E2E pouco confiáveis mesmo quando estão verdes. Na nova API da Shopify, “todo passo carrega uma asserção. Você não pode tocar, esperar ou digitar sem declarar o que a tela deve mostrar depois. Se o app sai do estado esperado, o teste falha no passo em que a realidade divergiu, e não quatro ações adiante, quando algo mais abaixo quebra.”

Asserção por passo, sozinha, ainda deixaria a porta aberta: uma asserção sempre verdadeira afirma nada. Então a API acrescenta uma regra que governa as próprias asserções, dita assim no artigo: “uma asserção deve ser falsa antes da ação e verdadeira depois.”

Essa regra é a peça interessante. Ela coloca a verificação tautológica do lado errado de uma regra. Se a pessoa afirma algo que já era verdade antes do toque, a asserção viola a regra e o teste falha, em vez de entrar na suíte para passar eternamente sem exercitar coisa alguma. O framework aqui checa o check, uma camada acima do app.

Quem já auditou uma suíte verde e encontrou parte dela afirmando constantes sabe quanta dívida silenciosa essa regra quita. E a forma se aplica muito fora de teste. Um alerta de monitoramento que nunca disparou, um motor de política que nunca negou, um agente de revisão que nunca bloqueou: cada um é uma asserção que ninguém provou capaz de ficar vermelha.

Mecânica 3: Condicione a promoção a execuções repetidas

Uma única execução verde prova que o teste consegue passar. Não prova que ele vai continuar passando. A Shopify colocou um pipeline entre as duas coisas: “Antes de um novo teste ser admitido na suíte bloqueante, um pipeline dedicado o executa várias vezes e o rejeita se ele falhar acima de um limiar definido.”

O artigo omite o valor do limiar. Escolher um para o seu repositório é trabalho empírico, então copie a estrutura em vez do número. Entrar na suíte bloqueante vira uma promoção com exigência de estabilidade demonstrada, em vez de um padrão que todo teste novo herda só por existir. Isso inverte a dinâmica anterior, em que a suíte se degrada em silêncio porque cada teste novo entra com uma execução verde e só sai depois de ter queimado horas de engenharia suficientes para justificar a discussão.

Por que isso é uma história sobre agentes

Garfinkle lista um objetivo de projeto incomum ao lado dos objetivos humanos: a API deveria ser “legível o bastante para agentes de IA escreverem. A superfície é pequena e a gramática é previsível, o que significa que tanto humanos quanto ferramentas de IA produzem testes corretos de primeira com mais frequência.”

Essa frase é a razão de o texto morar ao lado do nosso trabalho sobre governar o harness. A corretude aqui vem de encolher a gramática até que a construção ruim fique difícil de expressar. Prompt melhor e revisão mais dura atuam depois do fato; a gramática atua antes. Um agente escrevendo contra uma API em que todo passo exige uma asserção e em que a escotilha se chama UNSAFE_ produz saída auditável por padrão, porque a API deixou pouquíssimo espaço para outra coisa.

O texto Towards self-driving codebases, da Detail, defende essa tese diretamente: bases de código devem ser tornadas legíveis para os agentes que trabalham nelas, invertendo a direção usual da adaptação. Duas ressalvas acompanham a citação. O post não traz estatística própria, não tem assinatura visível e não tem data de publicação na página. E a Detail vende ferramenta exatamente na categoria que recomenda, o que a torna um enquadramento para pegar emprestado, não evidência para se apoiar. A evidência vem da Shopify: uma reescrita real de API, um número de estabilidade antes e depois, e uma suíte de volta ao CI bloqueante.

O resto do stack da Shopify vale registro pelo tanto que é comum. PaddleOCR lê o texto na tela. OpenCV casa ícones usando variantes em escala de cinza e com cor invertida, em múltiplos tamanhos, com adjacência para desambiguar elementos duplicados. O stack que a Shopify descreve é OCR e casamento de template de prateleira, sem modelo próprio. A restrição que produziu o número mora na superfície da API, que é o mesmo argumento que fizemos sobre o ambiente de avaliação ser produção.

Faça isso agora

Abra a API contra a qual seus agentes e seus engenheiros mais novos escrevem com mais frequência e responda duas perguntas com um grep, não com opinião.

Primeira: qual é a coisa mais perigosa que essa API permite a quem chama, e como ela se chama? Se a opção perigosa tem nome tão neutro quanto a opção segura, renomeie ainda esta semana. Coloque prefixo, deixe o nome longo, faça a chamada aparecer na revisão. Você mantém a operação disponível e cobra um preço por ela em revisão.

Segunda: qual das suas verificações automáticas nunca falhou? Puxe o histórico das suas asserções, dos seus alertas e dos seus gates de política, e liste todos que estão verdes desde que foram escritos. Cada um deles está por validar até que você consiga mostrá-lo vermelho. A regra da Shopify entrega o teste: force a precondição a ser falsa e confirme que a verificação percebe.

Os dois exercícios levam uma tarde. Nenhum exige reescrever um framework, que é a versão cara desta lição, a que a Shopify pagou e publicou. Os 50% deles são o preço de descobrir tarde que quem produzia as falhas era o framework, não os testes.

---

Fontes

• Shopify Engineering (Michael Garfinkle). “How we raised mobile end-to-end test stability to 98%.” Agosto de 2026.
• Detail (blog da empresa, sem data na página). “Towards self-driving codebases.” 2026.

A Victorino ajuda times de engenharia a redesenhar as superfícies de API contra as quais seus agentes escrevem, para que a saída correta seja o caminho mais barato: contato@victorino.com.br | www.victorino.com.br