# Best practices Visual regression helps you catch UI changes that functional checks may miss. It works best when the screen is predictable and the reference screenshot reflects a stable, intentional state. Use the practices below to keep visual regression useful instead of noisy. ### Prefer Element-Level Checks When Possible Use **element visual regression** when you want to verify a specific component, section, or control. This is usually the most stable option because: * it compares a smaller area * it is less affected by unrelated page changes * it makes failures easier to review Use **full-screen visual regression** only when page layout is the thing you actually want to validate. ### Keep the Screen State Stable Visual regression compares screenshots, so even small visual changes can affect the result. Before adding a visual regression step, make sure the page is in a repeatable state: * wait until content has finished loading * close popups, cookie banners, and tooltips unless they are part of the expected result * avoid transient UI states such as animations, loading spinners, hover states, and auto-rotating banners * make sure test data is predictable If the page changes every time the test runs, the screenshot will too. ### Use the Same Environment for Stable Results BugBug stores **reference screenshots per environment**. In practice, that means a reference is matched against the combination of: * browser * operating system * screen size * profile * run mode (cloud/local) If you run the same test in a different environment, BugBug may need a different reference screenshot for that environment. To keep results consistent: * review and approve references in the same environments you use for regular runs * avoid comparing local and cloud runs as if they were interchangeable * keep screen size and profile selection consistent across runs ### Understand the First Run When BugBug runs a visual regression step and **no reference screenshot exists for the current environment**, it automatically saves the current screenshot as the initial reference. That means the first run is used to establish the baseline. Because of that: * make sure the page looks correct before you accept that first run as your baseline * if the environment changes later, BugBug can create a separate reference for that environment ### Choose Max Difference Carefully `Max difference` defines how much visual change is allowed before the step fails. Keep it as low as you reasonably can: * use a low value for stable UI such as buttons, forms, labels, and layout containers * increase it only when small visual variation is expected and acceptable * avoid using a high value as a shortcut for unstable tests If the threshold is too low, you will get noisy failures. If it is too high, you can miss real regressions. The feature is not magic; it still depends on decent judgment. ### Use Project Settings for Consistent Behavior Visual regression comparison is influenced by project-level settings such as: * default max difference * pixel sensitivity threshold * anti-aliasing handling Use project defaults when you want consistent behavior across tests. Override the step-level max difference only when a specific step genuinely needs different tolerance. ### Review Failures Before Updating References When a visual regression step fails, review the screenshots before changing anything. Use **Review & fix** to decide whether the change is expected: * if the new look is correct, set the observed screenshot as the new reference * if the UI is allowed to vary slightly, increase the max difference * if the change is unexpected, keep the existing reference and investigate the regression Do not blindly replace references after every failure. That is just a more expensive version of ignoring the test. ### Avoid Common Sources of Flakiness Visual regression is most fragile when the UI includes content that changes outside your control. Common examples: * timestamps and relative dates * rotating banners or carousels * ads or third-party widgets * personalized content * lazy-loaded or virtualized sections * font rendering differences across environments * page-level screenshots with dynamic content above or below the fold If this kind of content matters, isolate it. If it does not matter, do not include it in the screenshot area. ### Re-Record References Intentionally Update a reference screenshot only when the new UI is the expected result. A good time to re-record is when: * the design changed on purpose * a component was restyled intentionally * the environment-specific reference needs to be refreshed Avoid re-recording references during unstable deployments or while the page is still changing frequently. ### Summary The most reliable visual regression tests have three things in common: * they target stable UI * they run in consistent environments * they use reference updates deliberately If you do that, visual regression becomes a useful safety net instead of another pile of flaky noise. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bugbug.io/visual-regression/best-practices.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.