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 screenshot of your application when it is functioning correctly. RegressionBot stores these reference images securely in cloud storage segmented by your organization, project, and target stage.
When a visual test runs, the worker crawls the site and captures brand-new screenshot buffers, comparing them pixel-by-pixel against the saved 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 screenshot as our source of truth."
Under the hood, this triggers an operation that overwrites the existing stored baseline file with the newly captured current image buffer. All future test runs will now compare against this new image.
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