feat: redesign HTML report with premium UI and visual testing

Self-contained single HTML file, zero external dependencies, works offline.

Views: Both (side-by-side) | Base only | New only | Heatmap
- Annotation toggle (key A) switches between original and annotated images
- Per-image zoom with synchronized drag-to-pan across panels
- Ctrl/Cmd/Alt + scroll wheel zoom, click image to toggle annotations
- Keyboard shortcuts: 1-4 views, arrows navigate, / search, +/- zoom

Reporter:
- Public render/template_path API, diff stats (diff_level, area_size)
- Percentage badge in topbar and sidebar (e.g. "2.34% diff")
- Path existence check, idempotent finalize, DEBUG-only diagnostics

Tests:
- Unit tests use real ImageCompare objects (no Struct stubs)
- 5 screenshot integration tests with perceptual_threshold
- HTML reporter enabled for all integration tests via system_test_case
- Rake report:sample task for manual testing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pftg

Rakefile

@@ -29,6 +29,11 @@ task :coverage do
   Rake::Task["test"].invoke
 end
 
+desc "Generate sample HTML report for manual testing"
+task "report:sample" do
+  ruby "scripts/generate_sample_report.rb"
+end
+
 task "clobber" do
   puts "Cleanup tmp/*.png"
   FileUtils.rm_rf(Dir["./tmp/*"])

lib/capybara_screenshot_diff/reporters/html.rb

@@ -10,11 +10,12 @@ module Reporters
     class HTML
       attr_reader :output_path, :failures, :total
 
-      def initialize(output_path: "tmp/snap_diff-report/index.html")
+      def initialize(output_path: "tmp/snap_diff/index.html")
         @output_path = Pathname.new(output_path)
         @report_dir = @output_path.dirname
         @failures = []
         @total = 0
+        @finalized = false
       end
 
       def record(assertions)
@@ -27,15 +28,22 @@ def record(assertions)
 
           @failures << failure_entry_for(assertion.name, compare)
         rescue => e
-          warn "[snap_diff] Reporter skipped '#{assertion.name}': #{e.message}"
+          warn "[snap_diff] Reporter skipped '#{assertion.name}': #{e.message}" if ENV["DEBUG"]
         end
       end
 
       def finalize
-        return if failures.empty?
+        return if @finalized
+
+        @finalized = true
+
+        if failures.empty?
+          warn "[snap_diff] No failures found, HTML report not generated" if ENV["DEBUG"]
+          return
+        end
 
         write_report
-        $stdout.puts "[snap_diff] HTML report: #{output_path}"
+        true
       end
 
       def passed = total - failures.size
@@ -46,33 +54,44 @@ def success_rate
         (passed.to_f / total * 100).round(1)
       end
 
+      def render
+        ERB.new(File.read(self.class.template_path)).result(binding)
+      end
+
+      def self.template_path
+        File.expand_path("templates/report.html.erb", __dir__)
+      end
+
       private
 
       def failure_entry_for(name, compare)
+        difference = compare.difference
         {
           name: name,
           original: relative_path(compare.base_image_path),
           new: relative_path(compare.image_path),
+          base_diff: relative_path(compare.reporter.annotated_base_image_path),
           diff: relative_path(compare.reporter.annotated_image_path),
-          heatmap: relative_path(compare.reporter.heatmap_diff_path)
+          heatmap: relative_path(compare.reporter.heatmap_diff_path),
+          diff_level: difference.ratio && (difference.ratio * 100).round(2),
+          area_size: difference.region_area_size,
+          max_color_distance: difference.meta[:max_color_distance]&.round(1)
         }
       end
 
       def relative_path(path)
-        return "" unless path
+        return unless path
 
-        Pathname.new(path).relative_path_from(@report_dir).to_s
-      rescue ArgumentError
-        path.to_s
+        pathname = Pathname.new(path)
+        return unless pathname.exist?
+
+        pathname.relative_path_from(@report_dir).to_s
       end
 
       def write_report
         FileUtils.mkdir_p(@report_dir)
-        File.write(output_path, ERB.new(File.read(template_path)).result(binding))
+        File.write(output_path, render)
       end
-
-      def template_path = File.expand_path("templates/report.html.erb", __dir__)
-      def failed_screenshots = failures
     end
   end
 end
@@ -83,9 +102,9 @@ def failed_screenshots = failures
 
 at_exit do
   CapybaraScreenshotDiff.reporters.each do |reporter|
-    reporter.finalize
+    wrote = reporter.finalize
+    $stdout.puts "[snap_diff] HTML report: #{reporter.output_path}" if wrote
   rescue => e
-    warn "[snap_diff] Reporter #{reporter.class} failed (#{e.class}: #{e.message})"
-    warn e.full_message(highlight: false) if e.respond_to?(:full_message)
+    warn "[snap_diff] Reporter #{reporter.class} failed (#{e.class}: #{e.message})" if ENV["DEBUG"]
   end
 end

