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.