Share some real cases

[pftg]

Hey guys will be great to learn how to move this gem futher. Share your cases that when we will run bug refactoring we will take in account those cases

[pftg]

@oboxodo thanks for your contribution. Could you share how do use or want to use this gem?

[oboxodo]

@pftg glad they were useful - there's more in the backlog as time allows 😅 (and if you agree, of course).

How I use it: inside an existing RSpec/Capybara system-spec suite, Firefox on self-hosted runners, baselines committed in plain git. My team isn't on it yet, by choice: before I put it in front of them I want the whole loop to be smooth, because anything that feels like a roadblock to merging gets routed around and the tool loses its chance. So I've been prototyping that loop on a POC branch, and upstreaming every piece that would help any user of the gem, which also means the eventual rollout in my project carries as few custom hacks as possible. The comparison itself is solid. What shaped everything I built around it is that the human time goes into reviewing diffs and getting the new images into the right commit. Out of the box, with images rendered on CI, the dev is on their own for that part. Two flows came out of it.

Remote flow: CI renders, you review and commit locally

This is basically the out-of-the-box existing flow, but I'm making it easy for the user to run a review tool based on the report, locally.

flowchart TD
    A([Push the branch]) --> B[CI runs the system specs<br/>match_screenshot compares against git show HEAD:]
    B --> C{any screenshot<br/>changed?}
    C -- no --> G([Green, nothing to review])
    C -- yes --> D[CI uploads an artifact<br/>base, actual, diff, heatmap, HTML report]
    D --> E[Sticky PR comment<br/>links the report and names the run id]
    E --> F["review --run &lt;id&gt;<br/>downloads the artifact with gh"]
    F --> H[Serves the same HTML report locally<br/>Accept / Reject per screenshot]
    H -- reject --> I[Baseline kept<br/>fix the UI, push again]
    H -- accept --> J[CI-rendered PNG copied over the baseline<br/>and staged]
    J --> K["git commit --fixup &lt;commit that last set it&gt;<br/>one click, grouped"]
    K --> L([Autosquash, push]) -.-> B
    I -.-> A

Loading

Local flow: the same loop without a CI round trip

This one basically allows for faster feedback loops by generating the new images locally. Then uses the same new review tool. If the dev skips it, the remote flow still catches the issues. So it's opt-in.

flowchart TD
    A([Edit the UI, run one command]) --> B{container browser with<br/>the CI-pinned Firefox<br/>running?}
    B -- no / stale --> C[Start or recreate it<br/>one status line] --> D
    B -- yes --> D[Run the tagged specs<br/>against the container]
    D --> E[Compare against git show HEAD:<br/>same images CI would render]
    E --> F{any screenshot<br/>changed?}
    F -- no --> G([Green, push<br/>CI compares the same way])
    F -- yes --> H[Review page opens<br/>Accept / Reject, with example title,<br/>file:line, URL, baseline's last commit]
    H -- accept --> I["Stage + git commit --fixup<br/>&lt;commit that last set it&gt;"] -.-> A
    H -- reject --> J[Baseline kept, fix the UI] -.-> A

Loading

In both, the comparison reads git show HEAD:, so "accept" is complete only once committed, and the fixup step is what turns the next run green. Plain bin/rspec without the container never compares and prints one summary line, so devs who skip the local setup just use the remote flow.

Pieces, each one PR-sized

Roughly in the order I'd propose them. The review UI is the part I'd most like in core. The container runner feels like a wrapping gem, though I'm not sure yet, and anything else you'd rather not carry can live there too if core exposes the hook it needs.

1. Review page on top of the HTML report. Accept / Reject per screenshot (Y/N keys), progress counter, undo, "all reviewed" card. Accept copies the new PNG over the baseline and stages it. For a new screenshot (listed in the report as of fix: the HTML report lists new screenshots #307) Accept is just the git add the report already suggests. Reject does nothing to disk. Needs: nothing new in core, it is the existing template plus a tiny local Rack server the review command runs on 127.0.0.1. It could even be a minimal TCPServer-based server tailored to this one use, to keep it free of dependencies outside Ruby core.
2. Context per screenshot. The example's description, file:line, page URL, the crop:/skip_area: used, and the commit that last set the baseline (git log -1 on the PNG). Deciding "is this change intended?" is much faster with those four lines than with a file name. Needs: the assertion to carry test metadata, a field on ScreenshotAssertion. This is the one API change worth agreeing on early. In my POC it is a sidecar file next to each capture, only because I am working outside the gem. Upstream it belongs on the assertion itself, flowing into Reporting the same way the new-screenshot tally does in fix: the HTML report lists new screenshots #307, so the HTML report embeds it and custom reporters get it for free.
3. Accept as a commit. After review, one action creates git commit --fixup <commit that last set each baseline>, grouped, so the baselines travel with the UI change that moved them, and the page explains the HEAD rule the README already documents instead of the dev discovering it when the next run stays red. Needs: the VCS helper exposed.
4. Review CI-rendered captures locally. bin/snap_diff review --run <id> downloads the artifact your upload-screenshots action produces and serves it through the same page. Needs: a stable artifact layout contract (which files, where).
5. Compare only on the pinned renderer. Outside CI or the container the matcher is a no-op and the run ends with one line ("N snapshot examples ran without pixel comparison, CI compares them"). Needs: a config flag. It sits naturally next to record.
6. RSpec :visual tag, enforced both ways. An untagged match_screenshot raises, and a tagged example that never calls it fails. Gives bin/rspec --tag visual as the discovery command. Needs: RSpec integration only.
7. Pinned-browser container. Selenium's standalone-firefox image with the runner's Firefox and geckodriver laid over it, started on demand by the test run, plus the Firefox prefs that make a non-localhost host alias behave (secure-context allowlist, no mixed-content upgrade), a short page-load timeout, and a preflight that detects a stale container after the laptop changes networks. I could understand keeping this out of core, as a snap_diff-container-style gem. I have it running in my POC and it works, but it is too tailored for now. If the local review server and interactive report from items 1 to 3 land upstream, the container piece just hooks into that same review flow.

Here are some screenshots of the POC. I had to blur parts of them for the privacy of the project I'm working on.

Review page: Accept or Reject per screenshot, with the example that took it, its file:line, the page URL and the
commit that last set the baseline

All reviewed: accepted baselines grouped by the commit that last set them, the HEAD rule spelled out, and the exact
fixup command or a one-click button

After the one-click fixup: the commits made, what went into each, and the next step

Happy to discuss further and eager for feedback. Thanks for opening the discussion.

[oboxodo]

@pftg:

One correction on the screenshots above, specifically the "all reviewed" and "committed" cards. They fixup each accepted baseline into the commit that last set that baseline. That is the wrong target: the fixup should land in the commit that caused the pixels to change, and the commit that last recorded the baseline is often somewhere else, possibly on the default branch and outside the PR entirely, where an autosquash would never find it. In the run I took the screenshots from the two happened to coincide, which is how it slipped past me. The tool cannot know which commit caused a change, so I am exploring how to do this honestly: likely a default of HEAD with a choice among the branch's own commits, and no fixup offered at all while the UI change is still uncommitted, since then the baselines belong in that same commit. The rest of the review flow is unaffected.