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 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
Comparison modes
Switch between modes using the toolbar buttons or keyboard shortcuts.
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)
Changed areas are outlined with bounding boxes. This mode can display either pixel blob regions or semantic element results with statuses (visual change, layout change, ignored, dynamic). When semantic results are available, a sidebar lists each region with its status, and you can create comparison rules (Ignore, Dynamic, Layout only) directly from the viewer.
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 scenario has failed, an Approve button appears in the toolbar (or press a). Approving a test updates the baseline with the new screenshot, marking the visual change as intentional.
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) Starter plan
- Coach AI provides a natural-language explanation of what changed Pro plan