Diff Viewer
Six comparison modes for reviewing visual differences.
The Diff Viewer is VisualQ's core review tool. It displays visual differences between baseline and test screenshots using six distinct comparison modes.
Accessing the Diff Viewer
- From the VRT tab, use the results grid to pick an execution, scenario, viewport, and browser, then click View diff
- From the Tests tab, click on a run to open the viewer
- From the project overview, click "Open viewer" on any scenario
- Direct URL:
/projects/[slug]/viewer
The VRT tab groups visual results by execution first, then by scenario. Each execution shows the global VRT score and each scenario expands into a viewport/browser table with status, mismatch percentage, and available signals such as comparison rules, anti-shift, and AI severity.
Comparison modes
Switch between modes using the toolbar buttons or keyboard shortcuts. Each mode is also addressable with the mode query parameter on the viewer URL:
| Mode | URL value |
|---|---|
| Side by side | mode=sidebyside (default — omitted from URL) |
| Slider | mode=slider |
| Overlay | mode=overlay |
| Toggle | mode=toggle |
| Diff highlight | mode=highlight |
| Regions | mode=regions |
Example: /projects/my-project/viewer?runId=abc123&mode=regions opens the viewer directly in Page sections mode.
1. Side by side (1)
Displays the reference image and test image next to each other. When a diff image is available, a third Diff strip is shown below for quick comparison. Best for spotting differences when you can scan both images simultaneously.
2. Slider (2)
A draggable slider reveals the test image over the reference image. Drag left or right to compare specific regions. Ideal for seeing exactly where changes occur.
3. Overlay (3)
The test image is overlaid on the reference image with adjustable opacity. Useful for comparing overall layout changes and alignment shifts.
4. Toggle (4)
Click or press a key to flip between the reference and test images. Good for spotting subtle color or spacing changes that are hard to see side by side.
5. Diff highlight (5)
Pixel differences are highlighted in color on a neutral background. Only the changed pixels are visible, making it easy to locate modifications at a glance.
6. Regions (6)
The Page sections view groups the page into functional blocks (Header, Hero, Carousel, content sections, Footer) instead of individual DOM nodes. All sections are listed in the sidebar; unchanged sections appear greyed out, while sections with differences are highlighted on the canvas with a red diff overlay inside the block.
Each changed section shows its status (visual change, layout change, mixed, ignored) and lets you create comparison rules (Ignore, Dynamic, Layout only) at the block level. Expand a section to see internal element-level details.
Page sections require a test run captured with a recent VisualQ capture version. Older runs without blockResults show a message asking you to re-run the test.
Keyboard shortcuts
| Key | Action |
|---|---|
1 – 6 | Switch to the corresponding view mode |
r | Toggle between normalized and raw images |
a | Approve the current scenario (on failed tests) |
f | Fit image to viewport |
p | Toggle the left panel |
← / → | Navigate between scenarios |
+ / - | Zoom in / out |
? | Show/hide keyboard shortcuts help |
Escape | Close help overlay |
Press ? in the viewer to see the full list of keyboard shortcuts.
Approving changes
When a viewport has failed, an Approve button appears in the toolbar (or press a). Approving promotes that test screenshot to the new baseline, marks the row as Approved, and keeps the original mismatch and diff metadata visible for auditability. Approved rows no longer count as failures in VRT totals.
Anti-shift indicator
When VisualQ detects that differences are caused by a global page shift rather than content changes, an Anti-shift badge with a count appears in the toolbar. This helps you distinguish between real visual regressions and simple alignment shifts.
Normalized vs. raw
When content rules are applied, the viewer shows normalized images by default (with dynamic content replaced). Press r to see the raw screenshots as they were actually captured.
Panel and filtering
The left panel displays the list of test results. Use the toolbar filters to narrow down results:
- Status filter: All, Failed, Passed (with counts)
- Browser filter: appears only when the run includes multiple browsers
The panel also includes a Tests tab and a Coach tab. The Coach tab shows AI analysis of the current diff (on supported plans). You can collapse or expand the panel with the p shortcut — the state is persisted across sessions.
AI analysis panel
On supported plans, an AI Analysis panel appears alongside the diff view:
- Smart Diff classifies each change by severity (critical, major, minor, cosmetic) Hobby plan
- Coach AI provides a natural-language explanation of what changed Hobby plan