capybara-screenshot-diff 1.10.3.1 → 1.13.0

data/docs/UPGRADING.md

@@ -0,0 +1,390 @@
+# Upgrading to v1.12.0
+
+## Overview
+
+Version 1.12.0 is a **minor release** with new features, performance improvements, and default behavior changes. This guide will help you upgrade smoothly.
+
+**Estimated upgrade time:** 5-15 minutes depending on your setup
+
+---
+
+## Quick Upgrade Path (Most Users)
+
+For **most users**, upgrading is as simple as:
+
+```ruby
+# In your Gemfile
+gem 'capybara-screenshot-diff', '~> 1.12.0'
+```
+
+```bash
+bundle update capybara-screenshot-diff
+bundle exec rake test  # Verify tests still pass
+```
+
+**That's it!** The zero-config setup still works out of the box. Your existing screenshot comparisons will continue to work with v1.12.0.
+
+---
+
+## Breaking Changes & Migration Steps
+
+### 1. Default Behavior Changes (Most Important)
+
+Three settings now have different defaults. This is the most likely source of unexpected test failures.
+
+#### `blur_active_element` — Now defaults to `true`
+
+**Before (v1.11.x):** Cursor blinking could delay screenshots  
+**After (v1.12.0):** Cursor is automatically hidden
+
+**Action required:** Only if you want the old behavior
+
+```ruby
+# To restore v1.x behavior:
+Capybara::Screenshot.blur_active_element = false
+```
+
+#### `hide_caret` — Now defaults to `true`
+
+**Before (v1.11.x):** Input caret visible in screenshots  
+**After (v1.12.0):** Caret is transparent for stable screenshots
+
+**Action required:** Only if you want the old behavior
+
+```ruby
+# To restore v1.x behavior:
+Capybara::Screenshot.hide_caret = false
+```
+
+#### `fail_if_new` — Now defaults to `true` in CI
+
+**Before (v1.11.x):** New screenshots allowed in CI  
+**After (v1.12.0):** New screenshots fail tests in CI (when `ENV['CI']` is set)
+
+**Action required:** Only if you want to allow new screenshots in CI
+
+```ruby
+# To allow new screenshots in CI:
+Capybara::Screenshot::Diff.fail_if_new = false
+```
+
+**Why this changed:** This prevents accidental baseline additions in CI pipelines. Most teams want this behavior.
+
+---
+
+### 2. SVN Support Removed
+
+**Before (v1.11.x):** Could use SVN for version control  
+**After (v1.12.0):** Git only
+
+**Action required:** If using SVN, migrate to Git
+
+```bash
+# Check if you're using SVN for screenshots
+git grep svn test/  # Look for svn commands in your tests
+```
+
+If you find SVN usage:
+1. Export your SVN repository to Git
+2. Update your CI/CD to use Git
+3. Re-commit all screenshot baselines with Git
+
+**Why this changed:** SVN support was rarely used and added maintenance burden.
+
+---
+
+### 3. ActiveSupport No Longer Required
+
+**Before (v1.11.x):** ActiveSupport was a runtime dependency  
+**After (v1.12.0):** Pure Ruby, no ActiveSupport required
+
+**Action required:** None (this is a positive change!)
+
+If your project only had ActiveSupport because of this gem, you can now remove it:
+
+```ruby
+# In your Gemfile — can likely be removed if only used for this gem
+# gem 'activesupport'  # ← Remove if not used elsewhere
+```
+
+**Why this changed:** Lighter installations, faster boot times.
+
+---
+
+### 4. Internal API Changes
+
+**Before (v1.11.x):** Could use internal classes like `CaptureStrategy`, `ComparisonLoader`  
+**After (v1.12.0):** These have been inlined/refactored
+
+**Action required:** Only if using internal APIs
+
+Check your codebase:
+
+```bash
+# Search for internal API usage
+grep -r "CaptureStrategy" test/ lib/
+grep -r "ComparisonLoader" test/ lib/
+grep -r "ScreenshotCoordinator" test/ lib/
+grep -r "ImagePreprocessor" test/ lib/
+```
+
+If you find usage, these were never part of the public API and should be replaced with the documented public API.
+
+**Why this changed:** Simplified architecture, better performance, easier maintenance.
+
+---
+
+## New Features to Try
+
+### HTML Reporter (Recommended)
+
+Get an interactive dashboard showing all screenshot differences:
+
+```ruby
+# Add to test_helper.rb or spec_helper.rb
+require 'capybara_screenshot_diff/reporters/html'
+```
+
+After running tests:
+
+```bash
+open doc/screenshots/snap_diff_report.html
+```
+
+**Features:**
+- Side-by-side comparison with diff toggle
+- Thumbnail sidebar for navigation
+- Search functionality
+- Summary statistics
+
+---
+
+### Standalone Image Comparison
+
+Compare any two images without Capybara or a browser:
+
+```ruby
+result = Capybara::Screenshot::Diff.compare("baseline.png", "current.png")
+result.quick_equal?  # => true if byte-identical
+result.different?    # => true if visually different
+```
+
+**Use cases:**
+- PDF regression testing
+- Generated image validation
+- CI artifact verification
+
+---
+
+### Perceptual Color Distance (Anti-aliasing Fix)
+
+Eliminate false positives from font rendering differences:
+
+```ruby
+# Global configuration
+Capybara::Screenshot::Diff.perceptual_threshold = 2.0
+
+# Or per-screenshot
+screenshot 'dashboard', perceptual_threshold: 2.0
+```
+
+**dE00 Scale Reference:**
+- `< 1.0` — Not perceptible by human eyes
+- `1-2` — Perceptible through close observation (anti-aliasing, font hinting)
+- `2-10` — Perceptible at a glance (color shifts, layout changes)
+- `> 10` — Clearly different colors
+
+**Why use this:** If you see false positives from font rendering differences across CI environments.
+
+---
+
+### `assert_no_screenshot_changes`
+
+Assert that an action produces no visual change:
+
+```ruby
+test "clicking cancel doesn't change page" do
+  visit '/edit'
+  screenshot 'before_cancel'
+  
+  click_button 'Cancel'
+  
+  assert_no_screenshot_changes 'after_cancel'
+end
+```
+
+---
+
+### Simplified Configuration
+
+Use the new `Diff.configure` block:
+
+```ruby
+# In test_helper.rb — one line, that's it
+Capybara::Screenshot::Diff.configure do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+  screenshot.stability_time_limit = 1
+  diff.driver = :vips
+  diff.tolerance = 0.0005
+end
+```
+
+---
+
+## Performance Improvements
+
+Enjoy faster screenshot comparisons:
+
+- **ChunkyPNG:** Eliminated array allocations in shift-detection (~30% faster for large images)
+- **VIPS:** Cached computations at construction (~15% faster)
+- **General:** Memoized region area size, replaced closures with blocks
+
+**No action required** — these are automatic improvements.
+
+---
+
+## Ruby & Rails Compatibility
+
+### Supported Versions
+
+- **Ruby:** 3.2, 3.3, 3.4, 3.5 (new!), 4.0 (new!)
+- **Rails:** 7.1, 7.2, 8.0
+
+### Upgrade Notes
+
+**Ruby 4.0:** Fully compatible! If you see DSLStub ordering issues, they're fixed in v1.12.0.
+
+**Rails 8.0:** Works out of the box with updated dependencies.
+
+---
+
+## Testing Your Upgrade
+
+### Step 1: Update Gemfile
+
+```ruby
+gem 'capybara-screenshot-diff', '~> 1.12.0'
+```
+
+### Step 2: Bundle Update
+
+```bash
+bundle update capybara-screenshot-diff
+```
+
+### Step 3: Run Tests
+
+```bash
+bundle exec rake test
+```
+
+### Step 4: Check for New Screenshot Failures
+
+If tests fail with new screenshot errors in CI:
+
+1. **Option A:** Commit the new baselines (recommended if changes are intentional)
+2. **Option B:** Set `fail_if_new = false` temporarily (not recommended long-term)
+
+### Step 5: Enable HTML Reporter (Optional)
+
+```ruby
+require 'capybara_screenshot_diff/reporters/html'
+```
+
+Run tests and open `doc/screenshots/snap_diff_report.html` to review differences.
+
+---
+
+## Troubleshooting
+
+### "Tests fail with new screenshots in CI"
+
+**Cause:** `fail_if_new` now defaults to `true` in CI
+
+**Solution:**
+
+```bash
+# Commit the new baselines
+git add doc/screenshots/
+git commit -m "Add screenshot baselines for v1.12.0 upgrade"
+```
+
+Or temporarily allow them:
+
+```ruby
+Capybara::Screenshot::Diff.fail_if_new = false
+```
+
+### "Screenshots look different after upgrade"
+
+**Cause:** `blur_active_element` and `hide_caret` now default to `true`
+
+**Solution:** Restore v1.x behavior temporarily:
+
+```ruby
+Capybara::Screenshot.blur_active_element = false
+Capybara::Screenshot.hide_caret = false
+```
+
+Then re-record baselines with the new defaults (recommended):
+
+```bash
+# Delete old baselines
+rm doc/screenshots/*.png
+
+# Run tests to generate new baselines
+bundle exec rake test
+
+# Commit new baselines
+git add doc/screenshots/
+git commit -m "Re-record baselines with v1.12.0 defaults"
+```
+
+### "NoMethodError on internal class"
+
+**Cause:** Using internal APIs that were refactored
+
+**Solution:** Use the public API instead. Check the documentation for the correct interface.
+
+---
+
+## Rollback Plan
+
+If you need to rollback:
+
+```ruby
+# Pin to previous version
+gem 'capybara-screenshot-diff', '~> 1.12.0'
+```
+
+```bash
+bundle update capybara-screenshot-diff
+```
+
+All screenshot baselines are compatible — no data loss.
+
+---
+
+## Need Help?
+
+- **Documentation:** [README.md](README.md)
+- **Changelog:** [CHANGELOG.md](CHANGELOG.md)
+- **Issues:** [GitHub Issues](https://github.com/snap-diff/snap_diff-capybara/issues)
+- **DeepWiki:** [Code Documentation](https://deepwiki.com/snap-diff/snap_diff-capybara)
+
+---
+
+## Summary Checklist
+
+- [ ] Update gem version to `~> 1.12.0`
+- [ ] Run `bundle update capybara-screenshot-diff`
+- [ ] Run test suite
+- [ ] Check for new screenshot failures in CI
+- [ ] Decide on `fail_if_new` behavior
+- [ ] Decide on `blur_active_element` and `hide_caret` defaults
+- [ ] Enable HTML reporter (optional)
+- [ ] Re-record baselines if needed
+- [ ] Commit changes
+- [ ] Review upgrade issues in [GitHub Issues](https://github.com/snap-diff/snap_diff-capybara/issues)
+
+**Congratulations!** You're now running v1.12.0 🎉

data/docs/architecture.md

@@ -0,0 +1,270 @@
+# Architecture
+
+This document describes the internal architecture of `capybara-screenshot-diff` — how screenshots are captured, compared, and reported, and how the components fit together.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Test Framework                         │
+│  (Minitest / RSpec / Cucumber / Custom)                  │
+└──────────────┬──────────────────────────────┬────────────┘
+               │                              │
+               ▼                              ▼
+┌──────────────────────────┐    ┌──────────────────────────┐
+│  CapybaraScreenshotDiff   │    │  CapybaraScreenshotDiff   │
+│  ::DSL (screenshot, etc)  │    │  ::AssertionRegistry       │
+└──────────────┬───────────┘    └──────────────┬───────────┘
+               │                               │
+               ▼                               ▼
+┌──────────────────────────┐    ┌──────────────────────────┐
+│  ScreenshotMatcher        │    │  ScreenshotAssertion     │
+│  (capture + compare)      │    │  (validate results)      │
+└──────┬───────────┬────────┘    └──────────────┬───────────┘
+       │           │                            │
+       ▼           ▼                            ▼
+┌──────────┐ ┌──────────┐           ┌──────────────────────┐
+│Screenshot│ │Stable    │           │   Reporters           │
+│er        │ │Screenshot│           │  (Default / HTML /    │
+│          │ │er        │           │   Custom)             │
+└─────┬────┘ └──────────┘           └──────────────────────┘
+      │
+      ▼
+┌──────────────────────────────────────────┐
+│  ImageCompare (layered comparison)       │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐  │
+│  │1. Byte   │ │2. Pixel  │ │3. Region │  │
+│  │  compare │ │  compare │ │  analyze │  │
+│  └──────────┘ └──────────┘ └──────────┘  │
+└─────────────────────┬────────────────────┘
+                      │
+                      ▼
+┌──────────────────────────────────────────┐
+│  Drivers (image processing backends)     │
+│  ┌──────────┐ ┌──────────────────────┐   │
+│  │ Vips     │ │ ChunkyPNG            │   │
+│  │ (fast)   │ │ (no native deps)     │   │
+│  └──────────┘ └──────────────────────┘   │
+└──────────────────────────────────────────┘
+```
+
+## Component Breakdown
+
+### 1. DSL Layer (`lib/capybara_screenshot_diff/dsl.rb`)
+
+The entry point for test code. `assert_matches_screenshot` is the primary assertion method (captures and compares). `screenshot` is a convenience wrapper with a `compare:` option — `compare: true` (default) delegates to `assert_matches_screenshot`, while `compare: false` delegates to the new `capture_screenshot` method. `capture_screenshot` takes screenshots without assertions. `assert_no_screenshot_changes` keeps its behavior but now delegates to `assert_matches_screenshot` (that redirect is part of the #191 fix). Users can safely override `screenshot` in their test classes without affecting internal gem flow.
+
+**Flow:**
+1. Checks if screenshots are `active?` (returns `false` if disabled)
+2. Builds a full screenshot name via `ScreenshotNamer` (handles sections, groups, counters)
+3. Delegates to `ScreenshotMatcher` to capture and prepare comparison
+4. Creates a `ScreenshotAssertion` — either adds it to the thread-local registry (delayed validation) or validates immediately
+
+### 2. ScreenshotMatcher (`lib/capybara/screenshot/diff/screenshot_matcher.rb`)
+
+The orchestrator that coordinates capture and comparison:
+
+1. **Window size check** — verifies browser window is the expected size
+2. **Area calculation** — resolves crop regions and skip areas (supports CSS selectors and coordinates)
+3. **Base screenshot checkout** — retrieves the committed baseline from git via `Vcs.checkout_vcs`
+4. **Capture** — delegates to `Screenshoter` or `StableScreenshoter` depending on `stability_time_limit`
+5. **Comparison** — creates an `ImageCompare` object (lazy — actual comparison happens on first access)
+6. **Assertion** — returns a `ScreenshotAssertion` with the comparison attached
+
+**Key design decision:** The "new" screenshot is taken *first*, then compared against the baseline. This means if no baseline exists (first run), we skip comparison entirely and the test passes.
+
+### 3. Screenshoter & StableScreenshoter (`lib/capybara/screenshot/diff/screenshoter.rb`, `lib/capybara/screenshot/diff/stable_screenshoter.rb`)
+
+**Screenshoter:** The basic capture flow:
+1. Prepares the page (blur active element, hide caret, disable animations, wait for images)
+2. Takes a browser screenshot via `Capybara.current_session.save_screenshot`
+3. Processes the screenshot (resize for retina, apply crop)
+
+**StableScreenshoter:** Wraps `Screenshoter` with stability detection:
+1. Takes sequential screenshots at `stability_time_limit` intervals
+2. Compares consecutive attempts for byte-level equality
+3. Returns once two consecutive screenshots are identical
+4. Fails with `UnstableImage` if timeout (`wait`) is reached, generating annotated attempt images for debugging
+
+### 4. ImageCompare (`lib/capybara/screenshot/diff/image_compare.rb`)
+
+The comparison engine uses a **layered optimization strategy** to balance speed and accuracy:
+
+| Layer | Method | What it checks | Speed | When it returns |
+|-------|--------|----------------|-------|-----------------|
+| 1 | `quick_equal?` | File size + byte-level comparison | Fastest | Equal → `true`, Different → Layer 2 |
+| 2 | `quick_equal?` continues | Dimension check + pixel comparison | Fast | Different dimensions → `false`, Same pixels → `true` |
+| 3 | `processed` / `different?` | Full region analysis with tolerance | Slower | Detailed diff with region, heatmap, annotations |
+
+**Key details:**
+- `quick_equal?` is designed for fast rejection — it early-returns as soon as a difference is found
+- `different?` triggers the full comparison if not already processed
+- `processed` guarantees the comparison is complete and returns the result with all metadata
+- The `DifferenceFinder` handles the actual pixel analysis, delegating to the driver
+
+### 5. Drivers (`lib/capybara/screenshot/diff/drivers/`)
+
+Drivers abstract image processing operations. Each driver implements:
+
+| Operation | VipsDriver | ChunkyPNGDriver |
+|-----------|-----------|-----------------|
+| `load_images` | Vips::Image from file | ChunkyPNG::Image from blob |
+| `same_dimension?` | Compare width × height | Same |
+| `same_pixels?` | Pixel-level equality | Same |
+| `find_difference_region` | Difference mask → Region | Row-by-row scan → Region |
+| `crop` | Vips image crop | ChunkyPNG crop |
+| `save_image_to` | Vips write_to_file | PNG save |
+| `filter_image_with_median` | Vips median filter | Not supported |
+| `add_black_box` | Draw filled rect | No-op (handled differently) |
+| `merge` | Composite images | Not applicable |
+| `highlight_mask` | Conditional color overlay | Not applicable |
+
+**Auto-detection:** `Utils.detect_available_drivers` tries to load `:vips` first (via `ruby-vips` gem), then `:chunky_png`. The `:auto` driver mode picks the first available.
+
+### 6. Difference Region Detection
+
+**VipsDriver** uses a **difference mask** approach:
+1. Compute absolute difference between images: `(new - base).abs`
+2. Optional: apply perceptual color distance (CIE dE00) instead of raw RGB
+3. Project the mask to find the bounding region of non-zero pixels
+4. Return the tight bounding box of all differences
+
+**ChunkyPNGDriver** uses **row-by-row scanning**:
+1. Scan top-to-bottom, left-to-right for first differing pixel
+2. Expand left/right boundaries within each differing row
+3. Extend bottom boundary to cover all differing rows
+4. Supports shift detection (expensive neighbor pixel search)
+
+### 7. SnapManager & Snap (`lib/capybara_screenshot_diff/snap_manager.rb`, `lib/capybara_screenshot_diff/snap.rb`)
+
+**Snap** represents a single screenshot file with path management:
+- `path` — the actual screenshot file
+- `base_path` — the `.base.ext` VCS checkout
+- `attempt_path` — stability attempt files (`.attempt_00.png`, etc.)
+- Provides cleanup of diff artifacts (`.diff.png`, `.heatmap.diff.png`)
+
+**SnapManager** is the factory and path manager:
+- Creates `Snap` instances
+- Handles VCS checkout of baselines
+- Manages file operations (copy, move, cleanup)
+
+### 8. VCS (`lib/capybara/screenshot/diff/vcs.rb`)
+
+Handles baseline retrieval from git. Uses `git show HEAD:<path>` to extract the committed version. Supports Git LFS via `git lfs smudge`. Returns `false` if the file doesn't exist in VCS (first-run scenario).
+
+### 9. Reporters (`lib/capybara/screenshot/diff/reporters/`)
+
+**Default reporter:** Generates annotated diff images:
+- `image.diff.png` — new screenshot with diff region outlined in red
+- `image.base.diff.png` — baseline with diff region outlined in red
+- `image.heatmap.diff.png` — heatmap overlay of pixel differences
+
+**HTML reporter:** Generates an interactive dashboard (`snap_diff_report.html`) with:
+- Sidebar with thumbnails and search
+- 4 view modes (both/base/new/heatmap)
+- Annotated toggle for showing diff outlines
+- Per-image zoom with synchronized panning across side-by-side views
+- Keyboard navigation and shortcuts
+- Responsive layout for mobile
+
+**Custom reporters:** Implement `record(assertions)` and `finalize` methods, then add to `CapybaraScreenshotDiff.reporters`.
+
+### 10. Assertion Lifecycle
+
+```
+Test begins
+    │
+    ├─ setup: resize_window_if_needed
+    │
+    ├─ test body:
+    │    └─ screenshot("name")
+    │         ├─ ScreenshotMatcher builds assertion
+    │         ├─ delayed=true → add to Thread-local registry
+    │         └─ delayed=false → validate immediately
+    │
+    ├─ teardown:
+    │    └─ CapybaraScreenshotDiff.verify
+    │         ├─ iterates thread-local assertions
+    │         ├─ calls validate on each
+    │         ├─ raises ExpectationNotMet on first failure
+    │         └─ notifies reporters via mutex-protected snapshot
+    │
+    └─ at_exit:
+         └─ CapybaraScreenshotDiff.finalize_reporters!
+              ├─ Generates HTML report (if reporter registered)
+              └─ Prints summary
+```
+
+### 11. Thread Safety
+
+| Concern | Mechanism |
+|---------|-----------|
+| Assertion registry | Thread-local storage (`Thread.current[:capybara_screenshot_diff_registry]`) |
+| Reporter notification | Mutex-protected snapshot of reporter list before iteration |
+| HTML reporter internals | Mutex protecting `@failures`, `@total`, `@finalized` |
+| Screenshot naming | Per-thread `ScreenshotNamer` instance |
+| Global configuration | `mattr_accessor` — must be set before tests run, not mutated during parallel execution |
+| File system | Atomic `FileUtils.mv`, unique paths per screenshot name + counter, thread-safe `mkpath` |
+
+### 12. Configuration System
+
+Configuration uses Ruby's `mattr_accessor` (from ActiveSupport, or pure Ruby fallback) and is organized into two namespaces:
+
+**`Capybara::Screenshot`** — capture settings:
+- `window_size`, `stability_time_limit`, `blur_active_element`, `hide_caret`, `disable_animations`
+- `save_path`, `root`, `screenshot_format`, `add_driver_path`, `add_os_path`
+- `enabled`, `capybara_screenshot_options`
+
+**`Capybara::Screenshot::Diff`** — comparison settings:
+- `driver`, `tolerance`, `color_distance_limit`, `perceptual_threshold`, `shift_distance_limit`
+- `area_size_limit`, `skip_area`, `fail_if_new`, `fail_on_difference`, `delayed`
+
+The `Diff.configure` block helper provides a convenient way to set both namespaces at once.
+
+## File Layout
+
+```
+lib/
+  capybara_screenshot_diff.rb                  # Core module, mattr_accessor definitions
+  capybara/screenshot/diff.rb                  # Convenience require (loads minitest)
+  capybara_screenshot_diff/
+    dsl.rb                                     # screenshot(), screenshot_group(), etc.
+    minitest.rb                                # Minitest assertions integration
+    rspec.rb                                   # RSpec matcher integration
+    cucumber.rb                                # Cucumber World integration
+    static.rb                                  # Non-Rails static site serving
+    snap_manager.rb                            # Screenshot file management
+    snap.rb                                    # Single screenshot file abstraction
+    screenshot_namer.rb                        # Name/path generation with sections/groups
+    screenshot_assertion.rb                    # Assertion + registry objects
+    attempts_reporter.rb                       # Debug reporting for unstable captures
+    error_with_filtered_backtrace.rb           # Error with filtered stack
+    backtrace_filter.rb                        # Library/gem frame filtering
+    reporters/
+      html.rb                                  # Interactive HTML report reporter
+      templates/report.html.erb                # HTML report template
+  capybara/screenshot/diff/
+    version.rb                                 # VERSION constant
+    utils.rb                                   # Driver detection
+    drivers.rb                                 # Driver factory
+    drivers/
+      base_driver.rb                           # Abstract base driver
+      vips_driver.rb                           # VIPS image processing
+      chunky_png_driver.rb                     # ChunkyPNG image processing
+    screenshoter.rb                            # Basic browser screenshot capture
+    stable_screenshoter.rb                     # Stability detection wrapper
+    screenshot_matcher.rb                      # Orchestrator for capture + compare
+    image_compare.rb                           # Layered comparison engine
+    comparison.rb                              # Comparison value object
+    difference.rb                              # Difference result value object
+    difference_finder.rb                       # Core diff analysis logic
+    image_preprocessor.rb                      # Pre-processing (skip areas, median filter)
+    area_calculator.rb                         # Crop/skip area coordinate resolution
+    region.rb                                  # Bounding box region value object
+    browser_helpers.rb                         # DOM manipulation helpers
+    vcs.rb                                     # Git baseline checkout
+    os.rb                                      # OS detection
+    cucumber.rb                                # Deprecated Cucumber entry point
+    reporters/
+      default.rb                               # Default annotated-image reporter
+```