actionpack 7.1.5.1 → 8.1.2

data/lib/action_dispatch/system_test_case.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 gem "capybara", ">= 3.26"
 
 require "capybara/dsl"
@@ -12,103 +14,103 @@ require "action_dispatch/system_testing/test_helpers/screenshot_helper"
 require "action_dispatch/system_testing/test_helpers/setup_and_teardown"
 
 module ActionDispatch
-  # = System Testing
+  # # System Testing
   #
-  # System tests let you test applications in the browser. Because system
-  # tests use a real browser experience, you can test all of your JavaScript
-  # easily from your test suite.
+  # System tests let you test applications in the browser. Because system tests
+  # use a real browser experience, you can test all of your JavaScript easily from
+  # your test suite.
   #
-  # To create a system test in your application, extend your test class
-  # from <tt>ApplicationSystemTestCase</tt>. System tests use Capybara as a
-  # base and allow you to configure the settings through your
-  # <tt>application_system_test_case.rb</tt> file that is generated with a new
-  # application or scaffold.
+  # To create a system test in your application, extend your test class from
+  # `ApplicationSystemTestCase`. System tests use Capybara as a base and allow you
+  # to configure the settings through the `application_system_test_case.rb` file,
+  # which is created when you generate your first system test.
   #
   # Here is an example system test:
   #
-  #   require "application_system_test_case"
+  #     require "application_system_test_case"
   #
-  #   class Users::CreateTest < ApplicationSystemTestCase
-  #     test "adding a new user" do
-  #       visit users_path
-  #       click_on 'New User'
+  #     class Users::CreateTest < ApplicationSystemTestCase
+  #       test "adding a new user" do
+  #         visit users_path
+  #         click_on 'New User'
   #
-  #       fill_in 'Name', with: 'Arya'
-  #       click_on 'Create User'
+  #         fill_in 'Name', with: 'Arya'
+  #         click_on 'Create User'
   #
-  #       assert_text 'Arya'
+  #         assert_text 'Arya'
+  #       end
   #     end
-  #   end
   #
-  # When generating an application or scaffold, an +application_system_test_case.rb+
-  # file will also be generated containing the base class for system testing.
-  # This is where you can change the driver, add Capybara settings, and other
-  # configuration for your system tests.
+  # When generating system tests, an
+  # `application_system_test_case.rb` file will also be generated containing the
+  # base class for system testing. This is where you can change the driver, add
+  # Capybara settings, and other configuration for your system tests.
   #
-  #   require "test_helper"
+  #     require "test_helper"
   #
-  #   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  #     driven_by :selenium, using: :chrome, screen_size: [1400, 1400]
-  #   end
+  #     class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  #       driven_by :selenium, using: :chrome, screen_size: [1400, 1400]
+  #     end
   #
-  # By default, +ActionDispatch::SystemTestCase+ is driven by the
-  # Selenium driver, with the Chrome browser, and a browser size of 1400x1400.
+  # By default, `ActionDispatch::SystemTestCase` is driven by the Selenium driver,
+  # with the Chrome browser, and a browser size of 1400x1400.
   #
   # Changing the driver configuration options is easy. Let's say you want to use
-  # the Firefox browser instead of Chrome. In your +application_system_test_case.rb+
-  # file add the following:
-  #
-  #   require "test_helper"
+  # the Firefox browser instead of Chrome. In your
+  # `application_system_test_case.rb` file add the following:
   #
-  #   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  #     driven_by :selenium, using: :firefox
-  #   end
+  #     require "test_helper"
   #
-  # +driven_by+ has a required argument for the driver name. The keyword
-  # arguments are +:using+ for the browser and +:screen_size+ to change the
-  # size of the browser screen. These two options are not applicable for
-  # headless drivers and will be silently ignored if passed.
-  #
-  # 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+.
+  #     class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  #       driven_by :selenium, using: :firefox
+  #     end
   #
-  # To use a headless driver, like Cuprite, update your Gemfile to use
-  # 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
-  # +:options+ to pass options supported by the driver. Please refer to your
+  # `driven_by` has a required argument for the driver name. The keyword arguments
+  # are `:using` for the browser and `:screen_size` to change the size of the
+  # browser screen. These two options are not applicable for headless drivers and
+  # will be silently ignored if passed.
+  #
+  # 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 Cuprite, update your Gemfile to use 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
+  # `:options` to pass options supported by the driver. Please refer to your
   # driver documentation to learn about supported options.
   #
