How to Use PixellPeep
Everything you need to run visual regression tests, catch UI regressions before users do, and ship with confidence — explained simply.
Create a Project
Start by organising your work into Projects. Projects group related test runs together, making it easy to track visual changes over time.
- Go to Projects in the top navigation
- Click "New Project" and give it a meaningful name (e.g. "Marketing Website - Q2")
Compare Two Images
Upload a baseline (reference) and a comparison image to detect pixel-level differences with precision.
- Navigate to Comparisons → Image Compare from the top menu
- Upload your baseline screenshot on the left and the new version on the right
- Choose a comparison algorithm suited to your needs (see tips below)
- Adjust sensitivity — higher = more strict, lower = more tolerant
- Click Compare to start the analysis
Understand the Algorithms
PixellPeep offers multiple comparison engines. Choosing the right one dramatically improves result quality.
- Speed Compare — best for identical dimensions; catches every single pixel difference
- Visual Match — structural similarity; great for real-world screenshots with slight anti-aliasing
- Precision Analysis — statistical accuracy; recommended for compression or colour shift detection
- Smart Detect — perceptual hashing; ideal for finding duplicate or near-duplicate images
- Color Insight — color distribution analysis; perfect for detecting colour scheme or tinting changes
Read the Results
After a comparison runs, the result image and metrics help you pinpoint exactly what changed.
- Red/orange highlights show areas with differences
- Check the "Difference %" score — above 5% usually signals a significant regression
- Use the Highlight Mode toggle to switch between Heatmap, Color Overlay, and Bounding Box views
- Click on any highlighted region to zoom in
- Use the side-by-side slider to manually inspect baseline vs. current
Bulk Comparison (CSV Upload)
Test dozens of image pairs in a single run without uploading them one by one.
- Go to Comparisons → Bulk Compare
- Download the CSV template and fill in the image pair names and desired settings
- Upload your baseline images, comparison images, and the filled CSV together
- Each row in the CSV represents one image pair with its own algorithm and sensitivity
- All results are collected into a single Test Run for easy review
View Reports & Test Runs
Every comparison belongs to a Test Run. The Reports section gives you a full history with exportable summaries.
- Go to Reports in the top navigation to see all past Test Runs
- Filter by project, date range, or algorithm
- Click a Test Run to drill down into individual comparison results
- Download PDF or CSV exports for stakeholder sharing
- Spot trends over time using the pass/fail charts
Export & Share
Generate polished reports that you can attach to tickets, PRs, or send to your QA team.
- PDF reports include highlighted screenshots and a summary table
- CSV exports give you raw data for custom dashboards
- Reports include timestamps, algorithms used, and scores per image pair
Automate in CI
Fail builds when screenshots drift using the REST API, CLI, or GitHub Action.
- Create an API key under Settings → API Keys
- Install the CLI (npm install -g pixellpeep), then run: pixellpeep compare --baseline ... --current ... --project-id 1 --api-key qv_...
- See the CI Integration guide for Playwright + GitHub Actions examples
Keep your app true to its design
Design Fidelity automatically screenshots your live app as people use it and grades each screen against its Figma design, so you catch UI drift without lifting a finger.
- Open Design Fidelity and connect each screen to its Figma frame (file key + node id from the Figma URL)
- Add the @pixellpeep/capture snippet to your app — it captures screens automatically as users navigate
- Black out private areas with maskSelectors so sensitive data never leaves the browser
- Review graded results (colour, spacing, font, missing/extra elements) and get Slack/email alerts on real drift
- Full walkthrough: see the Design Fidelity setup guide under Docs
Best Practices
Follow these guidelines to get the most accurate and actionable results from PixellPeep.
Standardise screenshot dimensions
Always capture screenshots at the same viewport size. Mismatched dimensions cause false positives even with tolerant algorithms.
Use a staging environment
Run comparisons against your staging or QA environment, never production, to avoid live content flickering in results.
Update baselines intentionally
When a design change is approved, re-run the comparison and save the new result as your updated baseline rather than deleting the old one.
Pick sensitivity per use case
Use high sensitivity (80–100) for pixel-exact design QA. Use lower sensitivity (40–60) for UI smoke tests where minor rendering differences are acceptable.
Group related tests in a project
Keep marketing pages, app onboarding, and checkout flows in separate projects so regressions are easy to isolate.
Review test runs promptly
Aim to review test run results within the same sprint cycle. Stale results make it harder to trace the root cause of a regression.
Ready to start testing?
Set up your first project and run your first comparison in under 5 minutes.