fix: skip at_exit when framework adapter handles finalization

README.md

@@ -194,9 +194,20 @@ Comparisons add ~50ms per image with VIPS. Without `ruby-vips`, ChunkyPNG is use
 `DEBUG=1 bundle exec rake test` keeps `.diff.png` files for inspection.
 </details>
 
+## Custom Test Frameworks
+
+Minitest, RSpec, and Cucumber are supported out of the box. For other frameworks, call `finalize_reporters!` after all tests complete:
+
+```ruby
+# In your framework's "after suite" hook:
+CapybaraScreenshotDiff.finalize_reporters!
+```
+
+This generates the HTML report and prints the summary. Without this call, the gem falls back to `at_exit` which may fire before your tests finish.
+
 ## Installation
 
-**Requirements:** Ruby 3.2+. Rails 7.1+ for Rails integration; non-Rails projects supported via `CapybaraScreenshotDiff.serve()`. For the `:vips` driver: [libvips 8.9+](https://libvips.github.io/libvips/install.html).
+**Requirements:** Ruby 3.2+. Rails 7.1+ for Rails integration; non-Rails projects supported via `CapybaraScreenshotDiff.serve()`. For the `:vips` driver: [libvips 8.9+](https://libvips.github.io/libvips/install.html). On macOS: `brew install vips`. On Ubuntu: `apt-get install libvips-dev`.
 
 ## Docs
 

lib/capybara_screenshot_diff/cucumber.rb

@@ -9,4 +9,5 @@
   Capybara::Screenshot::BrowserHelpers.resize_window_if_needed
 end
 
+CapybaraScreenshotDiff.external_at_exit = true
 AfterAll { CapybaraScreenshotDiff.finalize_reporters! }

lib/capybara_screenshot_diff/minitest.rb

@@ -48,4 +48,7 @@ def before_teardown
   end
 end
 
-::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)
+if ::Minitest.respond_to?(:after_run)
+  CapybaraScreenshotDiff.external_at_exit = true
+  ::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! }
+end

lib/capybara_screenshot_diff/reporters/html.rb

@@ -136,6 +136,10 @@ def write_report
   CapybaraScreenshotDiff.reporters << CapybaraScreenshotDiff::Reporters::HTML.new(embed_images: !!ENV["CI"])
 end
 
-# Fallback for frameworks without explicit integration (e.g., Cucumber).
-# Minitest and RSpec adapters call finalize_reporters! via their native hooks.
-at_exit { CapybaraScreenshotDiff.finalize_reporters! }
+# Register at_exit as fallback for frameworks without explicit adapters.
+# Framework adapters (Minitest, RSpec, Cucumber) set external_at_exit = true
+# and call finalize_reporters! via native hooks for correct ordering.
+at_exit do
+  next if CapybaraScreenshotDiff.external_at_exit?
+  CapybaraScreenshotDiff.finalize_reporters!
+end

lib/capybara_screenshot_diff/rspec.rb

@@ -42,5 +42,6 @@
     end
   end
 
+  CapybaraScreenshotDiff.external_at_exit = true
   config.after(:suite) { CapybaraScreenshotDiff.finalize_reporters! }
 end

lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -130,6 +130,8 @@ def reporters
     end
 
     attr_reader :reporters_mutex
+    attr_accessor :external_at_exit
+    alias_method :external_at_exit?, :external_at_exit
 
     def finalize_reporters!
       reporters_mutex.synchronize { reporters.dup }.each do |reporter|