lib/capybara_screenshot_diff/reporters/templates/report.html.erb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Generate a sample HTML report for manual testing.
+# Uses absolute file:// paths so images load when opened directly in a browser.
+
+require "bundler/setup"
+require "capybara_screenshot_diff"
+require "capybara_screenshot_diff/minitest"
+require "capybara/screenshot/diff"
+require "capybara_screenshot_diff/reporters/html"
+
+output_path = File.expand_path("../tmp/sample_report.html", __dir__)
+
+# Build real comparisons using the gem's own ImageCompare.
+# Each pair gets a unique copy of the base image to avoid annotation file conflicts.
+pairs = [
+  {name: "islands-map", base: "a", new: "b"},
+  {name: "islands-variant", base: "a", new: "c"},
+  {name: "portrait-layout", base: "portrait", new: "portrait_b"}
+]
+
+reporter = CapybaraScreenshotDiff::Reporters::HTML.new(output_path: output_path)
+fixtures = File.expand_path("../test/fixtures/images", __dir__)
+tmp_dir = File.expand_path("../tmp/sample_images", __dir__)
+FileUtils.mkdir_p(tmp_dir)
+
+assertions = pairs.map do |pair|
+  # Copy to tmp so each comparison has its own base/new files for annotations
+  base_copy = "#{tmp_dir}/#{pair[:name]}_base.png"
+  new_copy = "#{tmp_dir}/#{pair[:name]}_new.png"
+  FileUtils.cp("#{fixtures}/#{pair[:base]}.png", base_copy)
+  FileUtils.cp("#{fixtures}/#{pair[:new]}.png", new_copy)
+
+  compare = Capybara::Screenshot::Diff::ImageCompare.new(new_copy, base_copy, driver: :vips)
+  compare.processed
+
+  CapybaraScreenshotDiff::ScreenshotAssertion.new(pair[:name]).tap { |a| a.compare = compare }
+end
+
+# Add passing assertions (identical images = no difference)
+passing = %w[dashboard settings profile users].map do |name|
+  compare = Capybara::Screenshot::Diff::ImageCompare.new("#{fixtures}/a.png", "#{fixtures}/a.png")
+  compare.processed
+  CapybaraScreenshotDiff::ScreenshotAssertion.new(name).tap { |a| a.compare = compare }
+end
+
+reporter.record(assertions + passing)
+reporter.finalize
+
+puts "Screenshots: #{reporter.failed} failed, #{reporter.passed} passed, #{reporter.total} total"

scripts/generate_sample_report.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "system_test_case"
+
+class ReportScreenshotTest < SystemTestCase
+  PERCEPTUAL_THRESHOLD = 2.0
+
+  setup do
+    screenshot_section "html_report"
+
+    @report_dir = Pathname.new("test/fixtures/app/report")
+    @report_path = @report_dir / "index.html"
+    skip "Run with RECORD_SCREENSHOTS=1 to update report fixtures" unless ENV["RECORD_SCREENSHOTS"]
+    generate_sample_report
+    visit "/report/index.html"
+  end
+
+  teardown do
+    FileUtils.rm_rf(@report_dir)
+  end
+
+  def test_report_both_view
+    screenshot "report_both", perceptual_threshold: PERCEPTUAL_THRESHOLD
+  end
+
+  def test_report_base_view
+    find("[data-view='base']").click
+    screenshot "report_base", perceptual_threshold: PERCEPTUAL_THRESHOLD
+  end
+
+  def test_report_new_view
+    find("[data-view='new']").click
+    screenshot "report_new", perceptual_threshold: PERCEPTUAL_THRESHOLD
+  end
+
+  def test_report_heatmap_view
+    find("[data-view='heatmap']").click
+    screenshot "report_heatmap", perceptual_threshold: PERCEPTUAL_THRESHOLD
+  end
+
+  def test_report_annotated_both
+    find("#annotate-toggle").click
+    screenshot "report_annotated_both", perceptual_threshold: PERCEPTUAL_THRESHOLD
+  end
+
+  private
+
+  def generate_sample_report
+    img_dir = @report_dir / "images"
+    img_dir.mkpath
+
+    # Copy fixtures into served directory so browser can load them
+    fixtures = Pathname.new("test/fixtures/images")
+    %w[a.png b.png c.png].each { |f| FileUtils.cp(fixtures / f, img_dir / f) }
+
+    # Run real comparisons inside the served directory
+    assertions = [
+      build_assertion("islands-map", img_dir / "a.png", img_dir / "b.png"),
+      build_assertion("islands-variant", img_dir / "a.png", img_dir / "c.png")
+    ]
+
+    reporter = CapybaraScreenshotDiff::Reporters::HTML.new(output_path: @report_path)
+    reporter.record(assertions)
+    reporter.finalize
+  end
+
+  def build_assertion(name, base_path, new_path)
+    # Copy to unique files so shared base images don't overwrite each other's annotations
+    unique_base = @report_dir / "images" / "#{name}_base.png"
+    unique_new = @report_dir / "images" / "#{name}_new.png"
+    FileUtils.cp(base_path, unique_base)
+    FileUtils.cp(new_path, unique_new)
+
+    compare = Capybara::Screenshot::Diff::ImageCompare.new(unique_new, unique_base, driver: :vips)
+    compare.processed
+    CapybaraScreenshotDiff::ScreenshotAssertion.new(name).tap { |a| a.compare = compare }
+  end
+end