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