capybara-screenshot-diff 1.10.3.1 → 1.13.0

data/docs/drivers.md

@@ -0,0 +1,102 @@
+# Image Processing Drivers
+
+## Perceptual color comparison (VIPS only)
+
+By default, color differences are measured using raw RGB channel distance. This can produce
+false positives from anti-aliasing and sub-pixel font rendering — the same page rendered on
+different OS versions or browsers will have slightly different pixel values at text edges.
+
+The `perceptual_threshold` option uses the CIE dE00 formula instead, which measures color
+difference the way human eyes perceive it. Anti-aliasing artifacts typically score below 2.0
+on the dE00 scale and are automatically ignored.
+
+```ruby
+# Per-screenshot: ignore anti-aliasing, catch real visual changes
+screenshot 'dashboard', perceptual_threshold: 2.0
+
+# Global: apply to all screenshots
+Capybara::Screenshot::Diff.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
+```
+
+Use `perceptual_threshold` when you see false positives from font rendering differences across
+CI environments, or when `color_distance_limit` with raw RGB requires frequent tuning.
+
+**⚠️ Important:** `perceptual_threshold` and `color_distance_limit` are **mutually exclusive**.
+If you set both, `perceptual_threshold` takes priority and `color_distance_limit` is silently ignored.
+
+These options use different scales and algorithms:
+- `perceptual_threshold` → CIE dE00 perceptual distance (0-100+)
+- `color_distance_limit` → Euclidean RGBA distance (0-510)
+
+**Choose one based on your driver setup:**
+- VIPS with `ruby-vips` gem → prefer `perceptual_threshold`
+- ChunkyPNG (no native dependencies) → use `color_distance_limit`
+
+## Available Image Processing Drivers
+
+There are several image processing supported by this gem.
+There are several options to setup active driver: `:auto`, `:chunky_png` and `:vips`.
+
+* `:auto` - will try to load `:vips` if there is gem `ruby-vips`, in other cases will load `:chunky_png`
+* `:chunky_png` and `:vips` will load correspondent driver
+
+## Enable VIPS image processing
+
+[Vips](https://www.rubydoc.info/gems/ruby-vips/Vips/Image) driver provides a faster comparison,
+and could be enabled by adding `ruby-vips` to `Gemfile`.
+
+If need to setup explicitly Vips driver, there are several ways to do this:
+
+* Globally: `Capybara::Screenshot::Diff.driver = :vips`
+* Per screenshot option: `screenshot 'index', driver: :vips`
+
+With enabled VIPS there are new alternatives to process differences, which are easier to find and support.
+For example, `shift_distance_limit` is a very heavy operation. Instead, use `median_filter_window_size`.
+
+## Tolerance level (vips only)
+
+You can set a "tolerance" anywhere from 0% to 100%. This is the amount of change that's allowable.
+If the screenshot has changed by more than that amount, it'll flag it as a failure.
+
+This is alternative to "Allowed difference size", only the difference that area calculates including valid pixels.
+But "tolerance" compares only different pixels.
+
+You can use the `tolerance` option to the `screenshot` method to set level:
+
+```ruby
+test 'unstable area' do
+  visit '/'
+  # tolerance: 0.01 allows 1% of pixels to differ (use for noisy pages)
+  screenshot 'index', tolerance: 0.01
+end
+```
+
+You can also set this globally:
+
+```ruby
+# Default for VIPS is 0.001 (0.1% pixel difference allowed)
+Capybara::Screenshot::Diff.tolerance = 0.001
+```
+
+## Median filter size (vips only)
+
+This is an alternative to "Allowed shift distance", but much faster.
+You can find more about this strategy on [Median Filter](https://en.wikipedia.org/wiki/Median_filter).
+Think about this like smoothing of the image, before comparison.
+
+You can use the `median_filter_window_size` option to the `screenshot` method to set level:
+
+```ruby
+test 'unstable area' do
+  visit '/'
+  screenshot 'index', median_filter_window_size: 2
+end
+```
+
+[← Back to README](../README.md)

data/docs/framework-setup.md

@@ -0,0 +1,87 @@
+# Framework Setup
+
+## Including DSL
+
+To use the screenshot capturing and change detection features in your tests, include the `CapybaraScreenshotDiff::DSL` in your test classes. It provides the `screenshot` method to capture and compare screenshots.
+
+There are different modules for different testing frameworks integrations.
+
+## Minitest
+
+For Minitest, need to require `capybara_screenshot_diff/minitest`.
+In your test class, include the `CapybaraScreenshotDiff::Minitest::Assertions` module:
+
+```ruby
+require 'capybara_screenshot_diff/minitest'
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  # Make the Capybara & Capybara Screenshot Diff DSLs available in tests
+  include CapybaraScreenshotDiff::DSL
+  # Make `assert_*` methods behave like Minitest assertions
+  include CapybaraScreenshotDiff::Minitest::Assertions
+
+  def test_my_feature
+    visit '/'
+    assert_matches_screenshot 'index'
+  end
+end
+```
+
+## RSpec
+
+To use the screenshot capturing and change detection features in your tests,
+include the `CapybaraScreenshotDiff::DSL` in your test classes.
+It adds `match_screenshot` matcher to RSpec.
+
+> **Important**:
+> The `CapybaraScreenshotDiff::DSL` is automatically included in all feature and system tests by default.
+
+
+```ruby
+require 'capybara_screenshot_diff/rspec'
+
+describe 'Permissions admin', type: :feature do
+  it 'works with permissions' do
+    visit('/')
+    expect(page).to match_screenshot('home_page')
+  end
+end
+
+
+describe 'Permissions admin', type: :non_feature do
+  include CapybaraScreenshotDiff::DSL
+
+  it 'works with permissions' do
+    visit('/')
+    expect(page).to match_screenshot('home_page')
+  end
+end
+```
+
+## Cucumber
+
+Load Cucumber support by adding the following line (typically to your `features/support/env.rb` file):
+
+```ruby
+require 'capybara_screenshot_diff/cucumber'
+```
+
+And in the steps you can use:
+
+```ruby
+Then('I should not see any visual difference') do
+  screenshot 'homepage'
+end
+```
+
+## Custom Test Frameworks
+
+Minitest, RSpec, and Cucumber are supported out of the box. For other frameworks, call `finalize_reporters!` in your framework's "after suite" hook:
+
+```ruby
+CapybaraScreenshotDiff.finalize_reporters!
+```
+
+This generates the HTML report and prints the summary.
+
+[← Back to README](../README.md)

data/docs/migration-guide.md

@@ -0,0 +1,286 @@
+# Migration Guide
+
+Migrate your visual regression testing from other tools to `capybara-screenshot-diff`. This guide covers the most common migration paths.
+
+## Why Switch?
+
+| Factor | Percy / Chromatic | BackstopJS | `capybara-screenshot-diff` |
+|--------|-------------------|------------|--------------------------|
+| Pricing | Paid SaaS (snapshot limits) | Free | Free (MIT) |
+| Infrastructure | Cloud service, API tokens | Node + Puppeteer | Ruby gem, no external services |
+| Baselines | Hosted on their servers | Local files | Git (committed to repo) |
+| Review | Web dashboard | HTML report | HTML report + GitHub PR comments |
+| PR integration | GitHub app | Manual CI steps | Reusable GitHub Action |
+| Offline | ❌ Requires internet | ✅ | ✅ |
+| Diff in PRs | Screenshot in comment | Manual | Upload artifact + PR comment |
+
+## From Percy
+
+### Setup changes
+
+**Before (Percy):**
+```ruby
+# Gemfile
+gem 'percy-capybara'
+
+# test helper
+require 'percy/capybara'
+
+# test
+def test_homepage
+  visit '/'
+  Percy::Capybara.screenshot('homepage')
+end
+```
+
+**After (capybara-screenshot-diff):**
+```ruby
+# Gemfile
+gem 'capybara-screenshot-diff'
+
+# test helper
+require 'capybara_screenshot_diff/minitest'
+
+# test class
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include CapybaraScreenshotDiff::Minitest::Assertions
+
+  test "homepage" do
+    visit '/'
+    screenshot 'homepage'
+  end
+end
+```
+
+### What changes
+
+| Concept | Percy | capybara-screenshot-diff |
+|---------|-------|-------------------------|
+| Baseline storage | Percy cloud | Committed to git (`doc/screenshots/`) |
+| First run | Uploads to Percy | Saves locally, passes automatically |
+| CI setup | `PERCY_TOKEN` env var | GitHub Action (3 lines) |
+| Diff review | Percy dashboard | `snap_diff_report.html` or PR artifacts |
+| Update baselines | Percy's "Approve" button | Delete file, re-run tests, commit |
+| Snapshot limits | Paid plan dependent | Unlimited |
+| Parallel builds | Built-in | Thread-safe with t-locals + mutex |
+
+### CI migration
+
+**Before (Percy GitHub Action):**
+```yaml
+- name: Percy Test
+  run: PERCY_TOKEN=${{ secrets.PERCY_TOKEN }} bundle exec rake test
+```
+
+**After (capybara-screenshot-diff):**
+```yaml
+- uses: snap-diff/snap_diff-capybara/.github/actions/setup-ruby-and-dependencies@master
+  with:
+    ruby-version: '4.0'
+- run: bundle exec rake test
+- uses: snap-diff/snap_diff-capybara/.github/actions/upload-screenshots@master
+  if: failure()
+  with:
+    name: screenshots
+    pr-comment: 'true'
+```
+
+### Migration steps
+
+1. **Remove Percy gem and configuration**
+2. **Add `capybara-screenshot-diff`** to your Gemfile
+3. **Replace `Percy::Capybara.screenshot` calls** with `screenshot` (or `match_screenshot` for RSpec)
+4. **Run tests once** to generate baselines
+5. **Commit baselines** (`git add doc/screenshots/`)
+6. **Set up CI** with the GitHub Actions upload step
+7. **Remove Percy integration** from CI
+
+---
+
+## From Chromatic
+
+### Setup changes
+
+**Before (Chromatic + Storybook):**
+```js
+// .storybook/preview.js
+import { withScreenshot } from 'chromatic';
+
+export const decorators = [withScreenshot];
+```
+
+**After (capybara-screenshot-diff):**
+```ruby
+# test/system/stories_test.rb
+class StoriesTest < ApplicationSystemTestCase
+  test "landing page story" do
+    visit '/iframe.html?id=pages-landing--default'
+    screenshot 'stories/landing-page'
+  end
+end
+```
+
+### Key differences
+
+| Concept | Chromatic | capybara-screenshot-diff |
+|---------|-----------|-------------------------|
+| Focus | Storybook components | Full-page system tests |
+| Baseline | Chromatic cloud | Git-committed |
+| Review | Chromatic web UI | HTML report + PR artifacts |
+| CI integration | Chromatic GitHub App | GitHub Actions + PR comments |
+| Thresholds | Visual catch (AI) | Configurable tolerance (numeric) |
+
+### Migration approach
+
+Chromatic is primarily for Storybook component testing. If you want to continue testing individual components:
+
+1. **Replace with Capybara system tests** that visit each component's rendered page
+2. **Use `crop:` option** to isolate specific elements: `screenshot 'button', crop: '.my-button'`
+3. **Use `skip_area:` option** to ignore dynamic regions: `screenshot 'dashboard', skip_area: ['.timestamp']`
+
+---
+
+## From BackstopJS
+
+### Setup changes
+
+**Before (BackstopJS):**
+```json
+// backstop.json
+{
+  "id": "homepage",
+  "viewports": [{"width": 1280, "height": 1024}],
+  "scenarios": [{
+    "label": "Homepage",
+    "url": "http://localhost:3000",
+    "referenceUrl": "http://localhost:3000",
+    "selectors": ["document"]
+  }],
+  "paths": {
+    "bitmaps_reference": "backstop_data/bitmaps_reference",
+    "bitmaps_test": "backstop_data/bitmaps_test",
+    "html_report": "backstop_data/html_report"
+  }
+}
+```
+
+**After (capybara-screenshot-diff):**
+```ruby
+class HomepageTest < ApplicationSystemTestCase
+  test "homepage" do
+    visit '/'
+    screenshot 'homepage'
+  end
+end
+```
+
+### Key differences
+
+| Concept | BackstopJS | capybara-screenshot-diff |
+|---------|-----------|-------------------------|
+| Language | JavaScript + Node | Ruby (runs in test suite) |
+| Dependencies | Node, Puppeteer/Chromium | Ruby gems + optional libvips |
+| Test runner | Standalone CLI | Minitest, RSpec, Cucumber |
+| Selectors | CSS selectors for scenarios | CSS selectors for crop/skip_area |
+| Viewports | Per-scenario config | Global `window_size` setting |
+| CI report | HTML report | HTML report + GitHub Actions |
+| Stability | `misMatchThreshold` + `delay` | `tolerance` + `stability_time_limit` |
+
+### Configuration mapping
+
+| BackstopJS option | capybara-screenshot-diff equivalent |
+|-------------------|-------------------------------------|
+| `misMatchThreshold` | `tolerance` (0.0-1.0 scale, e.g. `0.01` = 1%) |
+| `delay` | `stability_time_limit` (seconds) |
+| `selectors` | `crop:` option with CSS selector |
+| `hideSelectors` | `skip_area:` option with CSS selectors |
+| `removeSelectors` | N/A — use `skip_area` or modify DOM before screenshot |
+| `waitTimeout` | `wait:` option (defaults to `Capybara.default_max_wait_time`) |
+| `viewports` | `window_size: [width, height]` |
+| `onReadyScript` | Custom setup in your test's `setup` block |
+
+### CI migration
+
+**Before (BackstopJS in CI):**
+```yaml
+- run: npx backstop test --config=backstop.json
+```
+
+**After (capybara-screenshot-diff in CI):**
+```yaml
+- uses: snap-diff/snap_diff-capybara/.github/actions/setup-ruby-and-dependencies@master
+- run: bundle exec rake test
+- uses: snap-diff/snap_diff-capybara/.github/actions/upload-screenshots@master
+  if: failure()
+  with:
+    name: screenshots
+    pr-comment: 'true'
+```
+
+### Migration steps
+
+1. **Remove BackstopJS configuration** (`backstop.json`, npm dependencies)
+2. **Convert scenarios to Capybara tests** — each scenario becomes a `screenshot` call
+3. **Map threshold and delay settings** to `tolerance` and `stability_time_limit`
+4. **Run tests** to generate baselines
+5. **Commit baselines** (`git add doc/screenshots/`)
+6. **Update CI** to use the GitHub Actions setup
+
+---
+
+## General Migration Checklist
+
+- [ ] Remove old gem/npm dependencies
+- [ ] Add `capybara-screenshot-diff` to Gemfile
+- [ ] Require the appropriate adapter (`minitest`, `rspec`, or `cucumber`)
+- [ ] Replace screenshot calls with `screenshot` / `match_screenshot`
+- [ ] Configure `window_size` for consistent viewport dimensions
+- [ ] Set `tolerance` or `perceptual_threshold` if your previous tool had a mismatch threshold
+- [ ] Add `.gitignore` patterns for diff artifacts
+- [ ] Run tests to generate baseline screenshots
+- [ ] Commit baselines to git
+- [ ] Set up CI with artifact upload
+- [ ] Optional: add HTML reporter and PR commenting
+
+## Common Gotchas
+
+### "My baselines are on Percy/Chromatic servers"
+
+You'll need to take fresh screenshots. Either:
+- Visit each page and capture manually
+- Run tests with `RECORD_SCREENSHOTS=1` to generate all baselines at once
+
+### "I had hundreds of BackstopJS scenarios"
+
+Start small. Migrate one test file at a time. The `screenshot_group` feature helps organize related screenshots:
+```ruby
+screenshot_group 'checkout'
+screenshot 'step1'
+screenshot 'step2'
+# Produces: doc/screenshots/checkout/00_step1.png, 01_step2.png
+```
+
+### "My tests are slow now"
+
+Use the VIPS driver for ~50ms comparisons per image:
+```ruby
+gem 'ruby-vips'
+Capybara::Screenshot::Diff.driver = :vips
+```
+
+### "The diffs look different from what I'm used to"
+
+Each tool uses different comparison algorithms:
+- **Percy:** Proprietary pixel-level comparison with AI smoothing
+- **Chromatic:** Visual catch algorithm (structure-aware)
+- **BackstopJS:** Resemble.js pixel comparison
+- **capybara-screenshot-diff:** Raw pixel difference with configurable tolerance
+
+Start with default settings, then adjust `tolerance` or `perceptual_threshold` based on your needs.
+
+## Need Help?
+
+- [Architecture Overview](docs/architecture.md) — understanding how comparisons work
+- [Configuration Reference](docs/configuration.md) — all available options
+- [CI Integration](docs/ci-integration.md) — setting up in CI
+- [GitHub Issues](https://github.com/snap-diff/snap_diff-capybara/issues) — ask questions

data/docs/organization.md

@@ -0,0 +1,204 @@
+# Screenshot Organization
+
+## Taking screenshots
+
+Add `screenshot '<my_feature>'` to your tests.  The screenshot will be saved in
+the `doc/screenshots` directory.
+
+Change your existing `save_screenshot` calls to `screenshot`
+
+```ruby
+test 'my useful feature' do
+  visit '/'
+  screenshot 'welcome_index'
+  click_button 'Useful feature'
+  screenshot 'feature_index'
+  click_button 'Perform action'
+  screenshot 'action_performed'
+end
+```
+
+This will produce a sequence of images like this
+
+```
+doc
+  screenshots
+    action_performed
+    feature_index
+    welcome_index
+```
+
+To store the screenshot history, add the `doc/screenshots` directory to your
+version control system (git).
+
+Screenshots are compared to the previously COMMITTED version of the same screenshot.
+
+**Note:** When a screenshot differs, diff artifacts (`.diff.png`, `.heatmap.diff.png`, etc.) are generated alongside the baseline. Add `*.diff.png`, `*.base.png`, `*.diff.webp`, `*.base.webp`, and `snap_diff_report.html` to your `.gitignore`. Clean up artifacts with `rake snap_diff:clean`.
+
+## Screenshot groups
+
+Commonly it is useful to group screenshots around a feature, and record them as
+a sequence.  To do this, add a `screenshot_group` call to the start of your
+test.
+
+```ruby
+test 'my useful feature' do
+  screenshot_group 'useful_feature'
+  visit '/'
+  screenshot 'welcome_index'
+  click_button 'Useful feature'
+  screenshot 'feature_index'
+  click_button 'Perform action'
+  screenshot 'action_performed'
+end
+```
+
+This will produce a sequence of images like this
+
+```
+doc
+  screenshots
+    useful_feature
+      00_welcome_index
+      01_feature_index
+      02_action_performed
+```
+
+**Note:** `screenshot_group` sets the group name for organizing screenshots. It does not delete existing files.
+
+
+## Screenshot sections
+
+You can introduce another level above the screenshot group called a
+`screenshot_section`.  The section name is inserted just before the group name
+in the save path.  If called in the setup of the test, all screenshots in
+that test will get the same prefix:
+
+```ruby
+setup do
+  screenshot_section 'my_feature'
+end
+
+test 'my subfeature' do
+  screenshot_group 'subfeature'
+  visit '/feature'
+  click_button 'Interesting button'
+  screenshot 'subfeature_index'
+  click_button 'Perform action'
+  screenshot 'action_performed'
+end
+```
+
+This will produce a sequence of images like this
+
+```
+doc
+  screenshots
+    my_feature
+      subfeature
+        00_subfeature_index
+        01_action_performed
+```
+
+
+## Setting `screenshot_section` and/or `screenshot_group` for all tests
+
+Setting the `screenshot_section` and/or `screenshot_group` for all tests can be
+done in the super class setup:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  setup do
+    screenshot_section class_name.underscore.sub(/(_feature|_system)?_test$/, '')
+    screenshot_group name[5..-1]
+  end
+end
+```
+
+`screenshot_section` and/or `screenshot_group` can still be overridden in each
+test.
+
+
+## Capturing one area instead of the whole page
+
+You can crop images before comparison to be run, by providing region to crop as `[left, top, right, bottom]` or by css selector like `body .tag`
+
+```ruby
+test 'the cool' do
+  visit '/feature'
+  screenshot 'cool_element', crop: '#my_element'
+end
+```
+
+**Note:** When using a retina device screenshots dimensions might be off. If
+you are using (headless) chrome you can prevent this by setting the
+`force-device-scale-factor` argument to `1`.
+
+For Rails system specs using selenium you can do so for example by using the
+following snippet:
+
+```ruby
+driven_by :selenium, using: :chrome_headless do |options|
+  options.args << '--force-device-scale-factor=1'
+end
+```
+
+## Multiple Capybara drivers
+
+Often it is useful to test your app using different browsers.  To avoid the
+screenshots for different Capybara drivers to overwrite each other, set
+
+```ruby
+Capybara::Screenshot.add_driver_path = true
+```
+
+The example above will then save your screenshots like this
+(for poltergeist and selenium):
+
+```
+doc
+  screenshots
+    poltergeist
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+    selenium
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+```
+
+## Multiple OSs
+
+If you run your tests on multiple operating systems, you will most likely find
+the screen shots differ.  To avoid the screenshots for different OSs to
+overwrite each other, set
+
+```ruby
+Capybara::Screenshot.add_os_path = true
+```
+
+The example above will then save your screenshots like this
+(for Linux and Windows):
+
+```
+doc
+  screenshots
+    linux
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+    windows
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+```
+
+If you combine this config with the `add_driver_path` config, the driver will be
+put in front of the OS name.
+
+[← Back to README](../README.md)