-  #   require "test_helper"
-  #   require "capybara/cuprite"
+  #     require "test_helper"
+  #     require "capybara/cuprite"
   #
-  #   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  #     driven_by :cuprite, screen_size: [1400, 1400], options:
-  #       { js_errors: true }
-  #   end
+  #     class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  #       driven_by :cuprite, screen_size: [1400, 1400], options:
+  #         { js_errors: true }
+  #     end
   #
-  # Some drivers require browser capabilities to be passed as a block instead
-  # of through the +options+ hash.
+  # Some drivers require browser capabilities to be passed as a block instead of
+  # through the `options` hash.
   #
   # As an example, if you want to add mobile emulation on chrome, you'll have to
-  # create an instance of selenium's +Chrome::Options+ object and add
-  # capabilities with a block.
-  #
-  # The block will be passed an instance of <tt><Driver>::Options</tt> where you can
-  # define the capabilities you want. Please refer to your driver documentation
-  # to learn about supported options.
-  #
-  #   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  #     driven_by :selenium, using: :chrome, screen_size: [1024, 768] do |driver_option|
-  #       driver_option.add_emulation(device_name: 'iPhone 6')
-  #       driver_option.add_extension('path/to/chrome_extension.crx')
+  # create an instance of selenium's `Chrome::Options` object and add capabilities
+  # with a block.
+  #
+  # The block will be passed an instance of `<Driver>::Options` where you can
+  # define the capabilities you want. Please refer to your driver documentation to
+  # learn about supported options.
+  #
+  #     class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  #       driven_by :selenium, using: :chrome, screen_size: [1024, 768] do |driver_option|
+  #         driver_option.add_emulation(device_name: 'iPhone 6')
+  #         driver_option.add_extension('path/to/chrome_extension.crx')
+  #       end
   #     end
-  #   end
   #
-  # Because +ActionDispatch::SystemTestCase+ is a shim between Capybara
-  # and \Rails, any driver that is supported by Capybara is supported by system
-  # tests as long as you include the required gems and files.
+  # Because `ActionDispatch::SystemTestCase` is a shim between Capybara and Rails,
+  # any driver that is supported by Capybara is supported by system tests as long
+  # as you include the required gems and files.
   class SystemTestCase < ActiveSupport::TestCase
     include Capybara::DSL
     include Capybara::Minitest::Assertions
@@ -137,28 +139,36 @@ module ActionDispatch
 
     # System Test configuration options
     #
-    # The default settings are Selenium, using Chrome, with a screen size
-    # of 1400x1400.
+    # The default settings are Selenium, using Chrome, with a screen size of
+    # 1400x1400.
     #
     # Examples:
     #
-    #   driven_by :cuprite
+    #     driven_by :cuprite
     #
-    #   driven_by :selenium, screen_size: [800, 800]
+    #     driven_by :selenium, screen_size: [800, 800]
     #
-    #   driven_by :selenium, using: :chrome
+    #     driven_by :selenium, using: :chrome
     #
-    #   driven_by :selenium, using: :headless_chrome
+    #     driven_by :selenium, using: :headless_chrome
     #
-    #   driven_by :selenium, using: :firefox
+    #     driven_by :selenium, using: :firefox
     #
-    #   driven_by :selenium, using: :headless_firefox
+    #     driven_by :selenium, using: :headless_firefox
     def self.driven_by(driver, using: :chrome, screen_size: [1400, 1400], options: {}, &capabilities)
       driver_options = { using: using, screen_size: screen_size, options: options }
 
       self.driver = SystemTesting::Driver.new(driver, **driver_options, &capabilities)
     end
 
+    # Configuration for the System Test application server.
+    #
+    # By default this is localhost. This method allows the host and port to be specified manually.
+    def self.served_by(host:, port:)
+      Capybara.server_host = host
+      Capybara.server_port = port
+    end
+
     private
       def url_helpers
         @url_helpers ||=
@@ -178,9 +188,9 @@ module ActionDispatch
           end
       end
 
-      def method_missing(name, *args, &block)
+      def method_missing(name, ...)
         if url_helpers.respond_to?(name)
-          url_helpers.public_send(name, *args, &block)
+          url_helpers.public_send(name, ...)
         else
           super
         end

data/lib/action_dispatch/system_testing/browser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module SystemTesting
     class Browser # :nodoc:
@@ -7,7 +9,6 @@ module ActionDispatch
 
       def initialize(name)
         @name = name
-        set_default_options
       end
 
       def type
@@ -25,9 +26,9 @@ module ActionDispatch
         @options ||=
           case type
           when :chrome
-            ::Selenium::WebDriver::Chrome::Options.new
+            default_chrome_options
           when :firefox
-            ::Selenium::WebDriver::Firefox::Options.new
+            default_firefox_options
           end
       end
 
@@ -35,8 +36,8 @@ module ActionDispatch
         yield options if block_given?
       end
 
-      # driver_path is lazily initialized by default. Eagerly set it to
-      # avoid race conditions when using parallel tests.
+      # driver_path is lazily initialized by default. Eagerly set it to avoid race
+      # conditions when using parallel tests.
       def preload
         case type
         when :chrome
@@ -47,26 +48,18 @@ module ActionDispatch
       end
 
       private
-        def set_default_options
-          case name
-          when :headless_chrome
-            set_headless_chrome_browser_options
-          when :headless_firefox
-            set_headless_firefox_browser_options
-          end
-        end
-
-        def set_headless_chrome_browser_options
-          configure do |capabilities|
-            capabilities.add_argument("--headless")
-            capabilities.add_argument("--disable-gpu") if Gem.win_platform?
-          end
+        def default_chrome_options
+          options = ::Selenium::WebDriver::Chrome::Options.new
+          options.add_argument("--disable-search-engine-choice-screen")
+          options.add_argument("--headless") if name == :headless_chrome
+          options.add_argument("--disable-gpu") if Gem.win_platform?
+          options
         end
 
-        def set_headless_firefox_browser_options
-          configure do |capabilities|
-            capabilities.add_argument("-headless")
-          end
+        def default_firefox_options
+          options = ::Selenium::WebDriver::Firefox::Options.new
+          options.add_argument("-headless") if name == :headless_firefox
+          options
         end
 
         def resolve_driver_path(namespace)

data/lib/action_dispatch/system_testing/driver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module SystemTesting
     class Driver # :nodoc:

data/lib/action_dispatch/system_testing/server.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module SystemTesting
     class Server # :nodoc:

data/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module SystemTesting
     module TestHelpers
@@ -7,27 +9,35 @@ module ActionDispatch
       module ScreenshotHelper
         # Takes a screenshot of the current page in the browser.
         #
-        # +take_screenshot+ can be used at any point in your system tests to take
-        # a screenshot of the current state. This can be useful for debugging or
-        # automating visual testing. You can take multiple screenshots per test
-        # to investigate changes at different points during your test. These will be
-        # named with a sequential prefix (or 'failed' for failing tests)
+        # `take_screenshot` can be used at any point in your system tests to take a
+        # screenshot of the current state. This can be useful for debugging or
+        # automating visual testing. You can take multiple screenshots per test to
+        # investigate changes at different points during your test. These will be named
+        # with a sequential prefix (or 'failed' for failing tests)
+        #
+        # The default screenshots directory is `tmp/screenshots` but you can set a
+        # different one with `Capybara.save_path`
+        #
+        # You can use the `html` argument or set the
+        # `RAILS_SYSTEM_TESTING_SCREENSHOT_HTML` environment variable to save the HTML
+        # from the page that is being screenshotted so you can investigate the elements
+        # on the page at the time of the screenshot
+        #
+        # You can use the `screenshot` argument or set the
+        # `RAILS_SYSTEM_TESTING_SCREENSHOT` environment variable to control the output.
+        # Possible values are:
+        #     `simple` (default)
+        # :       Only displays the screenshot path. This is the default value.
+        #
+        #     `inline`
+        # :       Display the screenshot in the terminal using the iTerm image protocol
+        #         (https://iterm2.com/documentation-images.html).
         #
-        # The default screenshots directory is +tmp/screenshots+ but you can set a different
-        # one with +Capybara.save_path+
+        #     `artifact`
+        # :       Display the screenshot in the terminal, using the terminal artifact
+        #         format (https://buildkite.github.io/terminal-to-html/inline-images/).
         #
-        # You can use the +html+ argument or set the +RAILS_SYSTEM_TESTING_SCREENSHOT_HTML+
-        # environment variable to save the HTML from the page that is being screenshotted
-        # so you can investigate the elements on the page at the time of the screenshot
         #
