Review & fix

The Review & fix flow helps you decide what to do after a visual regression step fails.

Instead of guessing from a single screenshot, you can compare the expected result, the observed result, and the visual diff in one place.

Use this flow when a failed visual regression step needs a decision:

• keep the existing reference because the change is a real regression

• accept the new look as the new reference

• increase the allowed difference for this step

When Review & Fix Is Available

The Review & fix option appears for failed visual regression steps in a test run.

It is meant for steps where BugBug was able to compare:

• a stored reference screenshot

• the screenshot captured during the run

• the resulting diff

If no reference exists yet for the current environment, BugBug creates the initial reference automatically during the run instead of opening this flow.

What You See in Review & Fix

The modal is split into two main areas:

• the screenshot comparison view

• the resolution panel

Screenshot Comparison View

The comparison view shows:

• the reference screenshot

• the observed screenshot

• the difference percentage

You can also enable Show diff to overlay the pixel difference visualization on top of the reference screenshot. This helps you see exactly where BugBug detected changes.

Use the opacity slider to make the diff overlay more or less visible.

Resolution Panel

The resolution panel lets you choose what to do with the failure.

You can pick one of three actions:

• Do nothing

• Increase max allowed difference

• Set observed screenshot as reference

If the test run contains multiple failed visual regression steps, you can review them one by one and navigate through them from the same modal.

How to Open Review & Fix

Open the failed test run, find the failed visual regression step, and click Review & fix.

If the run contains multiple failed visual regression steps, BugBug can open a sequential review flow so you can process them one after another.

How to Read the Comparison

Before choosing an action, check three things:

1. What changed Compare the reference and observed screenshots.

2. Where it changed Turn on Show diff to inspect the changed area.

3. How large the change is Review the reported difference percentage.

This part matters because the same failure can mean very different things:

• a real UI regression

• a small acceptable visual shift

• an intentional design update

• an unstable or flaky page state

Do not jump straight to updating the reference. That is how bad baselines are born.

Resolution Options

Do Nothing

Choose Do nothing when the observed UI is not correct and the existing reference should stay unchanged.

Use this when:

• the difference reveals a real regression

• the screen captured the wrong state

• the page is unstable and the result should not be accepted yet

This keeps the current reference screenshot as the expected baseline.

Increase Max Allowed Difference

Choose Increase max allowed difference when the change is acceptable, but you do not want to replace the reference screenshot.

This option updates the step's max difference threshold so that small, acceptable variation can pass in future runs.

Use this when:

• the UI is visually the same in practice, but there are minor rendering differences

• small spacing, shading, or anti-aliasing changes are acceptable

• the component has slight but expected variation

Be careful with this option. Raising the threshold too much makes the check less useful.

Set Observed Screenshot as Reference

Choose Set observed screenshot as reference when the new appearance is the correct expected result and should become the new baseline.

Use this when:

• a design change was intentional

• the component was restyled on purpose

• the correct UI has changed and future runs should compare against the new look

This replaces the existing reference for the matching environment with the observed screenshot from the failed run.

What Happens When You Save

What BugBug saves depends on the option you selected.

If you choose Do nothing:

• no reference is changed

• no threshold is updated

If you choose Increase max allowed difference:

• BugBug updates the step's max difference value

• future runs for that step use the new threshold

If you choose Set observed screenshot as reference:

• BugBug saves the observed screenshot as the new reference

• future runs in the same environment compare against that new reference

Apply to All Failed Screenshots

If the test run contains multiple failed visual regression steps, the modal can show Also apply this to all other failed screenshots.

Use this carefully.

It applies the selected resolution to all failed visual regression steps in the current test run.

This can be useful when:

• a known visual change affects many steps

• a design refresh changed multiple validated areas

• a temporary tolerance adjustment is needed across several failed visual regression steps

It is a bad idea when failures have different causes. One bulk action can easily accept changes that should have been reviewed separately.

Keyboard Shortcuts

Review & fix supports keyboard shortcuts to speed up the workflow.

Resolution Shortcuts

• 1 selects Do nothing

• 2 selects Increase max allowed difference

• 3 selects Set observed screenshot as reference

Save Shortcuts

• Enter saves the current selection

• Shift + Enter saves for all failed visual regression steps in the current run

View Shortcuts

• D toggles the diff overlay

• = zooms in

• - zooms out

• 0 fits the image to the available space

How to Decide Which Option to Use

Use this rule of thumb:

• if the UI is wrong, choose Do nothing

• if the UI is correct but small variation is acceptable, choose Increase max allowed difference

• if the UI is correct and should become the new expected result, choose Set observed screenshot as reference

If you are unsure whether the page is stable, do not accept the result yet. Re-run after stabilizing the page state first.

Common Mistakes to Avoid

Accepting a Broken UI as the New Reference

Do not update the reference just because the test failed. A failing test is a signal, not a command.

Raising the Threshold Too Aggressively

If you keep increasing max difference to silence failures, the visual check gradually stops protecting anything useful.

Using Apply to All Without Reviewing the Failures

Bulk actions save time only when the failures come from the same intentional change. Otherwise, they just spread the mistake faster.

Ignoring Environment Differences

Review decisions apply to the matching environment. If the same step runs in another environment, it may still need its own review or its own reference screenshot.

Summary

Review & fix is where you decide whether a failed visual regression step means:

• there is a real bug

• the baseline should be updated

• the step needs a slightly higher tolerance

Used correctly, this flow helps you keep reference screenshots accurate and visual checks trustworthy.