> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/visual-regression/best-practices.md).

# 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 shows 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. It captures only the visible part of the page (the viewport), so scroll the page to the right place before the step. BugBug warns about this in the step settings: full-screen checks are more likely to be flaky because of dynamic content, scroll position, and loading states.

## Keep the screen state stable

Visual regression compares screenshots, so even small visual changes can affect the result.

Before taking the screenshot, visual regression steps wait for the page to load, using these [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md) by default:

* both step types wait until the document has loaded and network requests have finished
* element steps also wait until the element is visible, is not animating, and is not covered by another element

Waiting conditions don't cover everything. Before adding a visual regression step, make sure the page is in a repeatable state:

* close popups, cookie banners, and tooltips unless they are part of the expected result
* avoid transient UI states such as 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**. A reference is matched against the combination of:

* browser
* operating system
* screen size
* profile
* run mode (cloud or local)

If you run the same test in a different environment, BugBug creates a separate 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 saves the current screenshot as the initial reference and the step passes.

That means the first run sets the baseline. Because of that:

* make sure the page looks correct before you accept that first run as your baseline
* check the reference in the step details after the first run
* if the environment changes later, BugBug creates a separate reference for that environment

## Choose max difference carefully

**Max difference (%)** defines how much visual change is allowed before the step fails. If you don't set it for a step, the step uses the project default.

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.

## Use project settings for consistent behavior

Go to [Project settings](https://docs.bugbug.io/preventing-failed-tests/project-settings.md) and open the **Visual regression** tab to set how all visual regression steps in the project compare screenshots:

| Setting                        | Default | What it does                                                                                           |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------ |
| **Maximum allowed difference** | 10%     | Max difference used by steps that don't have their own value                                           |
| **Color sensitivity**          | 0.2     | How different the color of the same pixel must be to count as a difference                             |
| **Include anti-aliasing**      | Enabled | When enabled, anti-aliased pixels count as differences. Disable it to ignore anti-aliasing differences |

Use project defaults when you want consistent behavior across tests. Set **Max difference (%)** on a step only when that step genuinely needs a different tolerance. To go back to the project default, click **Reset to default** next to the field.

## Review failures before updating references

When a visual regression step fails, review the screenshots before changing anything.

Use [Review & fix](https://docs.bugbug.io/visual-regression/review-and-fix.md) 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.

## Watch for size changes

If the screenshot has a different size than the reference, BugBug scales it to the reference size before comparing. A change in the element's size alone may therefore cause only a small difference, as long as the content looks similar after scaling. Don't rely on visual regression alone to catch size changes.

## 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
* full-screen screenshots with dynamic content

If this kind of content matters, check it separately. If it does not matter, keep it out of the screenshot area, for example by checking a smaller element.

## 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

To re-record all references of a step at once, open the step in the test editor, click **Manage** next to **Reference screenshot**, and click **Delete all reference screenshots**. The next run in each environment captures a new reference. The **Manage** link appears when the step has references for more than one environment.

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
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://docs.bugbug.io/visual-regression/best-practices.md?ask=<question>&goal=<user_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.
