> 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/review-and-fix.md).

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

**Review & fix** is available for failed visual regression steps in a test run, where BugBug compared:

* a stored reference screenshot
* the screenshot captured during the run
* the resulting diff

If no reference exists yet for the current environment, BugBug saves the current screenshot as the reference and the step passes, so there is nothing to review.

## How to open Review & fix

Open the failed test run and select the failed visual regression step. Then click **Review & fix** in the step details or in the error details.

If the run has more than one failed visual regression step, the modal shows "Failed step X of Y". Use the arrows next to the title to move between steps.

## What you see in Review & fix

The modal has two areas:

* the screenshot comparison view
* the **What to do?** panel

### Screenshot comparison view

The comparison view shows:

* the **reference screenshot**
* the **observed screenshot**, with the difference percentage

Select **Show diff** to overlay the pixel difference on top of the reference screenshot. This shows exactly where BugBug detected changes. Use the slider to make the overlay more or less visible.

Use the zoom controls to zoom between 25% and 400%.

### What to do?

Pick one of three actions:

* **Do nothing**
* **Increase max allowed difference** (selected by default)
* **Set observed screenshot as reference**

Then click **Save**. When more failed steps are waiting, the button says **Save and review next** and opens the next step after saving.

## 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** - check the 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 screenshot captured the wrong state
* the page is unstable and the result should not be accepted yet

Nothing is saved. The reference and the max difference stay as they were.

### Increase max allowed difference

Choose **Increase max allowed difference** when the change is acceptable, but you don't want to replace the reference screenshot.

BugBug sets the step's **Max difference (%)** to the observed difference, rounded up to a whole percent. For example, if the observed difference is 3.2%, the new max difference is 4%. Future runs of this step use the new value in every environment.

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

BugBug replaces the reference for the environment of this run with the observed screenshot. References for other environments don't change.

## Apply to all failed screenshots

If the test run has more than one failed visual regression step, the modal shows **Also apply this to all other failed screenshots**. When you select it, the button changes to **Save N steps**.

It applies the selected action 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 checked areas
* a tolerance adjustment is needed across several failed 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

### 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 the current selection for all failed visual regression steps in the run, even if the checkbox is not selected

### 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. Stabilize the page state and run the test again 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

A new reference applies only to the environment of the reviewed run. If the same step runs in another environment, it may still need its own review or its own reference screenshot. A new max difference, on the other hand, applies to the step in every environment.

## 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 keeps reference screenshots accurate and visual checks trustworthy.


---

# 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/review-and-fix.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.
