snap_diff-capybara 2.0.0.beta1 → 2.0.0.beta3

data/docs/snapdiff.md

@@ -0,0 +1,326 @@
+# SnapDiff — the canonical API
+
+Everything in this gem lives under `SnapDiff` since v2. This page is the SnapDiff-native
+reference: setup, configuration, the object map, and the extension points — all using canonical
+names only.
+
+The legacy `Capybara::Screenshot::Diff` / `CapybaraScreenshotDiff` names still work (they resolve
+to the same objects, with a one-time deprecation warning per constant), and the rest of the docs
+still teach them. Nothing here replaces a working setup — it is what you write for **new** code.
+For migrating an existing suite, see [UPGRADING.md](UPGRADING.md).
+
+## Quick start
+
+### Minitest
+
+```ruby
+# test/test_helper.rb
+require "snap_diff/integrations/minitest"
+```
+
+```ruby
+# test/application_system_test_case.rb
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include SnapDiff::Minitest::Assertions   # brings in SnapDiff::DSL too
+end
+```
+
+```ruby
+class HomepageTest < ApplicationSystemTestCase
+  test "homepage" do
+    visit "/"
+    assert_matches_screenshot "homepage"
+  end
+end
+```
+
+`SnapDiff::Minitest::Assertions` already includes `SnapDiff::DSL`, so a separate
+`include SnapDiff::DSL` is not needed (it is harmless if you have it).
+
+> **The require path is `snap_diff/integrations/…`, not `snap_diff/…`.**
+> `require "snap_diff/minitest"` raises `LoadError` — there is no such file. The integrations
+> live one level down, mirroring `lib/snap_diff/integrations/`.
+
+### RSpec
+
+```ruby
+# spec/rails_helper.rb
+require "snap_diff/integrations/rspec"
+```
+
+This registers the `match_screenshot` matcher and includes `SnapDiff::DSL` into
+`type: :feature` and `type: :system` examples automatically:
+
+```ruby
+RSpec.describe "Homepage", type: :system do
+  it "looks right" do
+    visit "/"
+    expect(page).to match_screenshot("homepage")
+  end
+end
+```
+
+For other example types, include the DSL yourself:
+
+```ruby
+RSpec.describe "Admin", type: :request do
+  include SnapDiff::DSL
+end
+```
+
+### Cucumber
+
+```ruby
+# features/support/env.rb
+require "snap_diff/integrations/cucumber"
+```
+
+The DSL is added to the Cucumber `World`, so steps can call `screenshot` /
+`assert_matches_screenshot` directly. This file must be loaded from inside a Cucumber run — it
+calls `World`, `Before`, `After` and `AfterAll` at load time and raises `NoMethodError` if
+required outside one.
+
+### Static sites (Hugo, Jekyll, plain HTML)
+
+```ruby
+require "snap_diff/static"
+
+SnapDiff.serve("_site")             # or "public", "build", "dist"
+SnapDiff.serve("_site", root: Dir.pwd)   # root defaults to Dir.pwd
+```
+
+`SnapDiff.serve` points Capybara at the built directory and sets the screenshot root. It also
+loads the Minitest integration. See
+[CI & Non-Rails Integration](ci-integration.md#non-rails-projects-hugo-jekyll-static-sites).
+
+## Configuration
+
+All 27 settings live on one flat object, `SnapDiff.config` (a `SnapDiff::Config`).
+
+```ruby
+# test_helper.rb / rails_helper.rb
+SnapDiff.configure do |config|
+  config.window_size = [1280, 1024]
+  config.tolerance = 0.0005
+  config.driver = :vips
+  config.save_path = "doc/screenshots"
+end
+
+# Or set them one at a time
+SnapDiff.config.hide_caret = true
+SnapDiff.config.tolerance          # => 0.0005
+```
+
+`SnapDiff::Config` **is** the storage. The legacy `Capybara::Screenshot.*` and
+`Capybara::Screenshot::Diff.*` accessors are thin delegators onto it — one storage, two views —
+so a write through either surface is immediately visible through the other:
+
+```ruby
+SnapDiff.config.window_size = [1280, 1024]
+Capybara::Screenshot.window_size    # => [1280, 1024]
+```
+
+`SnapDiff.start` is the same call shape as the old `Capybara::Screenshot::Diff.configure`, if
+you prefer the two-holder form:
+
+```ruby
+SnapDiff.start do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+  diff.tolerance = 0.0005
+end
+```
+
+Three derived, read-only values are computed from the settings above:
+
+| Method | What it returns |
+|--------|-----------------|
+| `SnapDiff.config.active?` | Whether screenshots are taken at all (ex `Capybara::Screenshot.active?`) |
+| `SnapDiff.config.screenshot_area` | `save_path`, optionally segmented per OS and per Capybara driver |
+| `SnapDiff.config.default_options` | The capture/compare defaults handed to `SnapDiff::Comparison` |
+
+Every option's meaning is documented in the
+[Configuration Reference](configuration.md) — the names are identical, only the receiver differs.
+The one rename: `Capybara::Screenshot.enabled` is `SnapDiff.config.screenshot_enabled`, because
+`SnapDiff.config.enabled` is taken by `Capybara::Screenshot::Diff.enabled`.
+
+## Object map
+
+`require "snap_diff"` gives you the compare/configure core. The test-suite pieces come with the
+integration require; a few objects need their own require, noted below.
+
+| Object | What it is for |
+|--------|----------------|
+| `SnapDiff.config`, `SnapDiff::Config` | Every setting, one flat object. The storage. |
+| `SnapDiff.configure`, `SnapDiff.start` | Config block helpers (consolidated / v1 shape) |
+| `SnapDiff.compare` | Compare two image files directly, no browser |
+| `SnapDiff::Comparison` | The layered comparison engine (ex `ImageCompare`) |
+| `SnapDiff::Comparison::Images` | Frozen bundle a comparison operates on: both images, their paths, the driver and the options |
+| `SnapDiff::ComparisonResult` | Result value object: `different?`, region, metadata (ex `Difference`) |
+| `SnapDiff::Region` | Bounding box value object — `from_edge_coordinates`, `to_edge_coordinates` |
+| `SnapDiff::DSL` | `screenshot`, `assert_matches_screenshot`, `capture_screenshot`, groups/sections |
+| `SnapDiff::Minitest::Assertions` | Minitest wiring (`snap_diff/integrations/minitest`) |
+| `SnapDiff::Error` | Base class for every error this gem raises |
+| `SnapDiff::ExpectationNotMet` | A screenshot did not match its baseline |
+| `SnapDiff::UnstableImage` | No stable capture within `stability_time_limit` / `wait` |
+| `SnapDiff::WindowSizeMismatchError` | Browser window is not the configured `window_size` |
+| `SnapDiff::Driver` | Mixin with the shared driver defaults (`require "snap_diff/driver"`) |
+| `SnapDiff::Drivers` | Driver factory and registry — `.for`, `.loaded`, `.available` |
+| `SnapDiff::Reporting` | Process-global reporter lifecycle (`require "snap_diff/reporting"`) |
+| `SnapDiff::Reporters::HTML` | The interactive HTML report (`require "snap_diff/reporters/html"`) |
+| `SnapDiff::Reporters::Default` | Builds the annotated diff images and the failure message |
+| `SnapDiff.session` | The per-test assertion registry (fiber-local) |
+| `SnapDiff.reset` | Ends a test: notifies reporters, clears the session |
+| `SnapDiff.pending_screenshots_message` | Skip message when a new screenshot has no baseline |
+| `SnapDiff::Capture::Viewport` | Per-capture viewport check seam (`require "snap_diff/capture/viewport"`) |
+| `SnapDiff.serve` | Point Capybara at a static site directory (`require "snap_diff/static"`) |
+
+## Compare two images without a browser
+
+Works on anything on disk — rendered PDFs, generated charts, CI artifacts:
+
+```ruby
+require "snap_diff"
+
+result = SnapDiff.compare("baseline.png", "current.png")
+result.quick_equal?   # => true when byte-identical / pixel-identical
+result.different?     # => true when the difference exceeds the configured thresholds
+result.difference     # => SnapDiff::ComparisonResult with region and metadata
+
+# Per-call option overrides, merged over SnapDiff.config.default_options
+SnapDiff.compare("baseline.png", "current.png", tolerance: 0.5)
+```
+
+Note the argument order: baseline first, current second ("compare baseline against current").
+
+## Custom reporters
+
+A reporter is any object answering `record(assertions)`, `finalize`, and `summary`. Register it
+once, for the rest of the process:
+
+```ruby
+require "snap_diff/reporting"
+
+class SlackReporter
+  def initialize = @failures = []
+
+  # Called once per finished test, with that test's assertions.
+  def record(assertions)
+    assertions.each do |assertion|
+      next unless assertion.compare&.difference&.different?
+      @failures << assertion.name
+    end
+  end
+
+  # Called once at end of suite.
+  def finalize
+    post_to_slack(@failures) unless @failures.empty?
+  end
+
+  # Printed to stdout after finalize. Return nil to print nothing.
+  def summary
+    @failures.empty? ? nil : "#{@failures.size} screenshot(s) changed"
+  end
+end
+
+SnapDiff::Reporting.register(SlackReporter.new)
+```
+
+`register` appends under a mutex, so concurrent registrations cannot lose one — prefer it over
+mutating `SnapDiff::Reporting.reporters` directly.
+
+Do implement `summary`. `finalize!` calls it unconditionally; a reporter without it is finalized
+and then warned about (`[snap_diff] Reporter … failed (NoMethodError: undefined method 'summary')`).
+
+A reporter that raises is warned about and skipped — the other reporters still run.
+
+The bundled HTML report is just a pre-registered reporter of this kind:
+
+```ruby
+require "snap_diff/reporters/html"   # registers SnapDiff::Reporters::HTML itself
+```
+
+### Frameworks other than Minitest/RSpec/Cucumber
+
+The three bundled integrations call the lifecycle for you. Wiring another framework means calling
+three things:
+
+```ruby
+require "snap_diff/dsl"        # SnapDiff::DSL, BrowserHelpers, the session accessors
+require "snap_diff/reporting"  # SnapDiff::Reporting
+
+# before each test
+SnapDiff::BrowserHelpers.resize_window_if_needed
+
+# after each test
+SnapDiff.session.verify                  # raises SnapDiff::ExpectationNotMet on a mismatch
+msg = SnapDiff.pending_screenshots_message  # non-nil => skip the test with this message
+SnapDiff.reset                           # always: notifies reporters, clears the session
+
+# after the suite
+SnapDiff::Reporting.finalize!
+```
+
+## Custom drivers
+
+A driver is a plain object that does the image work. Include `SnapDiff::Driver` for the shared
+defaults, then implement the operations the comparison engine calls:
+
+```ruby
+require "snap_diff/driver"
+
+class MyDriver
+  include SnapDiff::Driver
+
+  # Provided by the mixin, override only if your image objects differ:
+  #   width_for(image), height_for(image), dimension(image),
+  #   image_area_size(image), same_dimension?(comparison), supports?(feature)
+
+  # Implement (this is what both bundled drivers implement):
+  #   from_file(path), load_images(base_path, new_path), save_image_to(image, path)
+  #   same_pixels?(comparison), find_difference_region(comparison)
+  #   crop(region, image), resize_image_to(image, w, h)
+  #   add_black_box(image, region), draw_rectangles(images, region, ...)
+end
+```
+
+`supports?(feature)` is just `respond_to?(feature)` — the engine uses it to skip optional
+operations. The VIPS driver additionally implements `filter_image_with_median`, `merge`,
+`highlight_mask` and `difference_level`; ChunkyPNG does not, and `supports?` is how that is
+detected. Look at `lib/snap_diff/drivers/chunky_png_driver.rb` for the smaller of the two
+reference implementations.
+
+### Registration
+
+`SnapDiff::Drivers.loaded` is the registry: a mutable `name => driver class` hash. Register by
+writing into it, then select the driver by that name:
+
+```ruby
+SnapDiff::Drivers.loaded[:my_driver] = MyDriver
+
+SnapDiff.config.driver = :my_driver          # globally
+screenshot "index", driver: :my_driver       # or per screenshot
+```
+
+Resolution goes through `SnapDiff::Drivers.for`, which looks the symbol up in `loaded` and calls
+`.new` on the class — **your driver class must be instantiable with no arguments**. A pre-built
+instance skips the registry entirely:
+
+```ruby
+screenshot "index", driver: MyDriver.new     # any non-Symbol is used as-is
+```
+
+`SnapDiff::Drivers.available` is the *detected* list (`[:vips, :chunky_png]`, filled at load time
+by probing for the `ruby-vips` and `chunky_png` gems). It is a read-only view of detection, not
+the registry — registering a custom driver does not add it there, and `driver: :auto` picks
+`available.first`. Custom drivers must always be named explicitly.
+
+## Related
+
+- [Framework Setup](framework-setup.md) — the same three integrations under their legacy names
+- [Configuration Reference](configuration.md) — what every option does
+- [Image Processing Drivers](drivers.md) — VIPS vs ChunkyPNG, perceptual threshold
+- [Web UI & Custom Reporters](reporters.md) — the HTML report in detail
+- [Architecture](architecture.md) — how the pieces fit together internally
+- [UPGRADING.md](UPGRADING.md) — migrating an existing suite off the legacy names
+
+[← Back to README](../README.md)

data/docs/thread_safety.md

@@ -100,9 +100,10 @@ Do not:
 
 Runtime state is thread-local (above), but *loading* the gem is a separate
 concern. The require graph is deliberately acyclic: `lib/snap_diff/*` units
-depend only on the legacy-config leaf
-(`capybara/screenshot/diff/config_legacy`) and specific sibling units, the
-umbrella files depend on the units, and nothing requires back up the chain.
+depend only on the config-storage leaf (`snap_diff/config`, which the legacy
+view `capybara/screenshot/diff/config_legacy` requires) and specific sibling
+units, the umbrella files depend on the units, and nothing requires back up
+the chain.
 
 Eager mutual requires between entry points are forbidden, even guarded ones:
 per-thread "loading" flags cannot serialize Ruby's process-global per-file

data/lib/capybara/screenshot/diff/config_legacy.rb

@@ -1,80 +1,44 @@
 # frozen_string_literal: true
 
-# Legacy Capybara::Screenshot / Capybara::Screenshot::Diff mattr_accessor
-# config module, extracted out of capybara_screenshot_diff.rb so it is a
-# leaf: it can be required by both capybara_screenshot_diff.rb (the old
-# umbrella entry point) and snap_diff.rb (the canonical entry point)
-# without either of *those* requiring the other back.
+# Legacy Capybara::Screenshot / Capybara::Screenshot::Diff config surface.
 #
-# Why this file has to exist at all: several lib/snap_diff/* units
-# (Screenshoter, SnapManager, Utils) are referenced here at class-body
-# eval time (mattr_accessor default blocks, AVAILABLE_DRIVERS) rather
-# than at call time, so they must be real, already-loaded classes before
-# this module body runs. Since v2 step 6 they are pulled in and referenced
-# under their canonical SnapDiff names: the old-name aliases are lazy
-# const_missing shims that emit deprecation warnings, and the gem's own
-# code must stay warning-free. Everything else this module references
-# (Os, Comparison) is referenced only inside method bodies, resolved
-# lazily at call time by whichever entry point loaded them.
-require "snap_diff/screenshoter"
-require "snap_diff/snap_manager"
+# Since ADR-008 step 1 the storage lives in SnapDiff::Config -- the require
+# leaf of the config graph (see its own header) -- and since step 7b the
+# DERIVED values (active?, screenshot_area, default_options) live there
+# too. snap_diff/config.rb also generates the old accessor names as thin
+# delegators from SnapDiff::Config::MAPPING, so nothing but forwarders is
+# left here. The v1 surface (Capybara::Screenshot.window_size = ...,
+# Diff.configure { ... }, Diff.compare) keeps working unchanged: one
+# storage, two views.
+#
+# Load order: requiring snap_diff/config first also eagerly evaluates the
+# require-time defaults (ENV["CI"] for fail_if_new, Rails.root/pwd for
+# root) at this same load moment, exactly when the old mattr_accessor
+# default blocks used to run. snap_diff/config never requires back here,
+# so the graph stays acyclic.
+require "snap_diff/config"
+# AVAILABLE_DRIVERS below is evaluated at class-body eval time, so Utils
+# must be a real, already-loaded module before this module body runs.
 require "snap_diff/utils"
 
 module Capybara
   module Screenshot
-    mattr_accessor :add_driver_path
-    mattr_accessor :add_os_path
-    mattr_accessor(:blur_active_element) { true }
-    mattr_accessor :enabled
-    mattr_accessor(:hide_caret) { true }
-    mattr_accessor :disable_animations
-    mattr_reader(:root) { (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
-    mattr_accessor :stability_time_limit
-    mattr_accessor :window_size
-    mattr_accessor(:save_path) { "doc/screenshots" }
-    mattr_accessor(:use_lfs)
-    mattr_accessor(:screenshot_format) { "png" }
-    mattr_accessor(:capybara_screenshot_options) { {} }
-
     class << self
-      def root=(path)
-        @@root = Pathname(path).expand_path
-      end
-
       def active?
-        enabled || (enabled.nil? && Diff.enabled)
+        SnapDiff.config.active?
       end
 
       def screenshot_area
-        parts = [Screenshot.save_path]
-        parts << SnapDiff::Os.name if Screenshot.add_os_path
-        parts << Capybara.current_driver.to_s if Screenshot.add_driver_path
-        File.join(*parts)
+        SnapDiff.config.screenshot_area
       end
 
       def screenshot_area_abs
-        root / screenshot_area
+        SnapDiff.config.screenshot_area_abs
       end
     end
 
     # Module to track screenshot changes
     module Diff
-      mattr_accessor(:delayed) { true }
-      mattr_accessor :area_size_limit
-      mattr_accessor(:fail_if_new) { !ENV["CI"].nil? && !ENV["CI"].empty? }
-      mattr_accessor(:pending_if_new) { false }
-      mattr_accessor(:fail_on_difference) { true }
-      mattr_accessor :color_distance_limit
-      mattr_accessor(:enabled) { true }
-      mattr_accessor :shift_distance_limit
-      mattr_accessor :skip_area
-      mattr_accessor(:driver) { :auto }
-      mattr_accessor :tolerance
-      mattr_accessor :perceptual_threshold
-
-      mattr_accessor(:screenshoter) { SnapDiff::Screenshoter }
-      mattr_accessor(:manager) { SnapDiff::SnapManager }
-
       AVAILABLE_DRIVERS = SnapDiff::Utils.detect_available_drivers.freeze
 
       # Configure screenshot and diff settings in one block.
@@ -85,28 +49,18 @@ module Capybara
       #     diff.driver = :vips
       #     diff.tolerance = 0.0005
       #   end
+      # The bare `yield` (rather than an explicit &block) keeps this
+      # method's published arity byte-identical to what it always had.
       def self.configure
-        yield Screenshot, self
+        SnapDiff.start { |screenshot, diff| yield screenshot, diff }
       end
 
       def self.compare(baseline_path, current_path, **options)
-        SnapDiff::Comparison.new(current_path, baseline_path, default_options.merge(options))
+        SnapDiff.compare(baseline_path, current_path, **options)
       end
 
       def self.default_options
-        {
-          area_size_limit: area_size_limit,
-          color_distance_limit: color_distance_limit,
-          driver: driver,
-          screenshot_format: Screenshot.screenshot_format,
-          capybara_screenshot_options: Screenshot.capybara_screenshot_options,
-          perceptual_threshold: perceptual_threshold,
-          shift_distance_limit: shift_distance_limit,
-          skip_area: skip_area,
-          stability_time_limit: Screenshot.stability_time_limit,
-          tolerance: tolerance || ((driver == :vips) ? 0.001 : nil),
-          wait: Capybara.default_max_wait_time
-        }
+        SnapDiff.config.default_options
       end
     end
   end

data/lib/capybara/screenshot/diff/cucumber.rb

@@ -1,3 +1,7 @@
 # frozen_string_literal: true
 
-require "snap_diff/integrations/cucumber"
+# Legacy (v1-documented) entry point: like every other legacy entry, it must
+# load the legacy surface too -- requiring only the canonical integration
+# left CapybaraScreenshotDiff half-present (module defined, but .verify /
+# .reset / .reporters / ... gone) for v1 users of this path.
+require "capybara_screenshot_diff/cucumber"

data/lib/capybara/screenshot/diff/image_compare.rb

@@ -6,7 +6,22 @@
 # snap_diff/comparison itself pulls in the ComparisonResult and Drivers
 # units, and the shims keep the old ::Difference / ::Drivers names
 # resolvable, so this path still provides everything the pre-move
-# image_compare.rb did. The internal Comparison struct and LOADED_DRIVERS
-# keep their legacy names and are defined by snap_diff/comparison.rb itself.
+# image_compare.rb did. The images-holder struct lives at
+# SnapDiff::Comparison::Images and the driver cache at
+# SnapDiff::Drivers.loaded, with LOADED_DRIVERS kept as an eager same-object
+# alias by legacy_shims (ADR-008 step 5).
 require "snap_diff/comparison"
 require "snap_diff/legacy_shims"
+
+# Deliberately EAGER and silent (v2 step 6 exception): Comparison is a
+# documented user-facing struct, so adopters feature-detect it with
+# defined?/const_defined? -- neither of which triggers const_missing, so a
+# lazy shim reported it permanently absent. See snap_diff/legacy_shims.rb
+# for the full exception list.
+module Capybara
+  module Screenshot
+    module Diff
+      Comparison = SnapDiff::Comparison::Images
+    end
+  end
+end

data/lib/capybara/screenshot/diff/region.rb

@@ -1,107 +1,5 @@
 # frozen_string_literal: true
 
-class Region
-  attr_accessor :x, :y, :width, :height
-
-  def initialize(x, y, width, height)
-    @x, @y, @width, @height = x, y, width, height
-  end
-
-  def self.from_edge_coordinates(left, top, right, bottom)
-    return nil unless left && top && right && bottom
-    return nil if right < left || bottom < top
-
-    Region.new(left, top, right - left, bottom - top)
-  end
-
-  def to_edge_coordinates
-    [left, top, right, bottom]
-  end
-
-  def to_top_left_corner_coordinates
-    [x, y, width, height]
-  end
-
-  def top
-    y
-  end
-
-  def bottom
-    y + height
-  end
-
-  def left
-    x
-  end
-
-  def right
-    x + width
-  end
-
-  def size
-    return 0 if width < 0 || height < 0
-
-    result = width * height
-    result.zero? ? 1 : result
-  end
-
-  def to_a
-    [@x, @y, @width, @height]
-  end
-
-  def find_intersect_with(region)
-    return nil unless intersect?(region)
-
-    new_left = [x, region.x].max
-    new_top = [y, region.y].max
-
-    Region.new(new_left, new_top, [right, region.right].min - new_left, [bottom, region.bottom].min - new_top)
-  end
-
-  def intersect?(region)
-    left <= region.right && right >= region.left && top <= region.bottom && bottom >= region.top
-  end
-
-  def move_by(right_by, down_by)
-    Region.new(x + right_by, y + down_by, width, height)
-  end
-
-  def find_relative_intersect(region)
-    intersect = find_intersect_with(region)
-    return nil unless intersect
-
-    intersect.move_by(-x, -y)
-  end
-
-  def cover?(x, y)
-    x.between?(left, right) && y.between?(top, bottom)
-  end
-
-  def empty?
-    width.zero? || height.zero?
-  end
-
-  def blank?
-    empty?
-  end
-
-  def present?
-    !empty?
-  end
-
-  def inspect
-    "Region(x: #{x}, y: #{y}, width: #{width}, height: #{height})"
-  end
-
-  # need to add this method to make it work with assert_equal
-  def ==(other)
-    case other
-    when Region
-      x == other.x && y == other.y && width == other.width && height == other.height
-    when Array
-      to_a == other
-    else
-      false
-    end
-  end
-end
+# Forwarder (ADR-008 step 3): Region now lives at SnapDiff::Region;
+# snap_diff/region also defines the eager top-level `Region` alias.
+require "snap_diff/region"