Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: add pinchtab compare command with visual and data diffs

Luigi Agostiedfe722b6fed
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 3fbb0523..b69ab48b 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -25,7 +25,7 @@ func browserRootCommands() []*cobra.Command {
downloadCmd, uploadCmd, findCmd, selectCmd, checkCmd, uncheckCmd, networkCmd, waitCmd,
keyboardCmd, keydownCmd, keyupCmd, scrollintoviewCmd, dialogCmd, consoleCmd, errorsCmd,
clipboardCmd, cacheCmd, cookiesCmd, setCmd, storageCmd, stateCmd, closeCmd, handoffCmd,
- resumeCmd, handoffStatusCmd, recordCmd, auditCmd,
+ resumeCmd, handoffStatusCmd, recordCmd, auditCmd, compareCmd,
}
}
@@ -365,6 +365,13 @@ func configureBrowserFlags() {
auditCmd.Flags().String("seaportal-report", "", "Audit pages from a SeaPortal results JSON file (array of Result objects)")
auditCmd.Flags().Bool("enrich-all", false, "Browser-enrich every seaportal page, ignoring browserRecommended routing")
+ compareCmd.Flags().String("pages", "", "Comma-separated relative paths to compare (default: the base URLs)")
+ compareCmd.Flags().Bool("visual-diff", true, "Capture screenshots and compute visual diffs")
+ compareCmd.Flags().String("output-dir", "", "Write report.json and diffs/ to this directory")
+ compareCmd.Flags().Int("concurrency", 0, "Pages audited in parallel per side (default 2, max 8)")
+ compareCmd.Flags().Bool("json", false, "Print the comparison report JSON to stdout")
+ compareCmd.Flags().Bool("fail-on-diff", false, "Exit non-zero when any visual or data diff exists")
+
addTabFlag(consoleCmd, errorsCmd)
}
diff --git a/cmd/pinchtab/cmd_compare.go b/cmd/pinchtab/cmd_compare.go
new file mode 100644
index 00000000..c288a31b
--- /dev/null
+++ b/cmd/pinchtab/cmd_compare.go
@@ -0,0 +1,28 @@
+package main
+
+import (
+ browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
+ "github.com/spf13/cobra"
+)
+
+var compareCmd = &cobra.Command{
+ Use: "compare <live-url> <staging-url>",
+ Short: "Compare two site versions visually and by audit data",
+ Long: `Audit the same pages on a live and a staging base URL, then compare
+each pair: pixel-level visual diff on the screenshots plus data drift
+(console errors, broken assets, accessibility score, load time).
+
+Pages default to the two base URLs; pass --pages with comma-separated
+relative paths to compare more. With --output-dir the comparison report is
+written to <dir>/report.json and annotated diff images to <dir>/diffs/.
+
+Differences are data, not failure: the command exits 0 even when pages
+differ. Pass --fail-on-diff to exit non-zero when any visual or data diff
+exists (CI gate).`,
+ Args: cobra.ExactArgs(2),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.Compare(rt.client, rt.base, rt.token, cmd, args[0], args[1])
+ })
+ },
+}
diff --git a/internal/audit/compare.go b/internal/audit/compare.go
new file mode 100644
index 00000000..8d90c02d
--- /dev/null
+++ b/internal/audit/compare.go
@@ -0,0 +1,274 @@
+package audit
+
+import (
+ "bytes"
+ "encoding/base64"
+ "fmt"
+ "image"
+ "image/png"
+ "math"
+ "strings"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/audit/visualdiff"
+)
+
+// Page comparison statuses.
+const (
+ CompareStatusCompared = "compared"
+ CompareStatusAdded = "added" // present only on the staging side
+ CompareStatusRemoved = "removed" // present only on the live side
+)
+
+// compareTolerance is the per-pixel tolerance for screenshot comparison,
+// absorbing anti-aliasing noise between two renders of the same page.
+const compareTolerance = 0.1
+
+// timingDriftThresholdMs is the load-time delta below which timing
+// differences are treated as run-to-run noise, not drift.
+const timingDriftThresholdMs = 1000.0
+
+// DataDrift is one field-level difference between paired pages.
+type DataDrift struct {
+ // Field identifies what drifted (consoleErrors, brokenAssets,
+ // accessibilityScore, loadMs).
+ Field string `json:"field"`
+ // Live and Staging are the two observed values, stringified.
+ Live string `json:"live"`
+ // Staging is the staging-side value.
+ Staging string `json:"staging"`
+}
+
+// PageComparison is the comparison outcome for one paired path.
+type PageComparison struct {
+ // Path is the page path relative to the two base URLs.
+ Path string `json:"path"`
+ // Status is compared, added, or removed.
+ Status string `json:"status"`
+ // LiveURL and StagingURL are the audited URLs, when present.
+ LiveURL string `json:"liveUrl,omitempty"`
+ // StagingURL is the staging-side URL.
+ StagingURL string `json:"stagingUrl,omitempty"`
+ // DiffPercentage is the visual difference over the compared area, in
+ // [0,100]; null when no screenshot pair was available.
+ DiffPercentage *float64 `json:"diffPercentage,omitempty"`
+ // DiffImagePath is the annotated diff image written by the caller,
+ // set only when the pair visually differs.
+ DiffImagePath string `json:"diffImagePath,omitempty"`
+ // Drift lists field-level data differences; empty means identical data.
+ Drift []DataDrift `json:"drift"`
+ // Error carries per-page audit errors from either side.
+ Error string `json:"error,omitempty"`
+}
+
+// changed reports whether this page counts as a difference for CI gating.
+func (pc PageComparison) changed() bool {
+ if pc.Status != CompareStatusCompared || len(pc.Drift) > 0 {
+ return true
+ }
+ return pc.DiffPercentage != nil && *pc.DiffPercentage > 0
+}
+
+// ComparisonReport is the site-level live-vs-staging comparison.
+type ComparisonReport struct {
+ // SchemaVersion is the report schema version; always SchemaVersion.
+ SchemaVersion string `json:"schemaVersion"`
+ // GeneratedAt is when the comparison was produced.
+ GeneratedAt time.Time `json:"generatedAt"`
+ // LiveBase and StagingBase are the compared base URLs.
+ LiveBase string `json:"liveBase"`
+ // StagingBase is the staging base URL.
+ StagingBase string `json:"stagingBase"`
+ // Pages are the per-path comparison entries.
+ Pages []PageComparison `json:"pages"`
+ // HasDiffs reports whether any page shows a visual or data difference.
+ HasDiffs bool `json:"hasDiffs"`
+}
+
+// CompareOutcome carries the report plus the annotated diff images (PNG
+// bytes keyed by page path) for the caller to write to disk.
+type CompareOutcome struct {
+ Report ComparisonReport
+ DiffImages map[string][]byte
+}
+
+// PagePair joins the live and staging entries for one relative path. A nil
+// side means the page exists only on the other.
+type PagePair struct {
+ Path string
+ Live *PageResult
+ Staging *PageResult
+}
+
+// relPath strips base from url, normalizing the trailing slash, so
+// "http://x/site/" + "http://x/site/a.html" → "a.html" and the base itself
+// maps to "".
+func relPath(base, url string) string {
+ base = strings.TrimSuffix(base, "/")
+ if url == base {
+ return ""
+ }
+ if strings.HasPrefix(url, base+"/") {
+ return strings.TrimPrefix(url, base+"/")
+ }
+ return url
+}
+
+// PairPages pairs live and staging report pages by path relative to their
+// base URLs: live-order pairs first, then staging-only pages. One-side-only
+// pages come back with the other side nil.
+func PairPages(liveBase, stagingBase string, live, staging []PageResult) []PagePair {
+ stagingByPath := make(map[string]*PageResult, len(staging))
+ for i := range staging {
+ stagingByPath[relPath(stagingBase, staging[i].URL)] = &staging[i]
+ }
+
+ var pairs []PagePair
+ seen := map[string]bool{}
+ for i := range live {
+ path := relPath(liveBase, live[i].URL)
+ seen[path] = true
+ pairs = append(pairs, PagePair{Path: path, Live: &live[i], Staging: stagingByPath[path]})
+ }
+ for i := range staging {
+ path := relPath(stagingBase, staging[i].URL)
+ if seen[path] {
+ continue
+ }
+ seen[path] = true
+ pairs = append(pairs, PagePair{Path: path, Staging: &staging[i]})
+ }
+ return pairs
+}
+
+// ComparePages pairs the two audit reports' pages and computes per-page
+// visual and data diffs. Diffs are data: the only errors are malformed
+// screenshots.
+func ComparePages(liveBase, stagingBase string, live, staging AuditReport) (CompareOutcome, error) {
+ outcome := CompareOutcome{
+ Report: ComparisonReport{
+ SchemaVersion: SchemaVersion,
+ GeneratedAt: time.Now().UTC(),
+ LiveBase: liveBase,
+ StagingBase: stagingBase,
+ },
+ DiffImages: map[string][]byte{},
+ }
+
+ for _, pair := range PairPages(liveBase, stagingBase, live.Pages, staging.Pages) {
+ pc := PageComparison{Path: pair.Path, Status: CompareStatusCompared, Drift: []DataDrift{}}
+ switch {
+ case pair.Staging == nil:
+ pc.Status = CompareStatusRemoved
+ pc.LiveURL = pair.Live.URL
+ case pair.Live == nil:
+ pc.Status = CompareStatusAdded
+ pc.StagingURL = pair.Staging.URL
+ default:
+ pc.LiveURL = pair.Live.URL
+ pc.StagingURL = pair.Staging.URL
+ pc.Drift = diffPageData(*pair.Live, *pair.Staging)
+ pc.Error = joinPageErrors(*pair.Live, *pair.Staging)
+ if err := compareVisual(&pc, pair, outcome.DiffImages); err != nil {
+ return CompareOutcome{}, fmt.Errorf("page %q: %w", pair.Path, err)
+ }
+ }
+ if pc.changed() {
+ outcome.Report.HasDiffs = true
+ }
+ outcome.Report.Pages = append(outcome.Report.Pages, pc)
+ }
+ return outcome, nil
+}
+
+// compareVisual runs the visual diff for a fully-paired page when both
+// sides carry screenshots, storing the annotated image for changed pairs.
+func compareVisual(pc *PageComparison, pair PagePair, images map[string][]byte) error {
+ if pair.Live.Screenshot == "" || pair.Staging.Screenshot == "" {
+ return nil
+ }
+ liveImg, err := decodeScreenshot(pair.Live.Screenshot)
+ if err != nil {
+ return fmt.Errorf("live screenshot: %w", err)
+ }
+ stagingImg, err := decodeScreenshot(pair.Staging.Screenshot)
+ if err != nil {
+ return fmt.Errorf("staging screenshot: %w", err)
+ }
+
+ res, err := visualdiff.Compare(liveImg, stagingImg, visualdiff.Options{
+ Tolerance: compareTolerance,
+ IgnoreAntiAliasing: true,
+ })
+ if err != nil {
+ return err
+ }
+ pc.DiffPercentage = &res.DiffPercentage
+ if res.PixelsChanged == 0 {
+ return nil
+ }
+
+ var buf bytes.Buffer
+ if err := visualdiff.WriteAnnotatedPNG(&buf, liveImg, res); err != nil {
+ return fmt.Errorf("annotate: %w", err)
+ }
+ images[pair.Path] = buf.Bytes()
+ return nil
+}
+
+func decodeScreenshot(b64 string) (image.Image, error) {
+ data, err := base64.StdEncoding.DecodeString(b64)
+ if err != nil {
+ return nil, err
+ }
+ return png.Decode(bytes.NewReader(data))
+}
+
+// diffPageData compares the data-level audit fields of a page pair. Timing
+// deltas under timingDriftThresholdMs are run-to-run noise, not drift.
+func diffPageData(live, staging PageResult) []DataDrift {
+ drift := []DataDrift{}
+ record := func(field string, liveVal, stagingVal any) {
+ drift = append(drift, DataDrift{
+ Field: field,
+ Live: fmt.Sprintf("%v", liveVal),
+ Staging: fmt.Sprintf("%v", stagingVal),
+ })
+ }
+
+ liveErrs, stagingErrs := consoleErrorCount(live), consoleErrorCount(staging)
+ if liveErrs != stagingErrs {
+ record("consoleErrors", liveErrs, stagingErrs)
+ }
+ if lb, sb := len(live.Browser.BrokenAssets), len(staging.Browser.BrokenAssets); lb != sb {
+ record("brokenAssets", lb, sb)
+ }
+ if live.Browser.AccessibilityScore != staging.Browser.AccessibilityScore {
+ record("accessibilityScore", live.Browser.AccessibilityScore, staging.Browser.AccessibilityScore)
+ }
+ if delta := math.Abs(live.Browser.TimingMetrics.Load - staging.Browser.TimingMetrics.Load); delta > timingDriftThresholdMs {
+ record("loadMs", live.Browser.TimingMetrics.Load, staging.Browser.TimingMetrics.Load)
+ }
+ return drift
+}
+
+func consoleErrorCount(p PageResult) int {
+ n := 0
+ for _, l := range p.Browser.ConsoleLogs {
+ if l.Level == "error" {
+ n++
+ }
+ }
+ return n
+}
+
+func joinPageErrors(live, staging PageResult) string {
+ var parts []string
+ if live.Error != "" {
+ parts = append(parts, "live: "+live.Error)
+ }
+ if staging.Error != "" {
+ parts = append(parts, "staging: "+staging.Error)
+ }
+ return strings.Join(parts, "; ")
+}
diff --git a/internal/audit/compare_test.go b/internal/audit/compare_test.go
new file mode 100644
index 00000000..5e4bcf80
--- /dev/null
+++ b/internal/audit/compare_test.go
@@ -0,0 +1,171 @@
+package audit
+
+import (
+ "bytes"
+ "encoding/base64"
+ "image"
+ "image/color"
+ "image/draw"
+ "image/png"
+ "testing"
+)
+
+func page(url string, opts ...func(*PageResult)) PageResult {
+ p := PageResult{URL: url}
+ for _, o := range opts {
+ o(&p)
+ }
+ return p
+}
+
+func TestPairPagesByPath(t *testing.T) {
+ live := []PageResult{
+ page("http://x/live/"),
+ page("http://x/live/a.html"),
+ page("http://x/live/only-live.html"),
+ }
+ staging := []PageResult{
+ page("http://y/stage/"),
+ page("http://y/stage/a.html"),
+ page("http://y/stage/only-staging.html"),
+ }
+ pairs := PairPages("http://x/live/", "http://y/stage/", live, staging)
+ if len(pairs) != 4 {
+ t.Fatalf("pairs = %d, want 4", len(pairs))
+ }
+ if pairs[0].Path != "" || pairs[0].Live == nil || pairs[0].Staging == nil {
+ t.Errorf("base pair = %+v", pairs[0])
+ }
+ if pairs[1].Path != "a.html" || pairs[1].Live == nil || pairs[1].Staging == nil {
+ t.Errorf("a.html pair = %+v", pairs[1])
+ }
+ if pairs[2].Path != "only-live.html" || pairs[2].Staging != nil {
+ t.Errorf("live-only pair = %+v", pairs[2])
+ }
+ if pairs[3].Path != "only-staging.html" || pairs[3].Live != nil {
+ t.Errorf("staging-only pair = %+v", pairs[3])
+ }
+}
+
+func TestComparePagesAddedRemovedStatuses(t *testing.T) {
+ live := AuditReport{Pages: []PageResult{page("http://x/l/gone.html")}}
+ staging := AuditReport{Pages: []PageResult{page("http://y/s/new.html")}}
+ outcome, err := ComparePages("http://x/l/", "http://y/s/", live, staging)
+ if err != nil {
+ t.Fatalf("ComparePages: %v", err)
+ }
+ if outcome.Report.Pages[0].Status != CompareStatusRemoved {
+ t.Errorf("live-only status = %q", outcome.Report.Pages[0].Status)
+ }
+ if outcome.Report.Pages[1].Status != CompareStatusAdded {
+ t.Errorf("staging-only status = %q", outcome.Report.Pages[1].Status)
+ }
+ if !outcome.Report.HasDiffs {
+ t.Error("added/removed pages should count as diffs")
+ }
+}
+
+func TestDiffPageDataIdentical(t *testing.T) {
+ a := page("http://x/p", func(p *PageResult) {
+ p.Browser.AccessibilityScore = 100
+ p.Browser.TimingMetrics.Load = 20
+ })
+ b := page("http://y/p", func(p *PageResult) {
+ p.Browser.AccessibilityScore = 100
+ p.Browser.TimingMetrics.Load = 400 // below drift threshold: noise
+ })
+ if drift := diffPageData(a, b); len(drift) != 0 {
+ t.Errorf("drift = %+v, want none", drift)
+ }
+}
+
+func TestDiffPageDataFields(t *testing.T) {
+ a := page("http://x/p", func(p *PageResult) {
+ p.Browser.AccessibilityScore = 100
+ p.Browser.ConsoleLogs = []ConsoleLogEntry{{Level: "error"}, {Level: "log"}}
+ p.Browser.TimingMetrics.Load = 100
+ })
+ b := page("http://y/p", func(p *PageResult) {
+ p.Browser.AccessibilityScore = 80
+ p.Browser.BrokenAssets = []BrokenAsset{{URL: "x"}}
+ p.Browser.TimingMetrics.Load = 2000
+ })
+ drift := diffPageData(a, b)
+ fields := map[string]bool{}
+ for _, d := range drift {
+ fields[d.Field] = true
+ }
+ for _, want := range []string{"consoleErrors", "brokenAssets", "accessibilityScore", "loadMs"} {
+ if !fields[want] {
+ t.Errorf("missing drift field %q in %+v", want, drift)
+ }
+ }
+}
+
+func encodeShot(t *testing.T, c color.RGBA, w, h int) string {
+ t.Helper()
+ img := image.NewRGBA(image.Rect(0, 0, w, h))
+ draw.Draw(img, img.Bounds(), image.NewUniform(c), image.Point{}, draw.Src)
+ var buf bytes.Buffer
+ if err := png.Encode(&buf, img); err != nil {
+ t.Fatal(err)
+ }
+ return base64.StdEncoding.EncodeToString(buf.Bytes())
+}
+
+func TestComparePagesVisualDiff(t *testing.T) {
+ white := encodeShot(t, color.RGBA{255, 255, 255, 255}, 16, 16)
+ red := encodeShot(t, color.RGBA{200, 0, 0, 255}, 16, 16)
+
+ live := AuditReport{Pages: []PageResult{
+ page("http://x/l/same.html", func(p *PageResult) { p.Screenshot = white }),
+ page("http://x/l/diff.html", func(p *PageResult) { p.Screenshot = white }),
+ }}
+ staging := AuditReport{Pages: []PageResult{
+ page("http://y/s/same.html", func(p *PageResult) { p.Screenshot = white }),
+ page("http://y/s/diff.html", func(p *PageResult) { p.Screenshot = red }),
+ }}
+
+ outcome, err := ComparePages("http://x/l/", "http://y/s/", live, staging)
+ if err != nil {
+ t.Fatalf("ComparePages: %v", err)
+ }
+
+ same := outcome.Report.Pages[0]
+ if same.DiffPercentage == nil || *same.DiffPercentage != 0 {
+ t.Errorf("identical pair DiffPercentage = %v, want 0", same.DiffPercentage)
+ }
+ if len(same.Drift) != 0 {
+ t.Errorf("identical pair drift = %+v", same.Drift)
+ }
+ if _, ok := outcome.DiffImages["same.html"]; ok {
+ t.Error("identical pair should not produce a diff image")
+ }
+
+ diff := outcome.Report.Pages[1]
+ if diff.DiffPercentage == nil || *diff.DiffPercentage <= 0 {
+ t.Errorf("changed pair DiffPercentage = %v, want > 0", diff.DiffPercentage)
+ }
+ if _, ok := outcome.DiffImages["diff.html"]; !ok {
+ t.Error("changed pair should produce an annotated diff image")
+ }
+ if !outcome.Report.HasDiffs {
+ t.Error("HasDiffs should be true")
+ }
+}
+
+func TestComparePagesNoScreenshots(t *testing.T) {
+ live := AuditReport{Pages: []PageResult{page("http://x/l/p.html")}}
+ staging := AuditReport{Pages: []PageResult{page("http://y/s/p.html")}}
+ outcome, err := ComparePages("http://x/l/", "http://y/s/", live, staging)
+ if err != nil {
+ t.Fatalf("ComparePages: %v", err)
+ }
+ pc := outcome.Report.Pages[0]
+ if pc.DiffPercentage != nil {
+ t.Errorf("DiffPercentage = %v, want nil without screenshots", pc.DiffPercentage)
+ }
+ if outcome.Report.HasDiffs {
+ t.Error("no screenshots and no drift should not be a diff")
+ }
+}
diff --git a/internal/cli/actions/actions_compare.go b/internal/cli/actions/actions_compare.go
new file mode 100644
index 00000000..7be24a55
--- /dev/null
+++ b/internal/cli/actions/actions_compare.go
@@ -0,0 +1,147 @@
+package actions
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/pinchtab/pinchtab/internal/audit"
+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/spf13/cobra"
+)
+
+// Compare audits the same pages on two base URLs and reports visual and
+// data differences per page.
+func Compare(client *http.Client, base, token string, cmd *cobra.Command, liveBase, stagingBase string) {
+ paths := comparePaths(cmd)
+ visual := mustBool(cmd, "visual-diff")
+ concurrency, _ := cmd.Flags().GetInt("concurrency")
+
+ longClient := &http.Client{Transport: client.Transport, Timeout: auditTimeout}
+ runSide := func(siteBase string) audit.AuditReport {
+ body := map[string]any{
+ "urls": joinPaths(siteBase, paths),
+ "options": map[string]any{"screenshot": visual},
+ }
+ if concurrency > 0 {
+ body["concurrency"] = concurrency
+ }
+ raw := apiclient.DoPostRaw(longClient, base, token, "/audit", body)
+ var report audit.AuditReport
+ if err := json.Unmarshal(raw, &report); err != nil {
+ fmt.Fprintf(os.Stderr, "parse audit report for %s: %v\n", siteBase, err)
+ os.Exit(1)
+ }
+ return report
+ }
+
+ liveReport := runSide(liveBase)
+ stagingReport := runSide(stagingBase)
+
+ outcome, err := audit.ComparePages(liveBase, stagingBase, liveReport, stagingReport)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "compare: %v\n", err)
+ os.Exit(1)
+ }
+
+ if dir, _ := cmd.Flags().GetString("output-dir"); dir != "" {
+ if err := writeCompareArtifacts(dir, &outcome); err != nil {
+ fmt.Fprintf(os.Stderr, "write artifacts: %v\n", err)
+ os.Exit(1)
+ }
+ fmt.Fprintf(os.Stderr, "report written to %s\n", filepath.Join(dir, "report.json"))
+ }
+
+ if mustBool(cmd, "json") {
+ out, _ := json.MarshalIndent(outcome.Report, "", " ")
+ fmt.Println(string(out))
+ } else {
+ printCompareSummary(outcome.Report)
+ }
+
+ if mustBool(cmd, "fail-on-diff") && outcome.Report.HasDiffs {
+ fmt.Fprintln(os.Stderr, "differences found (--fail-on-diff)")
+ os.Exit(1)
+ }
+}
+
+func comparePaths(cmd *cobra.Command) []string {
+ raw := mustString(cmd, "pages")
+ if raw == "" {
+ return []string{""}
+ }
+ var paths []string
+ for _, p := range strings.Split(raw, ",") {
+ paths = append(paths, strings.TrimSpace(p))
+ }
+ return paths
+}
+
+func joinPaths(siteBase string, paths []string) []string {
+ urls := make([]string, 0, len(paths))
+ for _, p := range paths {
+ if p == "" {
+ urls = append(urls, siteBase)
+ continue
+ }
+ urls = append(urls, strings.TrimSuffix(siteBase, "/")+"/"+strings.TrimPrefix(p, "/"))
+ }
+ return urls
+}
+
+// writeCompareArtifacts writes report.json and diffs/<path>.png under dir,
+// filling each page's diffImagePath before the report is serialized.
+func writeCompareArtifacts(dir string, outcome *audit.CompareOutcome) error {
+ diffsDir := filepath.Join(dir, "diffs")
+ if err := os.MkdirAll(diffsDir, 0o755); err != nil {
+ return err
+ }
+
+ for i := range outcome.Report.Pages {
+ pc := &outcome.Report.Pages[i]
+ data, ok := outcome.DiffImages[pc.Path]
+ if !ok {
+ continue
+ }
+ relPath := filepath.Join("diffs", diffImageName(pc.Path))
+ if err := os.WriteFile(filepath.Join(dir, relPath), data, 0o644); err != nil {
+ return err
+ }
+ pc.DiffImagePath = relPath
+ }
+
+ out, err := json.MarshalIndent(outcome.Report, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(filepath.Join(dir, "report.json"), out, 0o644)
+}
+
+func diffImageName(path string) string {
+ if path == "" {
+ path = "index"
+ }
+ safe := strings.NewReplacer("/", "_", "\\", "_", ":", "_", "?", "_", "&", "_").Replace(path)
+ return safe + ".diff.png"
+}
+
+func printCompareSummary(report audit.ComparisonReport) {
+ fmt.Printf("Compared %d page(s) · diffs: %v\n", len(report.Pages), report.HasDiffs)
+ for _, p := range report.Pages {
+ label := p.Path
+ if label == "" {
+ label = "(base)"
+ }
+ switch {
+ case p.Status != audit.CompareStatusCompared:
+ fmt.Printf(" %s · %s\n", label, p.Status)
+ case p.DiffPercentage != nil:
+ fmt.Printf(" %s · visual %.2f%% · drift %d\n", label, *p.DiffPercentage, len(p.Drift))
+ default:
+ fmt.Printf(" %s · drift %d\n", label, len(p.Drift))
+ }
+ }
+}
diff --git a/tests/e2e/scenarios/cli/compare-basic.sh b/tests/e2e/scenarios/cli/compare-basic.sh
new file mode 100755
index 00000000..87b235d2
--- /dev/null
+++ b/tests/e2e/scenarios/cli/compare-basic.sh
@@ -0,0 +1,65 @@
+#!/bin/bash
+# compare-basic.sh — pinchtab compare live-vs-staging happy path.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../../helpers/cli.sh"
+
+LIVE="http://fixtures/audit-site/"
+STAGING="http://fixtures/audit-site-staging/"
+OUT_DIR=$(mktemp -d /tmp/compare-cli.XXXXXX)
+
+# ─────────────────────────────────────────────────────────────────
+start_test "compare writes report and annotated diff for changed page"
+
+pt_ok compare "$LIVE" "$STAGING" --pages index.html,clean.html --output-dir "$OUT_DIR"
+
+REPORT="$OUT_DIR/report.json"
+if [ -f "$REPORT" ]; then
+ pass_assert "report.json exists"
+else
+ fail_assert "report.json exists"
+fi
+
+CLEAN=$(jq '.pages[] | select(.path == "clean.html")' "$REPORT" 2>/dev/null)
+if echo "$CLEAN" | jq -e '.diffPercentage == 0' >/dev/null 2>&1; then
+ pass_assert "clean.html diffPercentage == 0"
+else
+ fail_assert "clean.html diffPercentage == 0 (got: $(echo "$CLEAN" | jq '.diffPercentage'))"
+fi
+if echo "$CLEAN" | jq -e '.drift | length == 0' >/dev/null 2>&1; then
+ pass_assert "clean.html has zero data-drift entries"
+else
+ fail_assert "clean.html has zero data-drift entries (got: $(echo "$CLEAN" | jq -c '.drift'))"
+fi
+
+INDEX=$(jq '.pages[] | select(.path == "index.html")' "$REPORT" 2>/dev/null)
+if echo "$INDEX" | jq -e '.diffPercentage > 0' >/dev/null 2>&1; then
+ pass_assert "index.html diffPercentage > 0 ($(echo "$INDEX" | jq '.diffPercentage'))"
+else
+ fail_assert "index.html diffPercentage > 0 (got: $(echo "$INDEX" | jq '.diffPercentage'))"
+fi
+
+DIFF_IMAGE=$(echo "$INDEX" | jq -r '.diffImagePath // empty')
+if [ -n "$DIFF_IMAGE" ] && [ -f "$OUT_DIR/$DIFF_IMAGE" ]; then
+ pass_assert "annotated diff image on disk ($DIFF_IMAGE)"
+else
+ fail_assert "annotated diff image on disk (path: $DIFF_IMAGE)"
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "--fail-on-diff exits non-zero when pages differ"
+
+pt_fail compare "$LIVE" "$STAGING" --pages index.html --fail-on-diff
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "--fail-on-diff exits 0 when pages are identical"
+
+pt_ok compare "$LIVE" "$STAGING" --pages clean.html --fail-on-diff
+
+end_test
+
+rm -rf "$OUT_DIR"