snap_diff-capybara 2.0.0.beta3 → 2.0.0.beta4

data/docs/configuration.md

@@ -11,7 +11,6 @@ SnapDiff.configure do |config|
   config.stability_time_limit = 1
   config.blur_active_element = true
   config.hide_caret = true
-  config.driver = :vips
   config.tolerance = 0.0005
   config.color_distance_limit = 15
 end
@@ -26,12 +25,15 @@ Capybara::Screenshot::Diff.configure do |screenshot, diff|
   screenshot.stability_time_limit = 1
   screenshot.blur_active_element = true
   screenshot.hide_caret = true
-  diff.driver = :vips
   diff.tolerance = 0.0005
   diff.color_distance_limit = 15
 end
 ```
 
+> **`driver:` is deliberately absent from both examples.** The setting is removed in 2.1
+> (`NoMethodError` at config time) and 2.0 cannot warn about it. Add `gem "ruby-vips"` and
+> leave the selection alone — see [Drivers](drivers.md#removed-in-21-everything-on-this-page-except-vips).
+
 `SnapDiff::Config` **is** the storage; the legacy accessors are thin delegators onto it. There is
 one source of truth, so a write through either surface is visible through the other — mixing them
 is safe, and you can migrate a suite one line at a time:
@@ -46,9 +48,86 @@ exception: `Capybara::Screenshot.enabled` is `SnapDiff.config.screenshot_enabled
 `SnapDiff.config.enabled` is taken by `Capybara::Screenshot::Diff.enabled`. See
 [SnapDiff — the canonical API](snapdiff.md) for the full SnapDiff-native surface.
 