-        # You can use the +screenshot+ argument or set the +RAILS_SYSTEM_TESTING_SCREENSHOT+
-        # environment variable to control the output. Possible values are:
-        # * [+simple+ (default)]    Only displays the screenshot path.
-        #                           This is the default value.
-        # * [+inline+]              Display the screenshot in the terminal using the
-        #                           iTerm image protocol (https://iterm2.com/documentation-images.html).
-        # * [+artifact+]            Display the screenshot in the terminal, using the terminal
-        #                           artifact format (https://buildkite.github.io/terminal-to-html/inline-images/).
         def take_screenshot(html: false, screenshot: nil)
           showing_html = html || html_from_env?
 
@@ -37,10 +47,9 @@ module ActionDispatch
           show display_image(html: showing_html, screenshot_output: screenshot)
         end
 
-        # Takes a screenshot of the current page in the browser if the test
-        # failed.
+        # Takes a screenshot of the current page in the browser if the test failed.
         #
-        # +take_failed_screenshot+ is called during system test teardown.
+        # `take_failed_screenshot` is called during system test teardown.
         def take_failed_screenshot
           return unless failed? && supports_screenshot? && Capybara::Session.instance_created?
 
@@ -98,6 +107,7 @@ module ActionDispatch
             "#{absolute_path}.html"
           end
 
+          # rubocop:disable Lint/Debugger
           def save_html
             page.save_page(absolute_html_path)
           end
@@ -105,6 +115,7 @@ module ActionDispatch
           def save_image
             page.save_screenshot(absolute_image_path)
           end
+          # rubocop:enable Lint/Debugger
 
           def output_type
             # Environment variables have priority
@@ -121,8 +132,8 @@ module ActionDispatch
           end
 
           def display_image(html:, screenshot_output:)
-            message = +"[Screenshot Image]: #{image_path}\n"
-            message << +"[Screenshot HTML]: #{html_path}\n" if html
+            message = +"[Screenshot Image]: #{image_path} \n"
+            message << +"[Screenshot HTML]: #{html_path} \n" if html
 
             case screenshot_output || output_type
             when "artifact"

data/lib/action_dispatch/system_testing/test_helpers/setup_and_teardown.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module SystemTesting
     module TestHelpers

data/lib/action_dispatch/testing/assertion_response.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
-  # This is a class that abstracts away an asserted response. It purposely
-  # does not inherit from Response because it doesn't need it. That means it
-  # does not have headers or a body.
+  # This is a class that abstracts away an asserted response. It purposely does
+  # not inherit from Response because it doesn't need it. That means it does not
+  # have headers or a body.
   class AssertionResponse
     attr_reader :code, :name
 
@@ -14,9 +16,9 @@ module ActionDispatch
       error: "5XX"
     }
 
-    # Accepts a specific response status code as an Integer (404) or String
-    # ('404') or a response status range as a Symbol pseudo-code (:success,
-    # indicating any 200-299 status code).
+    # Accepts a specific response status code as an Integer (404) or String ('404')
+    # or a response status range as a Symbol pseudo-code (:success, indicating any
+    # 200-299 status code).
     def initialize(code_or_name)
       if code_or_name.is_a?(Symbol)
         @name = code_or_name
@@ -36,7 +38,7 @@ module ActionDispatch
 
     private
       def code_from_name(name)
-        GENERIC_RESPONSE_CODES[name] || Rack::Utils.status_code(name)
+        GENERIC_RESPONSE_CODES[name] || ActionDispatch::Response.rack_status_code(name)
       end
 
       def name_from_code(code)

