capybara-screenshot-diff 1.10.3.1 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b731cca6ca98b0d7a9a6c1cb9db02de35b6898cecbb28aba568b8ae773ae0ff
-  data.tar.gz: d42ae0a773e80fdd6aaf9ae7c6e2b5106131998c650338d24c20f9bc48d90602
+  metadata.gz: 163b89646e7610ebde81e77fb9f6ed8e81bb2fb74dce234846efcfbe9479ed2c
+  data.tar.gz: 30e46f9caecc9c705ed19309a246c7ea9353c179635e5be38be5513e187c5fc7
 SHA512:
-  metadata.gz: 50bf2196f84506387c16aca897d98e9a5ea4ef9dc1b10216c2473566b001b362afffb1834a843cbdcf83bb35ca33713432dad86bf73cb0cb2a078e3cf2c89e68
-  data.tar.gz: 69abf40070444fb6a3f2d2d250cb529cdcae957d3c6eefb55ff7e740964f5eae12556ab76b43ccdd9c4b0e14d00366997a7fe4032597bcf41b1a95aeb34471c9
+  metadata.gz: 7c58c2d084f4d052591d2f4bd1b4b983a9a933f5e4f4be8d1ef7683c8bc060ae9bf3d3deaaf381bb344ae6c21de723ee61e1fd54e30b825b5741b1f903509da2
+  data.tar.gz: e879a7f5f9bc06ca083157fc7cc24a08a38b5419ddfd6ab2e0ef63f5e4379ca6f9e864bb21f869f7d9617b3514ca691d4f3af090a00ec3cc4adec3de5215e095

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v1.12.0] - 2026-04-12
+
+### Added
+- **HTML reporter** — interactive dashboard with 4 comparison modes (both/base/new/heatmap), per-image zoom, keyboard navigation, and search ([#170](https://github.com/snap-diff/snap_diff-capybara/pull/170))
+- **GitHub Actions integration** — inline HTML preview with base64 embedded images + reusable composite action ([#171](https://github.com/snap-diff/snap_diff-capybara/pull/171))
+- **`disable_animations` helper** — inject CSS to stop all animations/transitions during screenshots ([#174](https://github.com/snap-diff/snap_diff-capybara/pull/174))
+- **`snap_diff:clean` rake task** — remove diff artifacts while keeping baselines ([#177](https://github.com/snap-diff/snap_diff-capybara/pull/177))
+- `Diff.compare` for standalone image comparison without Capybara or browser
+- Perceptual color distance (dE00) for anti-aliasing tolerance in VipsDriver
+- `assert_no_screenshot_changes` DSL assertion
+- `Diff.configure` block helper for simplified configuration
+- Ruby 3.5 and 4.0 support
+
+### Changed
+- `blur_active_element` now defaults to `true` — prevents cursor blinking artifacts
+- `hide_caret` now defaults to `true` — stable screenshots without caret
+- `fail_if_new` now defaults to `true` in CI (when `ENV['CI']` is set)
+- Thread-safe reporter notification with mutex ([#175](https://github.com/snap-diff/snap_diff-capybara/pull/175))
+
+### Removed
+- **SVN support** — Git only
+- **ActiveSupport runtime dependency** — pure Ruby, lighter installations
+
+### Fixed
+- VCS path resolution rewritten for thread safety (Open3 + array-form system)
+- Reporter diff artifacts cleaned up properly on `Snap#delete!` ([#173](https://github.com/snap-diff/snap_diff-capybara/pull/173))
+- RSpec matcher now provides `failure_message` and description
+- Missing baseline error includes recording instructions
+- Ruby 4.0 DSLStub ordering compatibility
+- ChunkyPNG `filter_image_with_median` incorrect behavior
+- Tolerance calculation no longer skips large changes
+
+### Performance
+- ChunkyPNG shift-detection: eliminated array allocations (~30% faster for large images)
+- VIPS: cached computations at construction (~15% faster)
+- Memoized region area size, replaced closures with blocks
+
+### Documentation
+- README restructured from 970 to 149 lines with 7 dedicated `docs/` files ([#171](https://github.com/snap-diff/snap_diff-capybara/pull/171))
+- CI integration guide with artifact upload and PR commenting ([docs/ci-integration.md](docs/ci-integration.md))
+- Upgrade guide ([docs/UPGRADING.md](docs/UPGRADING.md))
+- Color comparison guide — tolerance vs perceptual_threshold vs color_distance_limit ([#176](https://github.com/snap-diff/snap_diff-capybara/pull/176))
+
+### Internal
+- Simplified internals: inlined CaptureStrategy, ComparisonLoader, ScreenshotNamerDSL, VipsUtil
+- Unified Screenshoter constructors, consolidated skip_area accessor
+- Upgraded CI dependencies (actions/checkout v5, upload-artifact v7)
+
+---
+
+## [v1.11.0] - Previous Release
+
+[Unreleased]: https://github.com/snap-diff/snap_diff-capybara/compare/v1.12.0...HEAD
+[v1.12.0]: https://github.com/snap-diff/snap_diff-capybara/releases/tag/v1.12.0
+[v1.11.0]: https://github.com/snap-diff/snap_diff-capybara/releases/tag/v1.11.0
+
+**Upgrade Guide:** See [docs/UPGRADING.md](docs/UPGRADING.md) for detailed migration instructions.

data/Rakefile

@@ -11,14 +11,42 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+Rake::TestTask.new("test:unit") do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/unit/**/*_test.rb"]
+end
+
 Rake::TestTask.new("test:integration") do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/integration/**/*_test.rb"]
 end
 
+desc "Run all tests with coverage"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task["test"].invoke
+end
+
+desc "Generate sample HTML report. Use bin/rake 'report:sample[embed]' for base64 images"
+task "report:sample", [:embed] do |_t, args|
+  embed_arg = args[:embed] ? "--embed" : ""
+  ruby "scripts/generate_sample_report.rb #{embed_arg}"
+end
+
+desc "Remove screenshot diff artifacts (keeps baselines)"
+task "snap_diff:clean" do
+  patterns = ["**/*.diff.png", "**/*.base.png", "**/*.base.diff.png", "**/*.heatmap.diff.png",
+    "**/*.diff.webp", "**/*.base.webp", "**/*.base.diff.webp", "**/*.heatmap.diff.webp",
+    "**/snap_diff_report.html"]
+  removed = patterns.flat_map { |p| Dir.glob("tmp/#{p}") + Dir.glob("doc/screenshots/#{p}") }.uniq
+  removed.each { |f| FileUtils.rm_f(f) }
+  puts "Removed #{removed.size} diff artifacts"
+end
+
 task "clobber" do
-  puts "Cleanup tmp/*.png"
+  puts "Cleanup tmp/"
   FileUtils.rm_rf(Dir["./tmp/*"])
 end
 

data/capybara-screenshot-diff.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |spec|
   spec.email = ["uwe@kubosch.no"]
   spec.summary = "Track your GUI changes with diff assertions"
   spec.description = "Save screen shots and track changes with graphical diff"
-  spec.homepage = "https://github.com/donv/capybara-screenshot-diff"
-  spec.required_ruby_version = ">= 3.1"
+  spec.homepage = "https://github.com/snap-diff/snap_diff-capybara"
+  spec.required_ruby_version = ">= 3.2"
   spec.license = "MIT"
   spec.metadata["allowed_push_host"] = "https://rubygems.org/"
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "actionpack", ">= 7.0", "< 9"
+  spec.add_development_dependency "actionpack", ">= 7.1", "< 9"
+  spec.add_development_dependency "activesupport", ">= 7.1", "< 9"
   spec.add_runtime_dependency "capybara", ">= 2", "< 4"
 end

data/docs/RELEASE_PREP.md

@@ -0,0 +1,58 @@
+# Release Preparation — v1.12.0
+
+## Summary
+
+71 commits since v1.11.0 with new features, performance improvements, and default behavior changes.
+
+## Release Checklist
+
+### Pre-Release
+
+- [x] Update version to `1.12.0`
+- [x] Run tests: `bundle exec rake test` (218 runs, 0 failures)
+- [x] Add CHANGELOG.md
+- [x] Add docs/UPGRADING.md
+
+### Release (One Click)
+
+1. Push to GitHub
+2. Go to [Actions → Release](https://github.com/snap-diff/snap_diff-capybara/actions/workflows/release.yml)
+3. Click **Run workflow**, enter `1.12.0`
+4. Workflow will: test → tag → publish to RubyGems → create GitHub Release
+
+### Post-Release
+
+- [ ] Verify on [RubyGems](https://rubygems.org/gems/capybara-screenshot-diff)
+- [ ] Verify GitHub Release created
+
+## What Changed
+
+### New Features
+- HTML reporter with premium UI, 4 comparison modes, zoom, keyboard navigation
+- GitHub Actions artifact integration with inline preview + reusable composite action
+- `disable_animations` helper for stable screenshots
+- `snap_diff:clean` rake task for diff artifact cleanup
+- `Diff.compare` for standalone image comparison
+- Perceptual color distance (dE00) for anti-aliasing
+- `assert_no_screenshot_changes` DSL method
+- `Diff.configure` block helper
+- Ruby 3.5 & 4.0 support
+
+### Behavior Changes
+- `blur_active_element` defaults to `true`
+- `hide_caret` defaults to `true`
+- `fail_if_new` defaults to `true` in CI
+- Thread-safe reporter notification with mutex
+- SVN support removed
+- ActiveSupport no longer required
+
+### Performance
+- Faster ChunkyPNG shift-detection (eliminated allocations)
+- Cached computations in VIPS driver
+- Memoized region area size
+
+### Documentation
+- README restructured (970→149 lines) with 7 dedicated docs/ files
+- CI integration guide, upgrade guide, color comparison guide
+
+See [CHANGELOG.md](../CHANGELOG.md) for full details.

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 🎉