-**Note:** `fail_if_new` defaults to `true` in CI environments (when `ENV['CI']` is set). New screenshots are allowed locally but rejected in CI — no configuration needed.
+**Note:** Setting `SnapDiff.config.screenshot_enabled = false` is sufficient to disable all screenshots. There is no need to define no-op modules or monkey-patch the gem.
+
+## Record modes — accepting changes
+
+`record` is the single setting for *what happens when a screenshot has no committed baseline, or
+when you want to accept the ones that changed*. It replaces `fail_if_new`, which is removed in 2.1.
+
+```ruby
+SnapDiff.config.record = :once   # what a local run already does; see Precedence below for CI
+```
+
+| Mode | Missing baseline | Baseline present | Reach for it when |
+|------|------------------|------------------|-------------------|
+| `:once` | recorded, not compared | compared | the default — you want a normal run |
+| `:none` | **fails** with the `git add` command attached | compared | every screenshot must already be recorded |
+| `:all` | recorded | **re-recorded, not compared** | you changed the UI on purpose and want the new rendering to become the baseline |
+
+### `:all` — the bulk-accept verb
+
+After an intentional redesign that changed forty screenshots, re-record them in one run rather
+than accepting them one failure at a time:
+
+```ruby
+# test_helper.rb. There is no CLI flag — the gem has no runner to hang one on —
+# so gate it on an environment variable of your own if you want one:
+SnapDiff.config.record = ENV["ACCEPT_SCREENSHOTS"] ? :all : :once
+```
+
+```bash
+ACCEPT_SCREENSHOTS=1 bin/rails test:system     # with the line above in test_helper.rb
+```
+
+Every screenshot is written to its baseline path and nothing is compared, so `git status` lists
+exactly what changed. Review the images, then commit them — see
+[Accepting an intentional change](../README.md#accepting-an-intentional-change).
+
+At the end of the run the gem names what it accepted:
+
+```
+[snap_diff] record: :all re-recorded 3 screenshots WITHOUT comparing: checkout/cart, checkout/payment, checkout/review. Review the result before committing -- an unintended change is accepted just as silently.
+```
+
+> **`:all` refuses to run under CI** (when `ENV['CI']` is set to a non-empty value). It accepts
+> every rendering by design, so a mode left in a committed config file would buy you a build that
+> compares nothing and passes forever, with the "recorded" screenshots discarded when the runner
+> is torn down. Re-record locally, where you can look at the result.
+>
+> A CI job that needs to record screenshots with **no baseline yet** does not need `:all`:
+> `record = :once` records those and still compares everything that has a baseline. See
+> [CI integration](ci-integration.md).
+
+### Per screenshot
+
+```ruby
+assert_matches_screenshot "flaky_widget", record: :none   # this one must already exist
+```
+
+### Precedence
+
+**An explicitly set mode outranks `fail_if_new`; `fail_if_new` decides only when no mode was set.**
+That is the same rule `fail_if_new` itself has over the `CI` sniff — explicit outranks implicit, all
+the way down. Per screenshot outranks the config; the config outranks `fail_if_new`.
+
+With **nothing** set, `record` reads back as `:none` under CI and `:once` off it — which is exactly
+what `fail_if_new` has always done, so a suite that never mentions `record` behaves as it always
+did. The missing-baseline default is deliberately unchanged: failing only under CI is what Jest,
+AVA, Vitest, testthat and jest-image-snapshot all chose, and a screenshot baseline recorded on your
+laptop is often worthless on another OS. `:none` makes strictness an explicit choice instead.
 
-**Note:** Setting `Capybara::Screenshot.enabled = false` is sufficient to disable all screenshots. There is no need to define no-op modules or monkey-patch the gem.
+| You wrote | `record` reads | Missing baseline |
+|-----------|----------------|------------------|
+| nothing, off CI | `:once` | recorded |
+| nothing, under CI | `:none` | fails |
+| `record = :once` | `:once` | recorded, on CI too |
+| `record = :none` | `:none` | fails, off CI too |
+| `record = :once`, `fail_if_new = true` | `:once` | recorded — the mode wins |
+| `record = nil`, `fail_if_new = true` | `:none` | fails — nil hands it back |
+
+A misspelt mode raises `ArgumentError` at the point you set it, rather than reading back as
+"nobody said".
 
 ## Recommended tolerance values
 
@@ -105,7 +184,8 @@ screenshot 'dashboard', color_distance_limit: 15
 ## Configuration Tiers
 
 **Tier 1 — Zero config (works immediately):**
-`blur_active_element`, `hide_caret`, and `fail_if_new` (in CI) are enabled by default.
+`blur_active_element` and `hide_caret` are on by default, and `record` behaves as `:none` in CI
+(a missing baseline fails) and `:once` off it.
 Just `require 'snap_diff/integrations/minitest'` (legacy: `capybara_screenshot_diff/minitest`) and call `screenshot`.
 
 **Tier 2 — Set when tests are flaky:**
@@ -122,7 +202,7 @@ Just `require 'snap_diff/integrations/minitest'` (legacy: `capybara_screenshot_d
 | Setting | When to use |
 |---------|-------------|
 | `perceptual_threshold` | Anti-aliasing false positives across OS/browser versions |
-| `shift_distance_limit` | Content shifts by a few pixels (ChunkyPNG only) |
+| `shift_distance_limit` | Content shifts by a few pixels (ChunkyPNG only — **removed in 2.1**) |
 | `area_size_limit` | Allow small diff regions below a pixel count |
 | `color_distance_limit` | Fine-tune raw RGB channel tolerance |
 | `median_filter_window_size` | Smooth noise before comparison (VIPS only) |
@@ -147,15 +227,18 @@ unless the desired window size can be achieved.
 If you want to skip taking screen shots, set
 
 ```ruby
-Capybara::Screenshot.enabled = false
+SnapDiff.config.screenshot_enabled = false
 ```
 
 You can of course set this by an environment variable
 
 ```ruby
-Capybara::Screenshot.enabled = ENV['TAKE_SCREENSHOTS']
+SnapDiff.config.screenshot_enabled = ENV['TAKE_SCREENSHOTS']
 ```
 
+A disabled screenshot is not an assertion, and Minitest is told so: a test whose only assertion
+was a screenshot reports as missing assertions rather than as a pass over nothing.
+
 ### Disabling diff
 
 If you want to skip the assertion for change in the screen shot, set
@@ -172,6 +255,10 @@ Capybara::Screenshot::Diff.enabled = ENV['COMPARE_SCREENSHOTS']
 
 ### Tolerate screenshot differences
 
+> **Removed in 2.1.** A screenshot that differs from its baseline fails — that is what the gem is
+> for. To *accept* a difference, re-record it: [`record = :all`](#record-modes--accepting-changes).
+> It keeps working for the whole 2.x line and warns once per process.
+
 To allow screenshot differences, but still fail on functional errors, you can set the following option:
 
 ```ruby
@@ -183,6 +270,11 @@ report while still reporting functional errors.
 
 ### Does not tolerate new screenshots
 
+> **Removed in 2.1, superseded by [`record`](#record-modes--accepting-changes).**
+> `record = :none` is `fail_if_new = true`; `record = :once` is `fail_if_new = false`. Unlike the
+> boolean, a mode means the same thing on CI and off it. It keeps working for the whole 2.x line and
+> warns once per process.
+
 To fail the test if a new screenshot is taken, set the following option:
 
 ```ruby
@@ -194,8 +286,17 @@ that does not have a corresponding previous image to compare against.
 This can be useful in situations where you want to ensure
 that every screenshot taken by your tests corresponds to an expected state of your application.
 
+`fail_if_new` defaults to `true` in CI environments (when `ENV['CI']` is set to a non-empty value).
+Setting it yourself outranks the environment: `fail_if_new = false` stays `false` under `CI=true`.
+Assign `nil` to hand it back to the environment. Setting `record` outranks it either way.
+
 ### Marks new screenshots as pending
 
+> **Removed in 2.1.** It skips the test instead of saying what to do about the missing baseline.
+> [`record = :none`](#record-modes--accepting-changes) fails with the `git add` command attached;
+> `record = :once` records the screenshot and names it in the end-of-run summary. It keeps working
+> for the whole 2.x line and warns once per process.
+
 To mark tests as pending (skipped) if a new screenshot is taken without a baseline, set:
 
 ```ruby
@@ -313,6 +414,15 @@ Capybara::Screenshot::Diff.color_distance_limit = 42
 
 ### Allowed shift distance
 
+> **Removed in 2.1.** `shift_distance_limit` is implemented only by the ChunkyPNG driver,
+> and 2.1 removes that driver — libvips becomes the only backend. Setting it anywhere
+> (`SnapDiff.config.shift_distance_limit =`, the legacy
+> `Capybara::Screenshot::Diff.shift_distance_limit =`, or `screenshot 'index',
+> shift_distance_limit: 2`) warns once per process in 2.0. There is no vips equivalent:
+> use `median_filter_window_size` (the faster answer to the same problem — see
+> [Drivers](drivers.md#median-filter-size-vips-only)), `tolerance`, or
+> `color_distance_limit`.
+
 Sometimes you want to allow small movements in the images.  For example, jquery-tablesorter
 renders the same table slightly differently sometimes.  You can set set the shift distance
 threshold for the comparison using the `shift_distance_limit` option to the `screenshot`
@@ -362,8 +472,6 @@ Capybara::Screenshot::Diff.area_size_limit = 42
 Sometimes you have expected change that you want to ignore.
 You can use the `skip_area` option with `[left, top, right, bottom]`
 or css selector like `'#footer'` or `'.container .skipped_element'` to the `screenshot` method to ignore an area.
-Be aware that if the selector is not in the page then the library will wait the default wait time for it to appear.
-Therefore, it is best to only use css selectors for skip_areas you know will be in the page:
 
 ```ruby
 test 'unstable area' do
@@ -372,6 +480,64 @@ test 'unstable area' do
 end
 ```
 
+**`skip_area` masks what is on the page at assertion time — it does not wait.**
+A selector is resolved against the DOM as it is when the screenshot is taken; one
+that matches nothing masks nothing, immediately. (Until 2.0 it blocked for
+`Capybara.default_max_wait_time` per unmatched selector — 5s each, on every
+screenshot. That wait is gone.)
+
+So content that arrives late — lazy-loaded images, JS-injected widgets, anything
+behind an unresolved fetch — has to be settled *before* the assertion, or its
+mask will be empty and the unstable region will be compared. Settle it in the
+readiness block described below.
+
+If a selector matched nothing in *every* screenshot of a run, the end-of-run
+summary names it:
+
+```
+[snap_diff] 1 selector never matched anything in this run: "artcile img". A selector that matches nothing masks nothing -- check for a typo or a stale selector.
+```
+
+That is a run-level fact on purpose. Per screenshot the gem cannot tell a typo
+from a page that legitimately has no images, so it says nothing; a selector that
+matched *somewhere* is doing its job and is never mentioned. Nothing is printed
+when every selector matched.
+
+### The readiness block
+
+`assert_matches_screenshot` and `capture_screenshot` (and the `screenshot` /
+`assert_no_screenshot_changes` wrappers) take an optional block. It runs once,
+after the enabled check and before the capture:
+
+```ruby
+test 'gallery' do
+  visit '/gallery'
+  assert_matches_screenshot 'gallery', skip_area: ['article img'] do
+    scroll_to :bottom
+    assert_text 'End of gallery'
+    scroll_to :top
+  end
+end
+```
+
+**Why a block rather than the line above it:** work in the block is skipped when
+screenshots are off. Both methods return immediately when
+`SnapDiff.config.enabled` (or `screenshot_enabled`) is false, so a
+`preload_all_images` written on the preceding line still pays for its browser
+round-trips — scroll, wait, scroll back — for a screenshot that is never taken.
+Inside the block it costs nothing, which is what makes turning visual tests off
+actually free.
+
+Errors raised in the block are yours and propagate unchanged. It is not a hook:
+there is no configuration-level equivalent, no after-block, and it runs once per
+assertion rather than once per stability retry.
+
+In RSpec, call `assert_matches_screenshot` directly rather than through the
+`match_screenshot` matcher — `expect(page).to match_screenshot('x') { ... }`
+binds the block by Ruby's `{}`/`do...end` precedence rather than by intent, so
+the matcher does not take one. In Cucumber the DSL is in the World, so step
+definitions pass a block the same way a Minitest test does.
+
 The arguments are `[left, top, right, bottom]` for the area you want to ignore.  You can also set this globally:
 
 ```ruby

data/docs/drivers.md

@@ -6,6 +6,44 @@
 > [Custom drivers](snapdiff.md#custom-drivers) for the `SnapDiff::Driver` mixin and how
 > registration in `SnapDiff::Drivers.loaded` works.
 
+## Removed in 2.1: everything on this page except VIPS
+
+2.1 makes **libvips the only backend**. 2.0 is the transitional release — all of the
+following still works. Most of it warns once per process naming 2.1; the rows marked
+*silent* cannot warn, and this table is their notice. Silence the warnings with
+`SnapDiff.silence_deprecations = true` or `SNAP_DIFF_SILENCE_DEPRECATIONS=1`.
+
+| Removed in 2.1 | What to do in 2.0 |
+|---|---|
+| the `:chunky_png` driver | add `gem "ruby-vips"` to your Gemfile and drop `driver: :chunky_png` |
+| the `driver:` setting itself — `SnapDiff.config.driver =` and the legacy `Capybara::Screenshot::Diff.driver =` (**silent in 2.0**; on 2.1 they raise `NoMethodError` at config time) | delete the line; one backend needs no selection |
+| the per-screenshot `driver:` override — `screenshot "index", driver: :vips` (**no deprecation warning in 2.0** -- but the key is validated, not inert: an unknown driver raises `RuntimeError: Wrong adapter ...`. 2.1 rejects the key outright) | delete the option, and grep for it — nothing will tell you the line is dead |
+| `driver: :auto` (and the `:auto` default) — warns **only when `:auto` actually falls back to ChunkyPNG**, i.e. when `ruby-vips` is missing; **silent** otherwise | with one backend there is nothing to choose; install `ruby-vips` and the default just works |
+| `shift_distance_limit` | ChunkyPNG-only. Use `median_filter_window_size`, `tolerance` or `color_distance_limit` — see [Configuration](configuration.md#allowed-shift-distance) |
+| `SnapDiff::Driver` (the custom-driver mixin) | nothing — see below |
+| `SnapDiff::Drivers.loaded` (the registry) | nothing — see below |
+| `SnapDiff::Drivers.available` (driver detection) | require `ruby-vips` instead of branching on a detected list |
+
+Three related names on the same chopping block stay **silent**, and deliberately so:
+`SnapDiff::Drivers.for` (the gem calls it for every comparison — warning there would fire on
+setups that nothing in this table affects), `SnapDiff::Drivers.detect_available` /
+`SnapDiff::Utils.detect_available_drivers` (run at load, before any user code), and the legacy
+`Capybara::Screenshot::Diff::LOADED_DRIVERS` / `::AVAILABLE_DRIVERS` constant aliases (plain
+constants, nothing to hook). Reach the same values through `.loaded` / `.available` and you
+will hear about them.
+
+**libvips becomes a hard requirement.** Install it with your system package manager
+(`brew install vips`, `apt-get install libvips`) and add `gem "ruby-vips"`. A 2.1 process
+without it cannot compare images at all.
+
+**Custom drivers: there is no migration path.** The driver abstraction is removed whole —
+the `SnapDiff::Driver` mixin, the `SnapDiff::Drivers.loaded` registry, and driver
+selection by name. Third-party drivers stop working in 2.1 and nothing replaces them
+(the decision was made deliberately: no measurable demand, and one backend is what keeps
+the comparison engine honest). If you maintain one, say so on
+[the issue tracker](https://github.com/snap-diff/snap_diff-capybara/issues) before 2.1
+ships — that is the only thing that can change this.
+
 ## Perceptual color comparison (VIPS only)
 
 By default, color differences are measured using raw RGB channel distance. This can produce
@@ -52,15 +90,20 @@ There are several options to setup active driver: `:auto`, `:chunky_png` and `:v
 * `: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
 
+> **2.1 keeps only `:vips`.** `:auto` and `:chunky_png` are removed; `:chunky_png` warns once per
+> process in 2.0. If `:auto` is quietly running you on ChunkyPNG today (no `ruby-vips`
+> installed), the warning says so — that is the setup 2.1 breaks.
+
 ## 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:
+and is enabled by adding `ruby-vips` to your `Gemfile` (plus the libvips system package).
+That is the whole setup — with `ruby-vips` installed the default `:auto` already picks it.
 
-* Globally: `Capybara::Screenshot::Diff.driver = :vips`
-* Per screenshot option: `screenshot 'index', driver: :vips`
+**Do not select it explicitly.** Both forms are on the 2.1 removal list at the top of this page:
+`Capybara::Screenshot::Diff.driver = :vips` / `SnapDiff.config.driver = :vips` raises
+`NoMethodError` at config time on 2.1, and the per-screenshot `screenshot 'index', driver: :vips`
+becomes inert. Neither warns in 2.0 — delete the line and grep for the per-screenshot form.
 
 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`.

data/docs/framework-setup.md

@@ -26,12 +26,16 @@ For Minitest, need to require `capybara_screenshot_diff/minitest`.
 In your test class, include the `CapybaraScreenshotDiff::Minitest::Assertions` module:
 
 ```ruby
+# test/application_system_test_case.rb
+require 'test_helper'
 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
+  # Pin the browser: window size and pixel ratio are inputs to every comparison
+  driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400]
+
+  # Make `assert_*` methods behave like Minitest assertions.
+  # This already includes CapybaraScreenshotDiff::DSL — a separate include is not needed.
   include CapybaraScreenshotDiff::Minitest::Assertions
 
   def test_my_feature
@@ -41,6 +45,9 @@ class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
 end
 ```
 
+Run it with `bin/rails test:system` — `rake test` / `rails test` skip `test/system/` and
+report `0 runs`.
+
 ## RSpec
 
 To use the screenshot capturing and change detection features in your tests,

data/docs/migration-guide.md

@@ -35,15 +35,19 @@ end
 
 **After (capybara-screenshot-diff):**
 ```ruby
-# Gemfile
-gem 'capybara-screenshot-diff'
+# Gemfile — pin the exact prerelease; '~> 2.0' does not resolve until 2.0.0 ships
+gem 'capybara-screenshot-diff', '2.0.0.beta4'
 
 # test helper
-require 'capybara_screenshot_diff/minitest'
+require "snap_diff/integrations/minitest"
+
+# test class — test/application_system_test_case.rb
+require "test_helper"
 
-# test class
 class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  include CapybaraScreenshotDiff::Minitest::Assertions
+  driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400]
+
+  include SnapDiff::Minitest::Assertions
 
   test "homepage" do
     visit '/'
@@ -60,7 +64,7 @@ end
 | 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 |
+| Update baselines | Percy's "Approve" button | Re-run tests (the run rewrites the baseline), review, commit — **not** delete: baselines are read from git |
 | Snapshot limits | Paid plan dependent | Unlimited |
 | Parallel builds | Built-in | Thread-safe with t-locals + mutex |
 
@@ -77,7 +81,7 @@ end
 - uses: snap-diff/snap_diff-capybara/.github/actions/setup-ruby-and-dependencies@master
   with:
     ruby-version: '4.0'
-- run: bundle exec rake test
+- run: bin/rails test:system   # not `rake test` — it skips test/system/
 - uses: snap-diff/snap_diff-capybara/.github/actions/upload-screenshots@master
   if: failure()
   with:
@@ -209,7 +213,7 @@ end
 **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
+- run: bin/rails test:system   # not `rake test` — it skips test/system/
 - uses: snap-diff/snap_diff-capybara/.github/actions/upload-screenshots@master
   if: failure()
   with:
@@ -246,9 +250,13 @@ end
 
 ### "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
+You'll need to take fresh screenshots. Run your system tests once — every screenshot
+is written to its baseline path, whether or not it matched — then commit them:
+
+```bash
+bin/rails test:system
+git add doc/screenshots/ && git commit -m "chore: record baselines"
+```
 
 ### "I had hundreds of BackstopJS scenarios"
 
@@ -262,11 +270,14 @@ screenshot 'step2'
 
 ### "My tests are slow now"
 
-Use the VIPS driver for ~50ms comparisons per image:
+Use libvips for ~50ms comparisons per image — installing the gem is the whole setup, and from
+2.1 it is the only backend:
 ```ruby
+# Gemfile
 gem 'ruby-vips'
-Capybara::Screenshot::Diff.driver = :vips
 ```
+Do **not** add `driver = :vips`: that setting is removed in 2.1 and raises `NoMethodError`
+there, silently, with nothing in 2.0 to warn you. See [Drivers](drivers.md).
 
 ### "The diffs look different from what I'm used to"
 

data/docs/reporters.md

@@ -18,7 +18,76 @@ open doc/screenshots/snap_diff_report.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.
+**Note:** The report is not generated when all screenshots match.
+
+## The end-of-run summary
+
+Every run ends with what it actually did, whether or not you require a reporter:
+
+```
+[snap_diff] 12 verified, 1 changed, 2 new (not verified).
+```
+
+- **verified** — a committed baseline existed and was compared
+- **changed** — of those, the ones that differed
+- **new** — captured but *not* compared, for want of a committed baseline: neither a pass nor a
+  failure. Commit the files to turn them into baselines.
+
+`0 verified` is printed as `NOTHING WAS VERIFIED`, because it is the only signal for the failures
+no per-assertion rule can see: a `rake test` that ran zero system tests, or an inherited `GIT_DIR`
+sending every baseline lookup to the wrong repository. Both leave a green suite that compared
+nothing.
+
+Requiring `snap_diff/reporters/html` adds one more line, naming the file it wrote:
+
+```
+[snap_diff] Report: doc/screenshots/snap_diff_report.html
+```
+
+## Parallel test runs
+
+`finalize` — the hook that writes the report — runs from the framework's end-of-suite hook. Whether
+that hook fires in the process holding the results depends on how your runner parallelizes:
+
+| How the suite runs | Report |
+| --- | --- |
+| Serial | Written, complete. |
+| `parallelize(with: :threads)` (also the default on JRuby) | Written, complete — same failures and counts as a serial run; only the order of the entries differs. Verified over repeated runs, provided [screenshot names are unique across tests](thread_safety.md#screenshot-names-must-be-unique-across-tests). |
+| `parallelize(workers: N)` (Rails' default, forks) | Written, complete — one report at the usual path, merged from every worker. No configuration needed. |
+| One process per worker (`parallel_tests`, RSpec, CI sharding) | Written, but only the **last** process to finish is in it; the others are overwritten. |
+
+Under Rails' forking parallelism the workers hold the results but never finalize: Minitest skips its
+`after_run` hooks in a forked child (`Minitest.allow_fork` defaults to `false`), and the parent
+process — the one that does finalize — recorded nothing. So each worker now hands its records to the
+parent on the way out (Rails' `run_cleanup` hook runs *inside* the worker), and the parent merges
+them before it writes the report. `N verified, N changed, N new` are the merged totals for the whole
+suite, not one worker's.
+
+The handoff goes through a scratch directory under the system temp dir, removed as soon as the merge
+is done. Nothing is written inside your repository, and a worker killed mid-write leaves nothing the
+merge will read.
+
+### Rails versions and older workarounds
+
+The merge uses `ActiveSupport::Testing::Parallelization`'s worker hooks and is registered only when
+Rails is present, so a non-Rails Capybara suite is unaffected.
+
+If your `test_helper.rb` still carries the old per-worker workaround —
+
+```ruby
+parallelize_teardown { SnapDiff::Reporting.finalize! }   # no longer needed
+```
+
+— you can delete it. Left in place it does not corrupt anything: the merged report is written last,
+at the documented path, with every failure in it. It just adds noise — each worker writes its own
+partial report over the same file first, and prints its own partial summary line (`32 verified …`
+four times, then the real one).
+
+Do **not** separate workers with a per-worker `save_path`: `save_path` is also where baselines are
+read from (`SnapDiff.config.screenshot_area`), so changing it per worker points the comparison at an
+empty baseline directory and every screenshot is recorded as new.
+
+See [Thread safety](thread_safety.md) for the state each mode shares.
 
 ## Custom Reporters
 

data/docs/snapdiff.md

@@ -4,9 +4,13 @@ Everything in this gem lives under `SnapDiff` since v2. This page is the SnapDif
 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.
+The legacy `Capybara::Screenshot::Diff` / `CapybaraScreenshotDiff` names still work — they resolve
+to the same objects — and the rest of the docs still teach them. A legacy config accessor,
+`include`, `default_options` call, or lazily shimmed constant prints one migration notice per
+process; *lazily shimmed* constants warn once each on top of that. Other legacy names — the
+integration requires and `CapybaraScreenshotDiff::Minitest::Assertions` among them — are silent
+by design, so a quiet suite is not a migrated one.
+[UPGRADING.md](UPGRADING.md#deprecation-warnings) lists exactly which is which. 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
@@ -20,12 +24,20 @@ require "snap_diff/integrations/minitest"
 
 ```ruby
 # test/application_system_test_case.rb
+require "test_helper"
+
 class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  # Window size and pixel ratio are inputs to every comparison — pin them.
+  driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400]
+
   include SnapDiff::Minitest::Assertions   # brings in SnapDiff::DSL too
 end
 ```
 
 ```ruby
+# test/system/homepage_test.rb
+require "application_system_test_case"
+
 class HomepageTest < ApplicationSystemTestCase
   test "homepage" do
     visit "/"
@@ -34,6 +46,9 @@ class HomepageTest < ApplicationSystemTestCase
 end
 ```
 
+Run it with `bin/rails test:system`. `rake test` and `rails test` skip `test/system/`
+entirely — `0 runs` and no baselines, which reads exactly like a pass.
+
 `SnapDiff::Minitest::Assertions` already includes `SnapDiff::DSL`, so a separate
 `include SnapDiff::DSL` is not needed (it is harmless if you have it).
 
@@ -95,14 +110,13 @@ loads the Minitest integration. See
 
 ## Configuration
 
-All 27 settings live on one flat object, `SnapDiff.config` (a `SnapDiff::Config`).
+All 28 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
 
@@ -159,12 +173,12 @@ integration require; a few objects need their own require, noted below.
 | `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::Error` | Base class for every error this gem *defines* — see the caveat below. Misuse still surfaces as plain Ruby: bad arguments raise `ArgumentError`, and a missing image backend raises `RuntimeError` |
 | `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::Driver` | Mixin with the shared driver defaults (`require "snap_diff/driver"`) — **removed in 2.1** |
+| `SnapDiff::Drivers` | Driver factory and registry — `.for`, `.loaded`, `.available` — **removed in 2.1** |
 | `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 |
@@ -174,6 +188,17 @@ integration require; a few objects need their own require, noted below.
 | `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"`) |
 
+> **`rescue SnapDiff::Error` does not catch a failed assertion under the framework
+> integrations.** `SnapDiff::ExpectationNotMet` — the row you most want to rescue — is
+> converted before it reaches your code: the Minitest integration re-raises it as
+> `Minitest::Assertion` ([`integrations/minitest.rb`](../lib/snap_diff/integrations/minitest.rb)),
+> and the RSpec integration as `RSpec::Expectations::ExpectationNotMetError`
+> ([`integrations/rspec.rb`](../lib/snap_diff/integrations/rspec.rb)). That conversion is the
+> point — it is what makes a mismatch a test failure rather than an error. You see a raw
+> `SnapDiff::ExpectationNotMet` only when you drive `SnapDiff::DSL` yourself, with a bare
+> `include SnapDiff::DSL` and no integration. `UnstableImage` and `WindowSizeMismatchError`
+> are not converted and do arrive as `SnapDiff::Error`.
+
 ## Compare two images without a browser
 
 Works on anything on disk — rendered PDFs, generated charts, CI artifacts:
@@ -262,6 +287,14 @@ SnapDiff::Reporting.finalize!
 
 ## Custom drivers
 
+> **Removed in 2.1 — no replacement.** libvips becomes the only backend, and the driver
+> abstraction goes with the choice: the `SnapDiff::Driver` mixin, the
+> `SnapDiff::Drivers.loaded` registry, `SnapDiff::Drivers.available`, and selecting a driver
+> by name. In 2.0 all of it still works and warns once per process (silence with
+> `SnapDiff.silence_deprecations = true` or `SNAP_DIFF_SILENCE_DEPRECATIONS=1`). Nothing
+> here migrates to a 2.1 shape — there is no 2.1 shape. If you maintain a driver, say so on
+> [the issue tracker](https://github.com/snap-diff/snap_diff-capybara/issues) before 2.1 ships.
+
 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: