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.
Build the exact artifact that CI produced. Download it if you must. Serve that artifact locally with a simple static file server, not with Vite or Webpack dev middleware. Use the same environment variables that CI injected. Match the browser version precisely. Run it in the same mode, headed or headless, because focus events, media queries, and autoplay policies still diverge between the two in subtle ways. If your CI uses a Docker container, run the same image locally. Remove your personal browser profile entirely.
When the local reproduction finally fails, you have a real debugging session. Until then, you are chasing shadows.
Stop Sleeping, Start Waiting
The most common response to a flaky browser test is to add delay. Wait five seconds. Wait ten. This is not a fix. It is a surrender. Arbitrary delays slow your suite, create false confidence, and still fail under load when the network hiccups.
Instead, wait for evidence of state. If a notification should appear after a form submission, do not wait for time to pass. Wait for a specific notification ID to exist in the DOM. If a counter should increment, wait for the text to change values. If a loading state blocks interaction, wait for the loading marker to disappear. If you are working with a WebSocket or server-sent events, wait for the network stream to produce a specific event.
Explicit waits turn your test from a guessing game into a contract. The test says: "I will proceed once the application confirms it is ready." That is far stronger than saying, "I will proceed once enough seconds have passed."
Hydration and the Disappearing Button
In modern React applications, hydration causes a specific class of failures that local dev servers often mask. The server sends HTML. React boots up in the browser and attaches event listeners. During that window, your test might click a button. React then replaces or restructures that DOM node during hydration. The element handle your test framework was holding now points to a detached node, and you get an error about interacting with a removed element.
The fix is not to write a more complex selector that digs deeper into the component tree. The fix is to look for readiness signals. Wait until a root element gains a hydrated attribute or a known data property. Wait for a skeleton loader to disappear. Wait for a client-side event handler to become active. Let the application announce that it is stable before you fire clicks.
Hidden Culprits: Dependencies and Third-Party Scripts
Sometimes the environment changes even though your application code did not. A transitive update in a small utility library, three levels deep in your node_modules, can alter browser behavior. It might change how promises resolve, how styles get injected, or how mocks intercept requests. When tests begin failing after a routine dependency update, record your package manager version and the lockfile checksum. You need to know whether you are looking at the same tree you were last week.
Third-party scripts are another frequent saboteur. Analytics trackers, payment SDKs, and chat widgets load asynchronously. They inject iframes, shift layout, or steal focus at moments your test does not expect. In CI, these scripts might load more slowly, or they might fail to load entirely because of network restrictions, causing your application to follow a different error-handling path. Log which third-party resources loaded and their HTTP status. If a payment iframe takes three seconds to mount in CI but loads instantly on your fast local connection, your "element not clickable" error suddenly has a clear cause.
And "element not clickable" is never a diagnosis. It is a symptom. Treat the cause.
Build an Evidence Kit
Every CI failure should be actionable. A stack trace alone is not enough. You need an evidence kit that lets another engineer, or yourself next month, reconstruct what happened.
Keep screenshots and video recordings from the failing run. Capture the full browser console output, not just errors but warnings too. Log network failures, including 404s, CORS rejections, and dropped connections. Preserve the build IDs and feature flags that were active. Take a DOM snapshot at the exact moment the assertion failed. A snapshot lets you inspect the HTML structure after the fact, rather