It starts with a Slack message. The build is red. You scroll through the failures, frown, and rerun the same test on your laptop. Green. You retry the CI job. Maybe it was a blip. The failure comes back, stubborn and repeatable on the server but invisible to you.
A browser test that fails in CI yet passes locally is more than an annoyance. It breeds distrust. Teams begin to blame timing. They push temporary fixes that never leave. A setTimeout here, a .wait(5000) there. The suite slows down. The failures keep returning. Those flaky tests harden into permanent fixtures, and eventually everyone begins treating a red pipeline as background noise.
That is dangerous. You do not want a test suite that cries wolf.
CI Is Not Broken; It Is Just Different
CI environments are not random. They are deterministic. The problem is that they are deterministic about a system that is not your MacBook or your Linux workstation. Your local setup hides differences that a clean CI runner exposes immediately.
Think about how many moving parts diverge. Your local machine might run a development server with hot module reloading, while CI builds a production artifact with tree shaking and minification. That alone can strip code paths or alter execution order. Dependency trees shift. A lockfile that looks identical can resolve differently if the package manager version varies by a single minor release. Network sequences change. Your office Wi-Fi might resolve a staging API in one hop; the CI runner might hit a different cluster behind a load balancer, introducing latency you never see.
Browsers themselves behave differently across environments. Your local Chrome carries extensions, cached credentials, persistent local storage, and a GPU with hardware acceleration. CI starts from a blank profile on every run. Browser lifecycles diverge. Rendering paths diverge. Fonts that exist on your system get substituted in CI. Viewport sizing and device pixel ratios vary, which can flip responsive breakpoints or alter lazy-loading behavior.
These gaps are real. They are mechanical. Pretending they are random does not make them go away.
Preview Environments Lie
Preview environments compound the problem. They are useful for human review, but they are not production. They often point to api-staging instead of the real API host. Feature flags evaluate to true for every experiment, hiding conditional logic that production executes. Authentication might skip a step or inject a mock token. Cookies might use relaxed policies. The dataset could be a thin slice, ten rows instead of ten thousand, which means pagination, search ranking, or virtualization logic never gets exercised.
If your test passes against a preview URL but fails in production, or vice versa, the test is not the bug. The environment is.
Log Before You Guess
When a failure first appears, resist the instinct to tweak the test and hope. Stop guessing. You need to freeze the context so you can compare a passing run against a failing one.
Log the obvious suspects. Record the page URL at the moment of failure, the build ID, and the commit SHA. Note the active feature flags. Capture the API host, the exact browser version, and the viewport size. These details turn a mysterious failure into a reproducible condition.
Do not rely only on screenshots. Two pages can look pixel-identical while running completely different JavaScript. A screenshot will not tell you that the CI bundle included an extra polyfill or that the local bundle skipped a chunk because it was already in your browser cache.
Also remember that opening DevTools changes timing. DevTools can defer garbage collection, alter network prioritization, and disable certain rendering optimizations. A test that passes while you are inspecting the DOM might fail the moment you close the panel and run it headless. The debugger is a useful tool, but it is not a neutral observer.
Recreate the Crime Scene
If you want to reproduce the failure accurately, you cannot simply run your local development server and hope for the best. You need to replicate the_CI's_ exact conditions.
Construa o artefato exato que o CI produziu. Baixe-o, se necessário. Sirva esse artefato localmente com um servidor de arquivos estáticos simples, não com o middleware de desenvolvimento do Vite ou Webpack. Use as mesmas variáveis de ambiente que o CI injetou. Corresponda à versão do navegador com precisão. Execute-o no mesmo modo, headed ou headless, porque eventos de foco, media queries e políticas de autoplay ainda divergem entre os dois de maneiras sutis. Se o seu CI usa um contêiner Docker, execute a mesma imagem localmente. Remova completamente o seu perfil pessoal de navegador.
Quando a reprodução local finalmente falhar, você terá uma sessão de depuração real. Até lá, você estará perseguindo sombras.
Pare de Dormir, Comece a Esperar
A resposta mais comum para um teste de navegador instável é adicionar atraso. Espere cinco segundos. Espere dez. Isso não é uma correção. É uma rendição. Atrasos arbitrários tornam sua suíte mais lenta, criam uma falsa confiança e ainda falham sob carga quando a rede oscila.
Em vez disso, espere por evidências de estado. Se uma notificação deve aparecer após o envio de um formulário, não espere o tempo passar. Espere que um ID de notificação específico exista no DOM. Se um contador deve incrementar, espere que o texto mude de valor. Se um estado de carregamento bloqueia a interação, espere que o marcador de carregamento desapareça. Se você estiver trabalhando com um WebSocket ou server-sent events, espere que o fluxo de rede produza um evento específico.
Esperas explícitas transformam seu teste de um jogo de adivinhação em um contrato. O teste diz: "Eu prosseguirei assim que a aplicação confirmar que está pronta". Isso é muito mais forte do que dizer: "Eu prosseguirei assim que passarem segundos suficientes".
Hidratação e o Botão que Desaparece
Em aplicações React modernas, a hidratação causa uma classe específica de falhas que os servidores de desenvolvimento locais costumam mascarar. O servidor envia o HTML. O React inicia no navegador e anexa os ouvintes de eventos. Durante esse intervalo, seu teste pode clicar em um botão. O React então substitui ou reestrutura esse nó do DOM durante a hidratação. A referência ao elemento que seu framework de teste estava segurando agora aponta para um nó desvinculado, e você recebe um erro sobre a interação com um elemento removido.
A solução não é escrever um seletor mais complexo que mergulhe mais fundo na árvore de componentes. A solução é procurar por sinais de prontidão. Espere até que um elemento raiz ganhe um atributo de hidratação ou uma propriedade de dados conhecida. Espere que um skeleton loader desapareça. Espere que um manipulador de eventos do lado do cliente se torne ativo. Deixe a aplicação anunciar que está estável antes de disparar cliques.
Culpados Ocultos: Dependências e Scripts de Terceiros
Às vezes, o ambiente muda mesmo que o código da sua aplicação não tenha mudado. Uma atualização transitiva em uma pequena biblioteca utilitária, três níveis abaixo no seu node_modules, pode alterar o comportamento do navegador. Pode mudar como as promises são resolvidas, como os estilos são injetados ou como os mocks interceptam as requisições. Quando os testes começarem a falhar após uma atualização rotineira de dependências, registre a versão do seu gerenciador de pacotes e o checksum do lockfile. Você precisa saber se está olhando para a mesma árvore que estava na semana passada.
Scripts de terceiros são outro sabotador frequente. Rastreadores de analytics, SDKs de pagamento e widgets de chat carregam de forma assíncrona. Eles injetam iframes, deslocam o layout ou roubam o foco em momentos que seu teste não espera. No CI, esses scripts podem carregar mais lentamente ou podem falhar ao carregar inteiramente devido a restrições de rede, fazendo com que sua aplicação siga um caminho de tratamento de erro diferente. Registre quais recursos de terceiros foram carregados e seu status HTTP. Se um iframe de pagamento leva três segundos para montar no CI, mas carrega instantaneamente na sua conexão local rápida, seu erro de "elemento não clicável" subitamente tem uma causa clara.
E "elemento não clicável" nunca é um diagnóstico. É um sintoma. Trate a causa.
Construa um Kit de Evidências
Cada falha de CI deve ser acionável. Um stack trace sozinho não é suficiente. Você precisa de um kit de evidências que permita a outro engenheiro, ou a você mesmo no próximo mês, reconstruir o que aconteceu.
Mantenha capturas de tela e gravações de vídeo da execução que falhou. Capture a saída completa do console do navegador, não apenas erros, mas também avisos. Registre falhas de rede, incluindo 404s, rejeições de CORS e conexões interrompidas. Preserve os IDs de build e as feature flags que estavam ativas. Tire um snapshot do DOM no momento exato em que a asserção falhou. Um snapshot permite que você inspecione a estrutura HTML após o ocorrido, em vez de