Core Concepts
New to visual testing? Learn the fundamental concepts of baseline matching, automated review workflows, and why structural analysis yields more reliable visual audits.
What is a Baseline?
A baseline is the reference capture of your page when it is working correctly: a screenshot plus the page's DOM tree. RegressionBot stores these captures securely in cloud storage segmented by your organization, project, and target stage.
When a visual test runs, the worker captures each page again and compares its DOM tree with the baseline's. It compares the elements, their text, a set of computed styles (such as colour, font, borders and position), images by their content, reader-facing attributes such as link targets and alt text, and the page's metadata and JSON-LD. The screenshots are kept only as pictures for people, in alerts and in the inspect view. Nothing compares their pixels.
Counts as a change
- Text edits
- Elements added, removed or moved
- Style changes on the compared list
- Image changes
- Edits to link targets, alt text, titles, aria-labels, placeholders, roles, types and values
- A change to an element's CSS
position, such as a header made sticky - Metadata changes (title, description, social tags, canonical, JSON-LD)
Does not count
- Parts that changed on their own during capture, such as carousels and counters. The page is read twice, 300ms apart, and anything that differs is marked
dynamicand left out. - Edits where only a date or time changed. They are listed with
valueOnly: "date"but do not make the page changed. - Content that was only pushed down by a change above it.
Known trade-off: a change that exists only in how the page is painted can go unreported. One example is an image that failed to decode while its element and source stayed the same. Many such cases are still caught: broken images, canvas content, and web fonts that failed to load (a font-failed change).
Every capture must include its DOM tree. If the tree cannot be read, the page ends with an ERROR that says so, and nothing is compared. A stored baseline from before DOM trees were kept is replaced by the next capture, which is reported as a new baseline.
Projects
A project is a named entity that serves as both a baseline namespace and a saved test configuration. The first time you run a managed-mode job against a new project name, RegressionBot creates the project and saves the configuration — the URLs, devices, and masks you supplied.
Subsequent runs against the same project name can omit all parameters. RegressionBot loads the saved configuration and compares against the stored baselines. This is called a parameter-less run. If you supply parameters that differ from the stored config, the run is rejected with an error — this prevents silent baseline drift from ad-hoc param changes.
Managed mode
No baseOrigin supplied. RegressionBot stores baselines on your behalf and enforces config locking. Suitable for fixed staging or production URLs where you control the approval step.
Live-vs-live mode
A baseOrigin is supplied. Every run compares the testOrigin against the live baseOrigin directly — no stored baselines, no approval step, no config locking. Suitable for PR preview vs production comparisons.
See the Project Configurations guide for step-by-step setup and the REST API reference.
Regressions vs. Intentional Changes
Visual changes fall into two distinct categories:
❌ Visual Regression (Unintentional)
An accidental layout breakdown. E.g., a CSS stylesheet change on the header breaks button alignments on the checkout page, causing items to overlap.
✨ Intentional Layout Change
A planned update. E.g., a designer redesigns the navbar to have a modern glassmorphic background. This is a visual difference, but it is not a regression.
What does Approval do?
When you approve a test result (either in the dashboard, via the SDK, or through MCP), you are telling RegressionBot:
"Yes, this visual change is intentional. Save this new capture as our source of truth."
Under the hood, this overwrites the stored baseline with the new capture. All future test runs will now compare against it.
Responsive Viewports
Layout bugs are often highly device-specific. RegressionBot runs headless workers using configurable browser viewport dimensions:
Desktop Chrome
1280px × 800px
Mobile viewport
375px × 667px
In addition to the default viewport, RegressionBot supports a fixed set of mobile and tablet profiles. Selecting one sets the viewport size, user agent and touch capability for the capture.
Desktop Chrome (default, 1280×720), iPhone 12, iPhone 13, iPhone 14, iPhone 15, iPad Mini, iPad Pro 11, Pixel 5, Pixel 7, Galaxy S8, and Galaxy S9+. Any other name is rejected.Testing Lifecycle Flow
This flowchart traces how a visual run flows through our parallel execution architecture:
🎯 Verdict Decision