data/lib/action_dispatch/testing/assertions/response.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module Assertions
-    # A small suite of assertions that test responses from \Rails applications.
+    # A small suite of assertions that test responses from Rails applications.
     module ResponseAssertions
       RESPONSE_PREDICATES = { # :nodoc:
         success:  :successful?,
@@ -13,20 +15,21 @@ module ActionDispatch
 
       # Asserts that the response is one of the following types:
       #
-      # * <tt>:success</tt>   - Status code was in the 200-299 range
-      # * <tt>:redirect</tt>  - Status code was in the 300-399 range
-      # * <tt>:missing</tt>   - Status code was 404
-      # * <tt>:error</tt>     - Status code was in the 500-599 range
+      # *   `:success`   - Status code was in the 200-299 range
+      # *   `:redirect`  - Status code was in the 300-399 range
+      # *   `:missing`   - Status code was 404
+      # *   `:error`     - Status code was in the 500-599 range
+      #
       #
-      # You can also pass an explicit status number like <tt>assert_response(501)</tt>
-      # or its symbolic equivalent <tt>assert_response(:not_implemented)</tt>.
-      # See +Rack::Utils::SYMBOL_TO_STATUS_CODE+ for a full list.
+      # You can also pass an explicit status number like `assert_response(501)` or its
+      # symbolic equivalent `assert_response(:not_implemented)`. See
+      # `Rack::Utils::SYMBOL_TO_STATUS_CODE` for a full list.
       #
-      #   # Asserts that the response was a redirection
-      #   assert_response :redirect
+      #     # Asserts that the response was a redirection
+      #     assert_response :redirect
       #
-      #   # Asserts that the response code was status code 401 (unauthorized)
-      #   assert_response 401
+      #     # Asserts that the response code was status code 401 (unauthorized)
+      #     assert_response 401
       def assert_response(type, message = nil)
         message ||= generate_response_message(type)
 
@@ -39,21 +42,21 @@ module ActionDispatch
 
       # Asserts that the response is a redirect to a URL matching the given options.
       #
-      #   # Asserts that the redirection was to the "index" action on the WeblogController
-      #   assert_redirected_to controller: "weblog", action: "index"
+      #     # Asserts that the redirection was to the "index" action on the WeblogController
+      #     assert_redirected_to controller: "weblog", action: "index"
       #
-      #   # Asserts that the redirection was to the named route login_url
-      #   assert_redirected_to login_url
+      #     # Asserts that the redirection was to the named route login_url
+      #     assert_redirected_to login_url
       #
-      #   # Asserts that the redirection was to the URL for @customer
-      #   assert_redirected_to @customer
+      #     # Asserts that the redirection was to the URL for @customer
+      #     assert_redirected_to @customer
       #
-      #   # Asserts that the redirection matches the regular expression
-      #   assert_redirected_to %r(\Ahttp://example.org)
+      #     # Asserts that the redirection matches the regular expression
+      #     assert_redirected_to %r(\Ahttp://example.org)
       #
-      #   # Asserts that the redirection has the HTTP status code 301 (Moved
-      #   # Permanently).
-      #   assert_redirected_to "/some/path", status: :moved_permanently
+      #     # Asserts that the redirection has the HTTP status code 301 (Moved
+      #     # Permanently).
+      #     assert_redirected_to "/some/path", status: :moved_permanently
       def assert_redirected_to(url_options = {}, options = {}, message = nil)
         options, message = {}, options unless options.is_a?(Hash)
 
@@ -68,6 +71,20 @@ module ActionDispatch
         assert_operator redirect_expected, :===, redirect_is, message
       end
 
+      # Asserts that the given +text+ is present somewhere in the response body.
+      #
+      #     assert_in_body fixture(:name).description
+      def assert_in_body(text)
+        assert_match(/#{Regexp.escape(text)}/, @response.body)
+      end
+
+      # Asserts that the given +text+ is not present anywhere in the response body.
+      #
+      #     assert_not_in_body fixture(:name).description
+      def assert_not_in_body(text)
+        assert_no_match(/#{Regexp.escape(text)}/, @response.body)
+      end
+
       private
         # Proxy to to_param if the object will respond to it.
         def parameterize(value)
@@ -84,8 +101,13 @@ module ActionDispatch
         end
 
         def generate_response_message(expected, actual = @response.response_code)
-          (+"Expected response to be a <#{code_with_name(expected)}>,"\
-          " but was a <#{code_with_name(actual)}>").concat(location_if_redirected).concat(response_body_if_short)
+          lambda do
+            (+"Expected response to be a <#{code_with_name(expected)}>,"\
+             " but was a <#{code_with_name(actual)}>").
+              concat(location_if_redirected).
+              concat(exception_if_present).
+              concat(response_body_if_short)
+          end
         end
 
         def response_body_if_short
@@ -93,6 +115,11 @@ module ActionDispatch
           "\nResponse body: #{@response.body}"
         end
 
+        def exception_if_present
+          return "" unless ex = @request&.env&.[]("action_dispatch.exception")
+          "\n\nException while processing request: #{Minitest::UnexpectedError.new(ex).message}\n"
+        end
+
         def location_if_redirected
           return "" unless @response.redirection? && @response.location.present?
           location = normalize_argument_to_redirection(@response.location)