> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/learn/reliability-and-flakiness/flaky-tests.md). # Stabilize screenshots and fix flaky visual tests A playbook for tackling visual flakiness, with detection, ignoring noisy changes, and stabilization strategies. The most reliable visual test suite is one where flakiness is fixed at the source. This playbook covers the strategies that make screenshots deterministic — from waiting for loading to freezing dynamic values. {% hint style="info" %} Argos also detects and filters flakiness for you: see [Flaky test detection](/docs/learn/reliability-and-flakiness/flaky-test-detection.md) for flaky badges, ignore, and auto-ignore, and the [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard.md) for a project-wide ranking. {% endhint %} ### Common causes Visual flakiness usually stems from one of the following: * **Dynamic content**: Ads, user-generated content, or other data that changes between runs. * **Asynchronous loading**: Elements or styles that render at inconsistent times. * **Rendering differences**: Browser, OS, or device variations that alter visual output. * **External dependencies**: Reliance on third-party systems that introduce variability. * **Animations and transitions**: Unhandled motion captured mid-frame. * **Resolution and scaling**: Screen size or pixel density differences between environments. ### Best practices for stable screenshots Follow these practices — each one targets a common cause above: {% hint style="info" %} Most stabilization is automatic. The Argos SDK stabilizes every screenshot by default — waiting for `aria-busy`, fonts, and images to settle, forcing font antialiasing, hiding carets and scrollbars, and more. You can customize or disable any of it through the [`stabilize` option](/docs/reference/playwright.md). The practices below cover what the SDK can't infer on its own, such as which elements are loaders or which values are dynamic. {% endhint %} * **Wait until the page is ready before capturing.** Mark loading elements with `aria-busy` so `argosScreenshot()` waits for them. → [Wait for loading](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-loading.md) * **Wait for CSS background images to load.** Flag elements with `data-visual-test-wait-bg-img` so Argos waits for their backgrounds — or extend the check to the whole page. → [Wait for background images](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-background-images.md) * **Freeze animated GIFs.** GIFs are paused on their first frame by default so they don't capture a random frame on each run. → [Pause animated GIFs](/docs/learn/reliability-and-flakiness/flaky-tests/pause-gifs.md) * **Make dates and times deterministic.** Hide or freeze any value that changes between runs. → [Stabilize date & time](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-date-and-time.md) * **Reduce text rendering differences.** Disable subpixel text and font hinting so glyphs vary less between machines. → [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering.md) * **Run the same environment everywhere, and tame rendering quirks.** Use the same OS and browser locally and on CI, and smooth over properties like `border-radius`. → [Browser glitches](/docs/learn/reliability-and-flakiness/flaky-tests/browser-glitches.md) * **Mask or hide unavoidable dynamic content.** Use `data-visual-test` attributes for anything you can't stabilize at the source. → [Argos helpers](/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers.md) {% hint style="success" %} **New to visual testing?** Start with [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering.md) and [Wait for loading](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-loading.md). Together they prevent the large majority of flaky screenshots. {% endhint %} ### Emphasis on accessibility At Argos, we advocate for accessibility-focused end-to-end testing. Improving accessibility (semantic markup, `aria-busy`, predictable focus states) not only supports users with disabilities but also makes tests more deterministic and less prone to flakiness. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://argos-ci.com/docs/learn/reliability-and-flakiness/flaky-tests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.