Merge pull request #42790 from YusukeIwaki/replace_poltergeist_with_cuprite

Deprecate `poltergeist` and `webkit` driver registration. Add `cuprite`.

actionpack/CHANGELOG.md

@@ -1,3 +1,11 @@
+*   Deprecate `poltergeist` and `webkit` (capybara-webkit) driver registration for system testing (they will be removed in Rails 7.1). Add `cuprite` instead.
+
+    [Poltergeist](https://github.com/teampoltergeist/poltergeist) and [capybara-webkit](https://github.com/thoughtbot/capybara-webkit) are already not maintained. These usage in Rails are removed for avoiding confusing users.
+
+    [Cuprite](https://github.com/rubycdp/cuprite) is a good alternative to Poltergeist. Some guide descriptions are replaced from Poltergeist to Cuprite.
+
+    *Yusuke Iwaki*
+
 *   Add `Middleware#remove` to delete middleware or raise if not found.
 
     `Middleware#remove` works just like `Middleware#delete` but will

actionpack/lib/action_dispatch/system_test_case.rb

@@ -72,8 +72,8 @@ module ActionDispatch
   # Headless browsers such as headless Chrome and headless Firefox are also supported.
   # You can use these browsers by setting the +:using+ argument to +:headless_chrome+ or +:headless_firefox+.
   #
-  # To use a headless driver, like Poltergeist, update your Gemfile to use
+  # To use a headless driver, like Cuprite, update your Gemfile to use
-  # Poltergeist instead of Selenium and then declare the driver name in the
+  # Cuprite instead of Selenium and then declare the driver name in the
   # +application_system_test_case.rb+ file. In this case, you would leave out
   # the +:using+ option because the driver is headless, but you can still use
   # +:screen_size+ to change the size of the browser screen, also you can use
@@ -81,10 +81,10 @@ module ActionDispatch
   # driver documentation to learn about supported options.
   #
   #   require "test_helper"
-  #   require "capybara/poltergeist"
+  #   require "capybara/cuprite"
   #
   #   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  #     driven_by :poltergeist, screen_size: [1400, 1400], options:
+  #     driven_by :cuprite, screen_size: [1400, 1400], options:
   #       { js_errors: true }
   #   end
   #
@@ -140,7 +140,7 @@ module ActionDispatch
     #
     # Examples:
     #
-    #   driven_by :poltergeist
+    #   driven_by :cuprite
     #
     #   driven_by :selenium, screen_size: [800, 800]
     #

actionpack/lib/action_dispatch/system_testing/driver.rb

@@ -9,6 +9,14 @@ module ActionDispatch
         @options = options[:options] || {}
         @capabilities = capabilities
 
+        if [:poltergeist, :webkit].include?(name)
+          ActiveSupport::Deprecation.warn <<~MSG.squish
+            Poltergeist and capybara-webkit are not maintained already.
+            Driver registration of :poltergeist or :webkit is deprecated and will be removed in Rails 7.1.
+            You can still use :selenium, and also :cuprite is available for alternative to Poltergeist.
+          MSG
+        end
+
         if name == :selenium
           require "selenium/webdriver"
           @browser = Browser.new(options[:using])
@@ -26,7 +34,7 @@ module ActionDispatch
 
       private
         def registerable?
-          [:selenium, :poltergeist, :webkit, :rack_test].include?(@name)
+          [:selenium, :poltergeist, :webkit, :cuprite, :rack_test].include?(@name)
         end
 
         def register
@@ -37,6 +45,7 @@ module ActionDispatch
             when :selenium then register_selenium(app)
             when :poltergeist then register_poltergeist(app)
             when :webkit then register_webkit(app)
+            when :cuprite then register_cuprite(app)
             when :rack_test then register_rack_test(app)
             end
           end
@@ -62,6 +71,10 @@ module ActionDispatch
           end
         end
 
+        def register_cuprite(app)
+          Capybara::Cuprite::Driver.new(app, @options.merge(window_size: @screen_size))
+        end
+
         def register_rack_test(app)
           Capybara::RackTest::Driver.new(app, respect_data_method: true, **@options)
         end

actionpack/test/dispatch/system_testing/driver_test.rb

@@ -38,19 +38,30 @@ class DriverTest < ActiveSupport::TestCase
   end
 
   test "initializing the driver with a poltergeist" do
-    driver = ActionDispatch::SystemTesting::Driver.new(:poltergeist, screen_size: [1400, 1400], options: { js_errors: false })
+    driver = assert_deprecated do
+      ActionDispatch::SystemTesting::Driver.new(:poltergeist, screen_size: [1400, 1400], options: { js_errors: false })
+    end
     assert_equal :poltergeist, driver.instance_variable_get(:@name)
     assert_equal [1400, 1400], driver.instance_variable_get(:@screen_size)
     assert_equal ({ js_errors: false }), driver.instance_variable_get(:@options)
   end
 
   test "initializing the driver with a webkit" do
-    driver = ActionDispatch::SystemTesting::Driver.new(:webkit, screen_size: [1400, 1400], options: { skip_image_loading: true })
+    driver = assert_deprecated do
+      ActionDispatch::SystemTesting::Driver.new(:webkit, screen_size: [1400, 1400], options: { skip_image_loading: true })
+    end
     assert_equal :webkit, driver.instance_variable_get(:@name)
     assert_equal [1400, 1400], driver.instance_variable_get(:@screen_size)
     assert_equal ({ skip_image_loading: true }), driver.instance_variable_get(:@options)
   end
 
+  test "initializing the driver with a cuprite" do
+    driver = ActionDispatch::SystemTesting::Driver.new(:cuprite, screen_size: [1400, 1400], options: { js_errors: false })
+    assert_equal :cuprite, driver.instance_variable_get(:@name)
+    assert_equal [1400, 1400], driver.instance_variable_get(:@screen_size)
+    assert_equal ({ js_errors: false }), driver.instance_variable_get(:@options)
+  end
+
   test "define extra capabilities using chrome" do
     driver = ActionDispatch::SystemTesting::Driver.new(:selenium, screen_size: [1400, 1400], using: :chrome) do |option|
       option.add_argument("start-maximized")
@@ -153,6 +164,6 @@ class DriverTest < ActiveSupport::TestCase
     assert ActionDispatch::SystemTesting::Driver.new(:selenium).instance_variable_get(:@browser)
 
     assert_nil ActionDispatch::SystemTesting::Driver.new(:rack_test).instance_variable_get(:@browser)
-    assert_nil ActionDispatch::SystemTesting::Driver.new(:poltergeist).instance_variable_get(:@browser)
+    assert_nil ActionDispatch::SystemTesting::Driver.new(:cuprite).instance_variable_get(:@browser)
   end
 end

guides/source/testing.md

@@ -825,15 +825,15 @@ system tests should live.
 
 If you want to change the default settings you can change what the system
 tests are "driven by". Say you want to change the driver from Selenium to
-Poltergeist. First add the `poltergeist` gem to your `Gemfile`. Then in your
+Cuprite. First add the `cuprite` gem to your `Gemfile`. Then in your
 `application_system_test_case.rb` file do the following:
 
 ```ruby
 require "test_helper"
-require "capybara/poltergeist"
+require "capybara/cuprite"
 
 class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  driven_by :poltergeist
+  driven_by :cuprite
 end
 ```