Visual Regression Testing
Relevant source files
The following files were used as context for generating this wiki page:
- tests/Feature/Console/VisualScreenshotCommandTest.php
- tests/Feature/Visual/VisualBaselinesTest.php
- docs/mobile/phase-48-visual-baselines.md (referenced in tests/Feature/Docs/Phase48MobileBaselinesTest.php)
- .github/pull_request_template.md (referenced in tests/Feature/Docs/PullRequestTemplateTest.php)
- AGENTS.md
- app/Support/VisualRegression/VisualScreenshotRunner.php
- app/Support/VisualRegression/VisualScreenshotTarget.php
Visual Regression Testing in RateGuru is a system designed to ensure UI consistency across different viewports and user states. It utilizes automated screenshot capture and comparison against established "baselines" to detect unintended layout or styling changes. This system is integrated into the development workflow, requiring visual checks for key components like the feed, modals, and drawers during the Pull Request process.
Sources: tests/Feature/Docs/PullRequestTemplateTest.php:1-21, AGENTS.md:40-50
Architecture and Components
The system is built around a command-driven runner that manages the lifecycle of capturing screenshots for specific UI "targets".
Visual Screenshot Targets
A VisualScreenshotTarget defines the parameters for a specific UI state to be captured. This includes the route, viewport dimensions, authentication requirements, and specific DOM selectors to wait for or interact with before the capture occurs.
The diagram above illustrates the relationship between the target definitions and the runner that executes the capture.
Sources: tests/Feature/Console/VisualScreenshotCommandTest.php:7-75
Key Screenshot Targets
The following targets are pre-defined for visual validation:
| Target Name | Route | Viewport (WxH) | Key Interaction/Wait Selector |
|---|---|---|---|
feed-desktop | feed | 1440x1000 | [data-testid="feed-page"] |
feed-mobile | feed | 390x844 | [data-testid="feed-page"] |
upload-modal | feed | 1440x1000 | Click [data-testid="open-upload-button"] |
post-drawer | feed | 1440x1000 | Click [data-testid="post-card"] |
post-show | posts.show | 1440x1000 | [data-testid="post-show"] |
Sources: tests/Feature/Console/VisualScreenshotCommandTest.php:7-75, tests/Feature/Visual/VisualBaselinesTest.php:5-35
Execution Flow
Visual regression tests are executed via the Artisan command line interface. The process involves identifying a target, preparing the environment (e.g., handling authentication or interactions), and saving the output to designated directories.
This flowchart describes the logic within the VisualScreenshotCommand and its safety guards.
Sources: tests/Feature/Console/VisualScreenshotCommandTest.php:77-118
Command Options
- Target Argument: Specifies the name of the target (e.g.,
feed-desktop) orallto run all targets. --fresh: Used to update baselines. This option is restricted tolocal,testing, orcienvironments to prevent accidental production overrides.
Sources: tests/Feature/Console/VisualScreenshotCommandTest.php:100-118
Baseline Management
Baselines are stored as reference PNG files in the repository. They represent the "known good" state of the UI.
- Baseline Path:
tests/Visual/baselines/{target}.png - Current Path:
tests/Visual/current/{target}.png
The system validates the existence of these baselines for critical pages. For mobile specifically, a 375px breakpoint is documented as a standard baseline reference.
Sources: tests/Feature/Visual/VisualBaselinesTest.php:5-35, tests/Feature/Docs/Phase48MobileBaselinesTest.php:8-18
Workflow Integration
Visual regression is a mandatory part of the development lifecycle as defined in the project's PR template and agent rules.
Pull Request Checklist
Before a PR can be merged, developers must verify:
- Execution of
visual:screenshot. - Comparison against existing baselines.
- Browser smoke tests for key components (desktop feed, mobile feed, upload modal, post drawer, post show).
- Mobile responsiveness specifically at the 375px width.
Sources: tests/Feature/Docs/PullRequestTemplateTest.php:1-21, tests/Feature/Docs/Phase48PrTemplateTest.php:1-21
Design Contract
UI work must be compared against the "PlateRate Reference Composition" and the /dev/ui-kit. The visual regression system serves as the automated enforcement for these design tokens and layouts.
Sources: AGENTS.md:40-55
Conclusion
The Visual Regression Testing system provides a robust framework for maintaining UI integrity. By combining Artisan-driven screenshot capture with a structured baseline comparison process, RateGuru ensures that new features or refactors do not introduce visual regressions across desktop and mobile viewports.