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

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