Visual Regression

Pixel-level screenshot comparisons that catch unintended UI changes between builds.

What this module tests

The Visual Regression module takes screenshots of your application pages and compares them against approved baseline images. Any visual difference above the configured threshold is flagged as a regression. Tests cover:

• Full-page screenshots across multiple viewports
• Component-level snapshots (specific regions or elements)
• Hover and focus states
• Dynamic content masking (to avoid false positives from timestamps, user-specific data)

Baseline management

Visual baselines are created on the first successful run. When you intentionally update your UI, approve the visual diff from the run results view to set the new baseline. Unapproved diffs block the run from being marked as passed.

Baselines are stored per environment. A staging baseline change does not update the production baseline.

Comparison settings

Setting	Default	Description
Pixel difference threshold	0.1%	Maximum percentage of pixels allowed to differ before flagging a failure
Anti-aliasing tolerance	Enabled	Ignores minor sub-pixel rendering differences between runs
Dynamic region masking	Per-scenario	Regions defined in KB or detected automatically (clocks, ads, avatars)
Viewports	Desktop 1280×800	Additional viewports can be added in project settings

KB scenario format for visual tests

# Visual regression scenario example
domain: landing-page
scenarios:
  - id: VIS-001
    title: "Hero section renders correctly at desktop"
    module: visual_regression
    viewport: desktop
    steps:
      - Navigate to / (homepage)
      - Wait for hero section to be fully rendered
    expected: >
      Hero section screenshot matches the approved baseline.
      No layout shifts or missing images.

  - id: VIS-002
    title: "Pricing page matches baseline at mobile viewport"
    module: visual_regression
    viewport: mobile
    screenshot_regions:
      - selector: "#pricing-section"
    steps:
      - Navigate to /pricing
      - Scroll to the pricing section
    expected: >
      Pricing cards render correctly at 375px width.
      No text overflow or truncation.