feat: add HTML reporter for visual diff dashboard

pftg · claude · pftg · commit 861183f920d9 · 2026-04-12T03:48:27.000+02:00
Interactive HTML report generated automatically when required:

  require 'capybara_screenshot_diff/reporters/html'

Features:
- Side-by-side baseline vs current with diff toggle
- Searchable sidebar with thumbnails
- Summary stats (total/failed/passed/success rate)
- Zero config — at_exit hook auto-generates report
- Based on prototype from showcase project (Tailwind + Alpine.js)

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -736,6 +736,49 @@ Capybara::Screenshot.capybara_screenshot_options[:full_page] = true
 screenshot('index', median_filter_window_size: 2, capybara_screenshot_options: {full_page: false})
 ```
 
+### HTML Report
+
+Generate an interactive HTML report of screenshot differences:
+
+```ruby
+# Add to test_helper.rb — one line, that's it
+require 'capybara_screenshot_diff/reporters/html'
+```
+
+After running tests, open the report (generated only when there are failures):
+
+```bash
+open tmp/snap_diff-report/index.html
+```
+
+The report includes a sidebar with thumbnails, side-by-side comparison with diff toggle, search, and summary stats. No configuration needed — just require it.
+
+**Note:** The report is not generated when all screenshots match. In parallel test environments, each worker writes to the same file — the last worker's results will be in the report.
+
+### Custom Reporters
+
+Build your own reporter by implementing `record` and `finalize`:
+
+```ruby
+class MyReporter
+  def record(assertions)
+    assertions.each do |assertion|
+      next unless assertion.compare&.difference&.different?
+      # process the failure — send to Slack, write JSON, etc.
+    end
+  end
+
+  def finalize
+    # called once at process exit — write summary, upload report, etc.
+  end
+end
+
+# Register in test_helper.rb
+CapybaraScreenshotDiff.reporters << MyReporter.new
+```
+
+Reporters are notified before assertions are cleared on each test teardown. `finalize` is called via `at_exit`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
diff --git a/lib/capybara_screenshot_diff/reporters/html.rb b/lib/capybara_screenshot_diff/reporters/html.rb
@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "pathname"
+require "json"
+
+module CapybaraScreenshotDiff
+  module Reporters
+    class HTML
+      attr_reader :output_path, :failures, :total
+
+      def initialize(output_path: "tmp/snap_diff-report/index.html")
+        @output_path = Pathname.new(output_path)
+        @report_dir = @output_path.dirname
+        @failures = []
+        @total = 0
+      end
+
+      def record(assertions)
+        assertions.each do |assertion|
+          compare = assertion.compare
+          next unless compare
+
+          @total += 1
+          next unless compare.difference&.different?
+
+          @failures << failure_entry_for(assertion.name, compare)
+        rescue => e
+          warn "[snap_diff] Reporter skipped '#{assertion.name}': #{e.message}"
+        end
+      end
+
+      def finalize
+        return if failures.empty?
+
+        write_report
+        $stdout.puts "[snap_diff] HTML report: #{output_path}"
+      end
+
+      def passed = total - failures.size
+      def failed = failures.size
+
+      def success_rate
+        return 0 if total.zero?
+        (passed.to_f / total * 100).round(1)
+      end
+
+      private
+
+      def failure_entry_for(name, compare)
+        {
+          name: name,
+          original: relative_path(compare.base_image_path),
+          new: relative_path(compare.image_path),
+          diff: relative_path(compare.reporter.annotated_image_path),
+          heatmap: relative_path(compare.reporter.heatmap_diff_path)
+        }
+      end
+
+      def relative_path(path)
+        return "" unless path
+
+        Pathname.new(path).relative_path_from(@report_dir).to_s
+      rescue ArgumentError
+        path.to_s
+      end
+
+      def write_report
+        FileUtils.mkdir_p(@report_dir)
+        File.write(output_path, ERB.new(File.read(template_path)).result(binding))
+      end
+
+      def template_path = File.expand_path("templates/report.html.erb", __dir__)
+      def failed_screenshots = failures
+    end
+  end
+end
+
+unless CapybaraScreenshotDiff.reporters.any?(CapybaraScreenshotDiff::Reporters::HTML)
+  CapybaraScreenshotDiff.reporters << CapybaraScreenshotDiff::Reporters::HTML.new
+end
+
+at_exit do
+  CapybaraScreenshotDiff.reporters.each do |reporter|
+    reporter.finalize
+  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)
+  end
+end
diff --git a/lib/capybara_screenshot_diff/reporters/templates/report.html.erb b/lib/capybara_screenshot_diff/reporters/templates/report.html.erb
@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html class="h-full bg-white">
+<head>
+    <meta charset="UTF-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+    <title>Screenshot Diff Report — <%= failed %> failures</title>
+    <script src="https://cdn.tailwindcss.com?plugins=forms,typography,aspect-ratio"></script>
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
+</head>
+
+<body class="h-full overflow-hidden">
+<div x-data>
+    <div class="flex h-screen">
+        <div class="flex min-w-0 flex-1 flex-col overflow-hidden">
+
+            <!-- Summary Bar -->
+            <div class="bg-gray-50 border-b px-6 py-3 flex items-center justify-between">
+                <h1 class="text-lg font-semibold text-gray-900">Screenshot Diff Report</h1>
+                <div class="flex gap-4 text-sm">
+                    <span class="text-gray-600">Total: <strong><%= total %></strong></span>
+                    <span class="text-red-600">Failed: <strong><%= failed %></strong></span>
+                    <span class="text-green-600">Passed: <strong><%= passed %></strong></span>
+                    <span class="text-gray-500">(<%= success_rate %>%)</span>
+                </div>
+            </div>
+
+            <div class="relative z-0 flex flex-1 overflow-hidden">
+
+                <!-- Main Content -->
+                <main class="relative z-0 flex-1 overflow-y-auto focus:outline-none sm:order-last p-6">
+                    <div x-data="{items: $store.screenshots.items}">
+                        <template x-for="(item, id) in items">
+                            <article x-show="item.selected">
+                                <h2 class="text-lg font-medium text-gray-900 mb-4" x-text="item.name"></h2>
+
+                                <div class="mb-4">
+                                    <button @click="$store.diff.toggle()"
+                                            :class="$store.diff.on ? 'bg-red-100 text-red-700' : 'bg-white text-gray-700'"
+                                            type="button"
+                                            class="inline-flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50">
+                                        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="w-5 h-5">
+                                            <path d="M16.5 6a3 3 0 0 0-3-3H6a3 3 0 0 0-3 3v7.5a3 3 0 0 0 3 3v-6A4.5 4.5 0 0 1 10.5 6h6Z"/>
+                                            <path d="M18 7.5a3 3 0 0 1 3 3V18a3 3 0 0 1-3 3h-7.5a3 3 0 0 1-3-3v-7.5a3 3 0 0 1 3-3H18Z"/>
+                                        </svg>
+                                        <span x-text="$store.diff.on ? 'Showing Diff' : 'Show Diff'"></span>
+                                    </button>
+                                </div>
+
+                                <div class="grid grid-cols-2 gap-4">
+                                    <div>
+                                        <p class="text-sm font-medium text-gray-500 mb-2">Baseline</p>
+                                        <div class="bg-black rounded-lg border overflow-hidden">
+                                            <img class="w-full" :alt="'Baseline: ' + item.name" :src="item.original">
+                                        </div>
+                                    </div>
+                                    <div>
+                                        <p class="text-sm font-medium text-gray-500 mb-2" x-text="$store.diff.on ? 'Diff' : 'Current'"></p>
+                                        <div class="bg-black rounded-lg border overflow-hidden">
+                                            <img class="w-full" :alt="'Current: ' + item.name" :src="$store.screenshots.comparison(id)">
+                                        </div>
+                                    </div>
+                                </div>
+                            </article>
+                        </template>
+                    </div>
+                </main>
+
+                <!-- Sidebar -->
+                <aside class="hidden w-72 border-r border-gray-200 sm:order-first sm:flex sm:flex-col">
+                    <div class="p-3">
+                        <input type="text"
+                               x-model="$store.screenshots.search"
+                               placeholder="Search screenshots..."
+                               class="w-full rounded-md border-gray-300 text-sm shadow-sm focus:border-indigo-500 focus:ring-indigo-500">
+                    </div>
+                    <nav class="flex-1 overflow-y-auto p-3" x-data="{items: $store.screenshots.items}">
+                        <template x-for="(item, id) in items">
+                            <div class="mb-2" x-show="item.name.toLowerCase().includes(($store.screenshots.search || '').toLowerCase())">
+                                <button @click="$store.screenshots.select(id)"
+                                        class="w-full text-left rounded-lg border-2 p-1 transition-colors"
+                                        :class="item.selected ? 'border-indigo-500 shadow-md' : 'border-transparent hover:border-gray-300'">
+                                    <div class="aspect-w-5 aspect-h-3 overflow-hidden rounded bg-black">
+                                        <img class="object-contain" :alt="item.name" :src="item.diff || item.new">
+                                    </div>
+                                    <p class="mt-1 truncate text-xs text-gray-600" x-text="item.name"></p>
+                                </button>
+                            </div>
+                        </template>
+                    </nav>
+                </aside>
+            </div>
+        </div>
+    </div>
+</div>
+
+<script>
+  document.addEventListener('alpine:init', () => {
+    Alpine.store('diff', {
+      on: false,
+      toggle() { this.on = !this.on }
+    })
+
+    Alpine.store('screenshots', {
+      current: 0,
+      search: '',
+      items: <%= failed_screenshots.to_json.gsub("</", "<\\/") %>,
+
+      select(id) {
+        if (this.items.length === 0) return
+        if (this.items[this.current]) this.items[this.current].selected = false
+        this.current = id
+        this.items[id].selected = true
+      },
+
+      comparison(id) {
+        return Alpine.store('diff').on ? this.items[id].diff : this.items[id].new
+      }
+    })
+
+    const store = Alpine.store('screenshots')
+    if (store.items.length > 0) store.select(0)
+  })
+</script>
+</body>
+</html>
diff --git a/lib/capybara_screenshot_diff/screenshot_assertion.rb b/lib/capybara_screenshot_diff/screenshot_assertion.rb
@@ -124,8 +124,28 @@ def registry
     def_delegator :registry, :assertions
     def_delegator :registry, :assertions_present?
     def_delegator :registry, :failed_assertions
-    def_delegator :registry, :reset
+    def reset
+      notify_reporters(registry.assertions)
+      registry.reset
+    end
+
+    def reporters
+      @reporters ||= []
+    end
+
     def_delegator :registry, :screenshot_namer
     def_delegator :registry, :verify
+
+    private
+
+    def notify_reporters(assertions)
+      return if reporters.empty? || assertions.nil? || assertions.empty?
+
+      reporters.each do |reporter|
+        reporter.record(assertions)
+      rescue => e
+        warn "[capybara-screenshot-diff] Reporter failed: #{e.message}"
+      end
+    end
   end
 end
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "capybara_screenshot_diff/reporters/html"
+
+module CapybaraScreenshotDiff
+  module Reporters
+    class HTMLReporterTest < ActiveSupport::TestCase
+      setup do
+        @output_dir = Pathname.new(Dir.mktmpdir)
+        @output_path = @output_dir / "report.html"
+      end
+
+      teardown do
+        FileUtils.remove_entry(@output_dir)
+      end
+
+      test "#format with no assertions writes nothing" do
+        reporter = HTML.new(output_path: @output_path)
+        reporter.record([])
+
+        assert_not @output_path.exist?
+      end
+
+      test "#format with passing assertions writes nothing" do
+        reporter = HTML.new(output_path: @output_path)
+
+        assertion = build_passing_assertion("index")
+        reporter.record([assertion])
+
+        assert_not @output_path.exist?
+      end
+
+      test "#record and #finalize with failing assertion generates HTML file" do
+        reporter = HTML.new(output_path: @output_path)
+
+        reporter.record([build_failing_assertion("index")])
+        reporter.finalize
+
+        assert @output_path.exist?
+        html = @output_path.read
+        assert_includes html, "<!DOCTYPE html>"
+        assert_includes html, "index"
+      end
+
+      test "#record and #finalize includes summary stats" do
+        reporter = HTML.new(output_path: @output_path)
+
+        reporter.record([
+          build_failing_assertion("page_a"),
+          build_passing_assertion("page_b"),
+          build_failing_assertion("page_c")
+        ])
+        reporter.finalize
+
+        html = @output_path.read
+        assert_match(/Total.*<strong>3<\/strong>/, html)
+        assert_match(/Failed.*<strong>2<\/strong>/, html)
+        assert_match(/Passed.*<strong>1<\/strong>/, html)
+      end
+
+      test "#record tolerates broken assertions without crashing" do
+        reporter = HTML.new(output_path: @output_path)
+
+        broken = ScreenshotAssertion.new("broken")
+        broken.compare = Object.new # will raise on .difference
+
+        valid = build_failing_assertion("valid")
+
+        assert_nothing_raised do
+          reporter.record([broken, valid])
+        end
+
+        reporter.finalize
+        assert @output_path.exist?
+        assert_includes @output_path.read, "valid"
+      end
+
+      private
+
+      def build_passing_assertion(name)
+        difference_stub = Struct.new(:different?).new(false)
+        compare_stub = Struct.new(:difference, :different?).new(difference_stub, false)
+        ScreenshotAssertion.new(name).tap { |a| a.compare = compare_stub }
+      end
+
+      def build_failing_assertion(name)
+        reporter_stub = Struct.new(:annotated_image_path, :annotated_base_image_path, :heatmap_diff_path)
+          .new(@output_dir / "#{name}.diff.png", @output_dir / "#{name}.base.diff.png", @output_dir / "#{name}.heatmap.diff.png")
+
+        difference_stub = Struct.new(:different?).new(true)
+        compare_stub = Struct.new(:difference, :different?, :base_image_path, :image_path, :reporter)
+          .new(difference_stub, true, @output_dir / "#{name}.base.png", @output_dir / "#{name}.png", reporter_stub)
+
+        ScreenshotAssertion.new(name).tap { |a| a.compare = compare_stub }
+      end
+    end
+  end
+end
