pr-screenshot-comparison

PR Screenshot Comparison

Create a single, reviewer-friendly image that makes a visual UI change easy to evaluate.

Product evidence rule

A PR screenshot is evidence of the product, not a design illustration. Every panel must come from the actual product route running the exact base or PR commit. It must use the real app shell, routing, authentication boundary, and data path.

A component harness, Storybook story, static reconstruction, fabricated destination page, or mock data screen does not qualify as product evidence. Do not attach one to a PR or describe it as an application screenshot.

If authentication or data blocks the route:

1. Start or reuse the project's canonical local environment.
2. Reuse an authenticated browser session when one is available. If sign-in needs the user, request the smallest necessary handoff.
3. If the actual route still cannot be reached, stop and report the blocker. A missing screenshot is more accurate than fabricated proof.

Build a harness only when the user explicitly asks for component-level evidence. Label it Component harness in the image and PR copy. Never mix it with or substitute it for product screenshots.

Internal data policy

For a verified private or internal PR, use the actual product data on screen, including PHI. Do not replace names, records, or content with fake data solely for privacy. These screenshots are internal review artifacts.

Still exclude credentials, access tokens, passwords, API keys, and unrelated sensitive data. For a public or externally visible PR, minimize or redact sensitive data before capture.

Workflow

1. Define the proof before capturing: route, viewport, theme, interaction states, and the exact UI area that changed. Before capture, list every user-visible behavior introduced or changed by the PR; the final artifact must cover each material behavior. If an interactive control is central to the change, show both its default state and its primary open or activated state. When the base has no equivalent control, use three panels: Before, After at rest, and After activated. Use the same data and controls wherever they exist. Prefer the smallest complete set of states that proves the change; do not screenshot unrelated chrome.
2. Capture the before state from the actual product route on the base branch and the after state from that same route on the PR branch. Use separate worktrees or an equivalent reversible setup so the two captures are genuinely comparable. Use the same authenticated session and product data where possible. Do not replace a blocked product route with a mock or harness.
3. Crop both captures tightly to the affected controls. Preserve enough nearby context to explain the state. Keep crop dimensions and scale identical unless the layout itself changed.
4. Stitch the images into one comparison image, ordered Before then After. Use the three-panel order from step 1 when the change adds a central interaction that has no base equivalent. Add a restrained caption above or below each panel. Use a neutral divider/background and ensure labels remain readable in the captured theme. Produce one PNG, not a set of loose images.
5. Inspect the final image at normal review size. Confirm it shows the actual running product, labels are accurate, the crops align, and no unrelated UI or prohibited secret is visible. Apply the internal data policy above instead of fabricating safer-looking content.
6. Attach the image to the PR description as a native GitHub attachment with gh pr edit --attach (see "Attaching with gh" below). Then re-read the stored body and confirm the image reference is a hosted github.com/user-attachments URL that renders for the repository.