refactor: split canonical vs legacy-surface tests (3.0 readiness) (#236)

* test: move the v1-surface tests into test/legacy/ and add rake test:canonical

The five tests whose SUBJECT is the v1 compatibility surface now live in
test/legacy/, so the 3.0 deletion is one more path on the same git rm:

  git rm -r lib/capybara* ... test/legacy

A directory rather than a list in the Rakefile: nothing to keep in sync.

- rake test           unchanged, runs everything (today's gate)
- rake test:canonical NEW, everything except test/legacy (the 3.0 gate)
- rake test:unit      test/unit + test/legacy, so the release gate keeps
                      its coverage (legacy/ marks lifetime, not kind)

errors_alias_test.rb was mixed: the four CapybaraScreenshotDiff::* alias
pairs are v1 surface, the hierarchy assertions outlive them. Split rather
than moved whole -- test/unit/errors_test.rb keeps the two canonical tests
verbatim, so no assertion is lost at 3.0.

530 runs, 1519 assertions, 0 failures (unchanged).

* test: point the whole canonical suite at SnapDiff names

The suite still spoke v1 everywhere, so it would have broken on the 3.0
deletion even though the gem no longer does. Mechanical, no behaviour and
no assertion values changed:

- harness: test_helper + system_test_case load snap_diff/integrations/*
  and configure through SnapDiff.config; the support stubs (DSLStub,
  ScreenshoterStub, TestDoubles, DriverCoverage, NonMinitest) stop
  reopening gem namespaces and become plain top-level modules
- 33 test files were defined inside module Capybara::Screenshot(::Diff) /
  CapybaraScreenshotDiff -- de-nested to top-level classes, so no bare
  constant resolves into a namespace 3.0 deletes
- 270 legacy constant/accessor/session call sites repointed
  (CapybaraScreenshotDiff.registry -> SnapDiff.session, .reporters ->
  SnapDiff::Reporting.reporters, Capybara::Screenshot.root ->
  SnapDiff.config.root, ...) and 25 legacy require paths
- legacy-surface tests now require the v1 entry point themselves, since
  the shared harness no longer loads it

Three claims would have become tautologies under a blind repoint
(assert_same SnapDiff.session, SnapDiff.session and friends): they were
forwarder-identity claims about the v1 view. Preserved verbatim in the new
test/legacy/legacy_forwarders_test.rb together with SnapDiff.start, which
yields the two v1 holders and cannot outlive them.

rake test:unit 534 runs, 1526 assertions, 0F/0E (was 530/1519)
rake test      562 runs, 1571 assertions, 0F/0E/1S (was 558/1564)
+4 runs: legacy_forwarders_test keeps the v1 claim where the canonical
file also kept its own version (register-appends, reporters_mutex, serve).

* test: split the mixed config/entry-point files along the same line

Four files asserted the canonical behaviour AND the v1 view of it in one
place, so a receiver repoint turned real claims into tautologies. Each is
now two files; the v1 half is verbatim, and the canonical half stands on
its own after 3.0:

- snap_diff_config_test        -> + test/legacy/legacy_config_accessors_test
  (CONFIG_MAPPING completeness, the mattr_accessor round trips, active?
  through the legacy forwarder, SnapDiff.start)
- config_default_timing_test   -> + test/legacy/legacy_config_default_timing_test
  canonical keeps snap_diff + snap_diff/integrations/minitest and reads
  SnapDiff.config only; the legacy file re-runs the SAME probe scripts
  under the v1 entries and adds the both-surfaces-agree loop, which is
  exactly what check_both asserted -- one source of truth, no drift
- support_load_probe_test      -> + test/legacy/legacy_entry_point_probe_test
  (advertised v1 constants, the CapybaraScreenshotDiff session surface,
  EAGER_USER_FACING / EAGER_EVERYWHERE under their OLD names)
- errors_alias_test (earlier commit) -> test/unit/errors_test

snap_diff-capybara joins CANONICAL_ENTRY_POINTS: 3.0 keeps that entry
point (repointed at snap_diff/integrations/minitest), and it was covered
only as a legacy entry, so it would have lost all coverage.

Also repointed the last legacy call sites the sweep left: the rspec
fixtures stubbed Capybara::Screenshot::Diff.pending_if_new, which the core
stopped reading in #235 -- a silent no-op stub, now SnapDiff.config.

rake test:unit 544 runs, 1544 assertions, 0F/0E
rake test      572 runs, 1589 assertions, 0F/0E/1S

* test: port the canonical claims that only a legacy-surface test was pinning

Audit of every assertion moving into test/legacy/, asking: if this file
vanished at 3.0, would any CANONICAL behaviour become untested? Two hits,
both now duplicated (not moved) into a canonical test -- the v1 originals
stay put, they still guard the v1 contract for all of 2.x:

- namespace_forwarding_test was the only place proving SnapDiff::Drivers
  .loaded is ONE hash mutated in place (it asserted the v1 LOADED_DRIVERS
  constant is that same object, and that registering through it shows up
  canonically). Utils.find_driver_class_for caches through .loaded, so a
  copy-returning refactor would break user driver registration silently.
  -> drivers_test ".loaded is a single hash mutated in place"
     mutation: `.loaded.dup[...] = ...` -> red, Expected :probe_driver, got nil

- the entry-point probe was the only place asserting an entry point defines
  its advertised CONSTANTS when it is the ONLY require (the f89cea2 bug
  class) -- but only for the v1 names.
  -> support_load_probe_test "every canonical entry point defines its
     advertised constants standalone", same claim over snap_diff/dsl,
     /integrations/minitest, /integrations/rspec, snap_diff-capybara.
     Entry-specific, because bare snap_diff carries neither DSL nor
     reporters by design.
     mutation: a bogus constant in the list -> red, naming it

Also: attempts_reporter_test now requires snap_diff/attempts_reporter --
stable_screenshoter pulls it in lazily and the v1 umbrella was what loaded
it eagerly, so it was the one canonical test the deletion actually broke.

Judged legacy-only and safe to lose at 3.0: const_missing/eager alias
semantics, deprecation warn-once + silencing, CONFIG_MAPPING completeness,
the alias-only scan of lib/capybara*, and the CapybaraScreenshotDiff
session/reporter forwarders -- every one is about a name 3.0 deletes, and
its canonical counterpart is pinned in test/unit/.

rake test 574 runs, 1593 assertions, 0F/0E/1S

* fix: the canonical gate demanded SnapDiff.start, which 3.0 deletes

Caught by independent review: `rake test:canonical` in the deleted tree is
1F, not the 0F I published.

CANONICAL_SURFACE listed `start`, applied to all 7 canonical entry points.
SnapDiff.start is defined only in lib/snap_diff/legacy_shims.rb:169 and
yields the two v1 config holders, so it cannot outlive them (#235 decided
this). A canonical gate demanding a method 3.0 deletes is a gate that goes
red the day the deletion lands -- and I widened it in e789c8a by adding
snap_diff-capybara. My own PR body filed .start under "safe to lose at 3.0".

  mutation (start put back, deleted tree):
    require "snap_diff"                       -> missing: start
    require "snap_diff/dsl"                   -> missing: start
    require "snap_diff/integrations/minitest" -> missing: start
    ... all 7 entry points

.start keeps full coverage on the legacy side: legacy_forwarders_test pins
what it yields and that it applies a setting, and a new per-entry-point
probe in legacy_entry_point_probe_test pins the availability claim the
canonical gate used to make -- for the entries that actually keep it.

Also, per review:

- "bare require never loads the umbrella" moves to legacy_forwarders_test.
  Its subject is lib/capybara_screenshot_diff.rb; once 3.0 deletes that
  file the $LOADED_FEATURES grep is empty by construction and the guard can
  never fail again. (-1 canonical run: 458 -> 457.)
- backtrace_filter_test built synthetic paths under lib/capybara_screenshot_diff/.
  Pure string inputs to a prefix matcher, so no assertion changes -- but one
  of them named the real file the filter defaults to, which 3.0 deletes.

rake test:unit      547 runs, 1550 assertions, 0F/0E/0S
rake test           575 runs, 1595 assertions, 0F/0E/1S
rake test:canonical 457 runs, 1288 assertions, 0F/0E/1S
  ... and 457/1288/0F/0E/1S in the deleted tree, identical.

Author: pftg

Rakefile

@@ -5,16 +5,46 @@ require "rake/testtask"
 
 task default: :test
 
+# THE 3.0 SPLIT.
+#
+# test/legacy/ holds every test whose SUBJECT is the v1 compatibility surface
+# -- the old Capybara::Screenshot / CapybaraScreenshotDiff namespaces, their
+# deprecation warnings, and the gates that keep lib/capybara* alias-only.
+# Those tests guard the v1 contract for the whole 2.x line, so they stay and
+# stay green; in 3.0 they are deleted by the same commit that deletes what
+# they test:
+#
+#   git rm -r lib/capybara* lib/capybara_screenshot_diff.rb \
+#             lib/snap_diff/legacy_shims.rb lib/snap_diff/deprecation.rb \
+#             test/legacy
+#
+# A directory rather than a list in this file: there is nothing to keep in
+# sync, and the deletion is one `git rm -r`.
+#
+# `rake test`           -- everything, today's gate.
+# `rake test:canonical` -- exactly what must still pass once test/legacy and
+#                          the v1 trees are gone. THE 3.0 GATE.
+# `rake test:unit`      -- unit-sized tests; test/legacy is unit-sized too
+#                          (legacy/ marks lifetime, not kind), so it is in.
+LEGACY_SURFACE_TESTS = "test/legacy/**/*_test.rb"
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+desc "Run every test that must survive the 3.0 deletion of the v1 surface"
+Rake::TestTask.new("test:canonical") do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"].exclude(LEGACY_SURFACE_TESTS)
+end
+
 Rake::TestTask.new("test:unit") do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/unit/**/*_test.rb"]
+  t.test_files = FileList["test/unit/**/*_test.rb", LEGACY_SURFACE_TESTS]
 end
 
 Rake::TestTask.new("test:integration") do |t|

test/fixtures/rspec_after_hook_order_masking_spec.rb

@@ -16,7 +16,7 @@
   end
 end
 
-require "capybara_screenshot_diff/rspec"
+require "snap_diff/integrations/rspec"
 require "support/stub_test_methods"
 
 unless defined?(SCREEN_SIZE)
@@ -40,23 +40,23 @@
   before do
     Capybara.current_driver = Capybara.javascript_driver
     Capybara.page.current_window.resize_to(*SCREEN_SIZE)
-    Capybara::Screenshot.window_size = SCREEN_SIZE
+    SnapDiff.config.window_size = SCREEN_SIZE
 
-    Capybara::Screenshot.save_path = "doc/screenshots"
-    Capybara::Screenshot.root = Rails.root / "../test/fixtures/app"
-    Capybara::Screenshot.add_os_path = true
-    Capybara::Screenshot.add_driver_path = true
-    Capybara::Screenshot::Diff.driver = ENV.fetch("SCREENSHOT_DRIVER", "chunky_png").to_sym
-    Capybara::Screenshot::Diff.tolerance = 0.5
+    SnapDiff.config.save_path = "doc/screenshots"
+    SnapDiff.config.root = Rails.root / "../test/fixtures/app"
+    SnapDiff.config.add_os_path = true
+    SnapDiff.config.add_driver_path = true
+    SnapDiff.config.driver = ENV.fetch("SCREENSHOT_DRIVER", "chunky_png").to_sym
+    SnapDiff.config.tolerance = 0.5
     # This fixture runs standalone in its own subprocess (no
     # ActiveSupport::TestCase setup forcing this off), and CI sets $CI,
     # which flips the default on and would raise before we ever get here.
-    Capybara::Screenshot::Diff.fail_if_new = false
+    SnapDiff.config.fail_if_new = false
   end
 
   it "keeps a real after-hook failure failing even when a new screenshot is pending" do
     name = "pending-masking-after-hook-order"
-    allow(Capybara::Screenshot::Diff).to receive(:pending_if_new).and_return(true)
+    allow(SnapDiff.config).to receive(:pending_if_new).and_return(true)
     visit "/"
     screenshot name
   ensure

test/fixtures/rspec_pending_masking_spec.rb

@@ -2,7 +2,7 @@
 
 require "capybara/rspec"
 
-require "capybara_screenshot_diff/rspec"
+require "snap_diff/integrations/rspec"
 require "support/stub_test_methods"
 
 unless defined?(SCREEN_SIZE)
@@ -27,23 +27,23 @@
   before do
     Capybara.current_driver = Capybara.javascript_driver
     Capybara.page.current_window.resize_to(*SCREEN_SIZE)
-    Capybara::Screenshot.window_size = SCREEN_SIZE
+    SnapDiff.config.window_size = SCREEN_SIZE
 
-    Capybara::Screenshot.save_path = "doc/screenshots"
-    Capybara::Screenshot.root = Rails.root / "../test/fixtures/app"
-    Capybara::Screenshot.add_os_path = true
-    Capybara::Screenshot.add_driver_path = true
-    Capybara::Screenshot::Diff.driver = ENV.fetch("SCREENSHOT_DRIVER", "chunky_png").to_sym
-    Capybara::Screenshot::Diff.tolerance = 0.5
+    SnapDiff.config.save_path = "doc/screenshots"
+    SnapDiff.config.root = Rails.root / "../test/fixtures/app"
+    SnapDiff.config.add_os_path = true
+    SnapDiff.config.add_driver_path = true
+    SnapDiff.config.driver = ENV.fetch("SCREENSHOT_DRIVER", "chunky_png").to_sym
+    SnapDiff.config.tolerance = 0.5
     # This fixture runs standalone in its own subprocess (no
     # ActiveSupport::TestCase setup forcing this off), and CI sets $CI,
     # which flips the default on and would raise before we ever get here.
-    Capybara::Screenshot::Diff.fail_if_new = false
+    SnapDiff.config.fail_if_new = false
   end
 
   it "keeps a genuine failure failing even when a new screenshot is pending" do
     name = "pending-masking-real-failure"
-    allow(Capybara::Screenshot::Diff).to receive(:pending_if_new).and_return(true)
+    allow(SnapDiff.config).to receive(:pending_if_new).and_return(true)
     visit "/"
     screenshot name
 

test/fixtures/rspec_spec.rb

@@ -2,7 +2,7 @@
 
 require "capybara/rspec"
 
-require "capybara_screenshot_diff/rspec"
+require "snap_diff/integrations/rspec"
 require "support/stub_test_methods"
 
 unless defined?(SCREEN_SIZE)
@@ -14,17 +14,17 @@
   before do
     Capybara.current_driver = Capybara.javascript_driver
     Capybara.page.current_window.resize_to(*SCREEN_SIZE)
-    Capybara::Screenshot.window_size = SCREEN_SIZE
-
-    Capybara::Screenshot.save_path = "doc/screenshots"
-    Capybara::Screenshot.root = Rails.root / "../test/fixtures/app"
-    Capybara::Screenshot.add_os_path = true
-    Capybara::Screenshot.add_driver_path = true
-    Capybara::Screenshot::Diff.driver = ENV.fetch("SCREENSHOT_DRIVER", "chunky_png").to_sym
-    Capybara::Screenshot::Diff.tolerance = 0.5
+    SnapDiff.config.window_size = SCREEN_SIZE
+
+    SnapDiff.config.save_path = "doc/screenshots"
+    SnapDiff.config.root = Rails.root / "../test/fixtures/app"
+    SnapDiff.config.add_os_path = true
+    SnapDiff.config.add_driver_path = true
+    SnapDiff.config.driver = ENV.fetch("SCREENSHOT_DRIVER", "chunky_png").to_sym
+    SnapDiff.config.tolerance = 0.5
   end
 
-  it "should include CapybaraScreenshotDiff in rspec" do
+  it "should include SnapDiff::DSL in rspec" do
     expect(self.class.ancestors).to include SnapDiff::DSL
   end
 
@@ -45,7 +45,7 @@
 
   it "marks the example pending when a new screenshot has no baseline and pending_if_new is enabled" do
     name = "pending-if-new-example"
-    allow(Capybara::Screenshot::Diff).to receive(:pending_if_new).and_return(true)
+    allow(SnapDiff.config).to receive(:pending_if_new).and_return(true)
     visit "/"
     screenshot name
   ensure