How to Compare Happo Screenshots Between Branches

To compare Happo screenshots between branches, compare the Happo reports for the commits at the tips of those branches. Happo’s documented API takes two report SHA identifiers, not branch names: POST /api/reports/:sha1/compare/:sha2. The result separates changed, ignored, added, deleted, and unchanged snapshots and includes a comparison URL. Review the differences to decide whether they are expected; a visual diff alone does not establish that a change is a bug. Happo API reference.

1. Identify the two reports

First make sure Happo has produced reports for both commits you want to inspect. A branch is a moving Git reference; the comparison API is documented in terms of report SHAs. Find the report identifiers in the relevant Happo report or CI output, and verify that each belongs to the commit you intend to compare.

1. Choose the base commit and the branch commit to compare.
2. Confirm that a Happo report exists for each commit.
3. Copy their report SHA values. Do not pass branch names in place of those values.
4. Compare the reports and inspect the returned categories and comparison URL.

Happo documents CI and pull-request review workflows. Where your integration provides a review link, use it to open the relevant comparison. Do not assume every provider selects a baseline the same way. Happo’s GitLab announcement describes history-based baseline lookup for that integration and labels the integration experimental; that announcement does not establish a universal baseline rule. Happo, GitLab integration announcement.

2. Compare the reports with the API

The endpoint is a POST request with both report SHAs in its path. The API reference documents authentication and optional project and comparison settings; consult it for the credentials and exact request fields required by your Happo project. The dossier does not specify a complete authentication header or request body, so the example below shows the documented route without inventing either.

curl -X POST "https://happo.io/api/reports/BASE_REPORT_SHA/compare/BRANCH_REPORT_SHA" \
  -H "Authorization: Bearer YOUR_HAPPO_API_TOKEN" \
  -H "Content-Type: application/json"

Replace both placeholders with report SHAs. Use the authentication scheme and any required project or comparison settings documented for your account in the Happo API reference. The bearer header above is illustrative: verify the documented scheme before running it. The documented comparison route is POST /api/reports/:sha1/compare/:sha2; Happo also documents endpoints for retrieving comparison status and results.

For a script or CI job, keep the API token in your CI secret store or environment rather than committing it. Construct the route from validated report identifiers, make the request, and retain the comparison URL and result categories with the job output. If the comparison is asynchronous or returns a status to check, follow the status and result endpoints described in Happo’s API reference.

3. Review the comparison result

Use the response categories to understand both pixel changes and changes to the snapshot inventory:

Category	What to check
Changed diffs	Inspect each visual difference and decide whether the code change explains it.
Ignored diffs	Check whether the ignored change is still appropriately excluded from review.
Added snapshots	Confirm that new snapshots are expected and belong to the intended report.
Deleted snapshots	Check whether a removed snapshot reflects an intentional inventory change or a missing capture.
Unchanged snapshots	Use these to see which parts of the snapshot set remained stable.
Summary and status	Read the overall comparison state alongside the individual entries.
Comparison URL	Open or share the report review link provided by the result.

A changed snapshot can be an intended design update, a rendering difference, or a regression. Confirm the relevant code change and capture setup before deciding. Added and deleted snapshots matter even when the existing screenshots look unchanged: they can indicate a changed set of stories, pages, or captured states.

4. Keep branch comparisons meaningful

A useful comparison depends on comparing the intended report pair under a suitable, consistent rendering setup. Verify commit/report identity first. Then check that the browser and viewport context is appropriate and consistent for the snapshots being judged. Happo’s Playwright and Storybook materials describe browser and viewport configuration and tolerance settings. Tolerances can reduce minor rendering noise, but they do not replace review of meaningful visual changes. Happo with Playwright, Happo Storybook documentation.

• Compare the base and branch reports for the commits you mean to review.
• Use comparable browser and viewport settings where the integration allows it.
• When a diff is surprising, check whether the snapshot inventory or capture context changed.
• Treat tolerance as noise control, not proof that a difference is harmless.
• Record the comparison URL in the pull-request or CI review context when available.

5. Troubleshooting

Symptom	Likely cause	What to do
The API request cannot find a report	A SHA is mistyped, is not a report identifier, or no report exists for that commit.	Check both report SHAs against the reports or CI output and confirm reports were produced for the chosen commits.
A branch name does not work in the route	The documented route takes report SHA values.	Resolve each branch to the relevant commit, then use the SHA identifiers of the corresponding Happo reports.
The request is rejected	Authentication, project context, or optional request settings may be missing or incorrect.	Follow the current authentication and request requirements in the Happo API reference; do not rely on the illustrative header above without checking.
There is no comparison to review yet	One or both reports may not exist, or the comparison may need a status/result lookup.	Confirm the reports and use Happo’s documented comparison status and result endpoints.
Many snapshots differ unexpectedly	The reports may use different browser or viewport contexts, or rendering noise may be present.	Check integration configuration and capture context. Consider an appropriate tolerance setting, then review remaining diffs.
A visual diff looks like a bug	The diff shows a difference, not its intent or cause.	Relate it to the branch’s code and design changes; accept it if intentional or investigate it if unexplained.
Snapshots appear or disappear	The captured snapshot inventory may have changed.	Review added and deleted entries and verify that the stories, pages, or capture definitions are correct.

6. Performance, reliability, and cost considerations

The comparison endpoint operates on reports already produced for two commits. Ensure the relevant CI jobs have completed before expecting a meaningful comparison. For reliable reviews, preserve the report identifiers and comparison URL with the build or pull request, and verify the selected pair rather than relying on an assumed baseline rule.

The cited Happo sources describe the comparison workflow and API, but the supplied research does not establish request latency, a benchmark, or pricing for this operation. Check Happo’s current documentation and your account terms for those details. A diff’s noise can be reduced with stable browser and viewport choices and suitable tolerance settings, but no setting can decide whether a product change is intended.

Or skip the browser setup

If you need to capture a page for a visual review or a custom comparison workflow, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. It does not replace Happo’s report-to-report comparison endpoint; it can provide screenshots for workflows where you want to capture pages directly.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed; its MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000. Sign up for free.

FAQ

Can I compare two Happo branches by name?

The documented comparison API uses report SHA identifiers. Resolve the branches to the reports for the commits you want to compare.

Does every integration choose the correct baseline automatically?

The supplied sources do not establish a universal baseline rule. The GitLab announcement describes history-based lookup for GitLab and marks that integration experimental.

Does a changed snapshot mean the branch is broken?

No. It means the rendered snapshot changed. Review the change in context and decide whether it is expected.

What should I share with a reviewer?

Share the comparison URL and identify the base and branch commits so the reviewer can confirm the report pair.