> 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/how-it-works.md).

# How it works?

Visual regression compares the current appearance of a page or element with a stored reference screenshot.

In BugBug, this happens as part of a visual regression step during test execution. There are two step types:

* **Element visual regression** - compares one selected element
* **Full-screen visual regression** - compares the visible part of the page (the viewport). Content you need to scroll to is not included.

{% hint style="info" %}
Visual regression steps are available on the [Pro plan and higher](https://bugbug.io/pricing/).
{% endhint %}

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FJ14zkNpdhOpSUd9fiCCJ%2Fimage.png?alt=media&amp;token=d9befe06-af8e-4035-8464-6049fd834d81" alt=""><figcaption></figcaption></figure>

## What happens during a run

When the test reaches a visual regression step, BugBug:

1. captures a screenshot of the selected element or of the visible part of the page
2. identifies the current environment
3. looks for a matching reference screenshot
4. compares the new screenshot with the reference
5. marks the step as passed or failed

If the step fails, you can review the difference and decide what to do next.

## How BugBug defines the environment

Reference screenshots are stored **per environment**.

An environment is defined by the combination of:

* browser (the browser name, not its version)
* operating system
* screen size
* profile
* run mode (cloud or local)

This matters because the same page can render differently across environments. For example, a test running in Chrome on Linux in the cloud may need a different reference than the same test running locally on another operating system.

## What happens on the first run

If BugBug cannot find a reference screenshot for the current environment, it does not compare anything yet.

Instead, it:

1. saves the current screenshot as the initial reference
2. links that reference to the current environment
3. marks the step as passed

This is how **the baseline** is created automatically during the first run.

The same happens when a test later runs in a different environment that does not have its own reference yet.

## How the comparison works

When a matching reference exists, BugBug compares the new screenshot with it pixel by pixel.

The comparison takes into account:

* how many pixels are different
* how sensitive the comparison is to color changes
* whether anti-aliased pixels count as differences

The result is the observed difference: the percentage of pixels that differ.

If the new screenshot has a different size than the reference, BugBug first scales it to the reference size and then compares them.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F971ZUJKxFNAfDWVw3FBg%2Fchrome-capture-2026-06-03.gif?alt=media&amp;token=c4f54f63-483d-424e-9910-f1fb09eb8972" alt=""><figcaption></figcaption></figure>

## What decides whether the step passes

Each visual regression step uses a **Max difference (%)** value.

<div align="left"><figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Ff9dqtETPvUUcvbqKcRHn%2Fimage.png?alt=media&amp;token=0f17b527-a052-41ed-b327-bbc569793f38" alt=""><figcaption></figcaption></figure></div>

If you don't set it for a step, the step uses the project default, **Maximum allowed difference**, which is 10% unless you change it in [Project settings](https://docs.bugbug.io/preventing-failed-tests/project-settings.md).

BugBug compares:

* the **observed difference** from the current run
* the **max difference** allowed for the step

The step passes when the observed difference is lower than or equal to the max difference. If it is higher, the step fails.

## What artifacts BugBug creates

For visual regression steps, BugBug stores:

* the reference screenshot
* the screenshot captured during the run
* a diff image that highlights the changed areas, when the step fails

You can see these screenshots in the run details and in the review flow, so you can check what changed instead of guessing.

## What you can do after a failure

When a step fails, open **Review & fix** and compare:

* the reference screenshot
* the observed screenshot from the run
* the visual diff

<div align="left"><figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F2vZB8BxisTb5MtdrkzIy%2Fimage.png?alt=media&amp;token=572b505a-c7ae-4b5f-8a9e-bfa673a721df" alt=""><figcaption></figcaption></figure></div>

From there, you can choose one of the following actions:

* **Do nothing** if the change is not acceptable
* **Increase max allowed difference** if the change is acceptable and the step needs more tolerance
* **Set observed screenshot as reference** if the new UI should become the baseline

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FYgGK57WOEQLxuS9k2U8g%2Fimage.png?alt=media&amp;token=a277e6e2-f9de-431b-9316-c40f04d624c6" alt=""><figcaption></figcaption></figure>

See [Review & fix](https://docs.bugbug.io/visual-regression/review-and-fix.md) for details.

## Manage reference screenshots

Open a visual regression step in the test editor. The **Reference screenshot** field shows the current reference. Before the first run, it says that the reference will be captured automatically.

When the step has references for more than one environment, click **Manage** next to the field. The **Manage reference screenshots** modal lists every reference with its method (cloud or local), OS, browser, profile, screen size, and capture date.

Click **Delete all reference screenshots** to remove all references for this step. The next run in each environment captures a new reference, just like the first run. This can't be undone.

## Why environment-specific references matter

Environment-specific references make visual regression more reliable.

Without them, BugBug would compare screenshots captured under different rendering conditions. That would produce false failures that have nothing to do with an actual regression.

By storing references per environment, BugBug compares like with like:

* desktop with desktop
* one browser with the same browser
* one run context with the same run context

That keeps failures meaningful and review decisions easier.

## Summary

Visual regression in BugBug follows a simple flow:

1. capture the screenshot
2. find the matching environment reference
3. create the reference automatically if none exists
4. compare the screenshots when a reference is available
5. pass or fail the step based on the allowed difference
6. let you review and update the result when needed


---

# 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/how-it-works.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.
