omg-actionpack 8.0.0.alpha1

data/lib/action_dispatch/system_test_case.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+gem "capybara", ">= 3.26"
+
+require "capybara/dsl"
+require "capybara/minitest"
+require "action_controller"
+require "action_dispatch/system_testing/driver"
+require "action_dispatch/system_testing/browser"
+require "action_dispatch/system_testing/server"
+require "action_dispatch/system_testing/test_helpers/screenshot_helper"
+require "action_dispatch/system_testing/test_helpers/setup_and_teardown"
+
+module ActionDispatch
+  # # 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.
+  #
+  # 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 your `application_system_test_case.rb` file
+  # that is generated with a new application or scaffold.
+  #
+  # Here is an example system test:
+  #
+  #     require "application_system_test_case"
+  #
+  #     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'
+  #
+  #         assert_text 'Arya'
+  #       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.
+  #
+  #     require "test_helper"
+  #
+  #     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.
+  #
+  # 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"
+  #
+  #     class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  #       driven_by :selenium, using: :firefox
+  #     end
+  #
+  # `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"
+  #
+  #     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.
+  #
+  # 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 `<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
+  #
+  # 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
+    include SystemTesting::TestHelpers::SetupAndTeardown
+    include SystemTesting::TestHelpers::ScreenshotHelper
+
+    DEFAULT_HOST = "http://127.0.0.1"
+
+    def initialize(*) # :nodoc:
+      super
+      self.class.driven_by(:selenium) unless self.class.driver?
+      self.class.driver.use
+    end
+
+    def self.start_application # :nodoc:
+      Capybara.app = Rack::Builder.new do
+        map "/" do
+          run Rails.application
+        end
+      end
+
+      SystemTesting::Server.new.run
+    end
+
+    class_attribute :driver, instance_accessor: false
+
+    # System Test configuration options
+    #
+    # The default settings are Selenium, using Chrome, with a screen size of
+    # 1400x1400.
+    #
+    # Examples:
+    #
+    #     driven_by :cuprite
+    #
+    #     driven_by :selenium, screen_size: [800, 800]
+    #
+    #     driven_by :selenium, using: :chrome
+    #
+    #     driven_by :selenium, using: :headless_chrome
+    #
+    #     driven_by :selenium, using: :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 ||=
+          if ActionDispatch.test_app
+            Class.new do
+              include ActionDispatch.test_app.routes.url_helpers
+              include ActionDispatch.test_app.routes.mounted_helpers
+
+              def url_options
+                default_url_options.reverse_merge(host: app_host)
+              end
+
+              def app_host
+                Capybara.app_host || Capybara.current_session.server_url || DEFAULT_HOST
+              end
+            end.new
+          end
+      end
+
+      def method_missing(name, ...)
+        if url_helpers.respond_to?(name)
+          url_helpers.public_send(name, ...)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        url_helpers.respond_to?(name)
+      end
+  end
+end
+
+ActiveSupport.run_load_hooks :action_dispatch_system_test_case, ActionDispatch::SystemTestCase
+ActionDispatch::SystemTestCase.start_application

data/lib/action_dispatch/system_testing/browser.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionDispatch
+  module SystemTesting
+    class Browser # :nodoc:
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def type
+        case name
+        when :headless_chrome
+          :chrome
+        when :headless_firefox
+          :firefox
+        else
+          name
+        end
+      end
+
+      def options
+        @options ||=
+          case type
+          when :chrome
+            default_chrome_options
+          when :firefox
+            default_firefox_options
+          end
+      end
+
+      def configure
+        yield options if block_given?
+      end
+
+      # driver_path is lazily initialized by default. Eagerly set it to avoid race
+      # conditions when using parallel tests.
+      def preload
+        case type
+        when :chrome
+          resolve_driver_path(::Selenium::WebDriver::Chrome)
+        when :firefox
+          resolve_driver_path(::Selenium::WebDriver::Firefox)
+        end
+      end
+
+      private
+        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 default_firefox_options
+          options = ::Selenium::WebDriver::Firefox::Options.new
+          options.add_argument("-headless") if name == :headless_firefox
+          options
+        end
+
+        def resolve_driver_path(namespace)
+          # The path method has been deprecated in 4.20.0
+          if Gem::Version.new(::Selenium::WebDriver::VERSION) >= Gem::Version.new("4.20.0")
+            namespace::Service.driver_path = ::Selenium::WebDriver::DriverFinder.new(options, namespace::Service.new).driver_path
+          else
+            namespace::Service.driver_path = ::Selenium::WebDriver::DriverFinder.path(options, namespace::Service)
+          end
+        end
+    end
+  end
+end

data/lib/action_dispatch/system_testing/driver.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionDispatch
+  module SystemTesting
+    class Driver # :nodoc:
+      attr_reader :name
+
+      def initialize(driver_type, **options, &capabilities)
+        @driver_type = driver_type
+        @screen_size = options[:screen_size]
+        @options = options[:options] || {}
+        @name = @options.delete(:name) || driver_type
+        @capabilities = capabilities
+
+        if driver_type == :selenium
+          gem "selenium-webdriver", ">= 4.0.0"
+          require "selenium/webdriver"
+          @browser = Browser.new(options[:using])
+          @browser.preload unless @options[:browser] == :remote
+        else
+          @browser = nil
+        end
+      end
+
+      def use
+        register if registerable?
+
+        setup
+      end
+
+      private
+        def registerable?
+          [:selenium, :cuprite, :rack_test, :playwright].include?(@driver_type)
+        end
+
+        def register
+          @browser&.configure(&@capabilities)
+
+          Capybara.register_driver name do |app|
+            case @driver_type
+            when :selenium then register_selenium(app)
+            when :cuprite then register_cuprite(app)
+            when :rack_test then register_rack_test(app)
+            when :playwright then register_playwright(app)
+            end
+          end
+        end
+
+        def browser_options
+          @options.merge(options: @browser.options).compact
+        end
+
+        def register_selenium(app)
+          Capybara::Selenium::Driver.new(app, browser: @browser.type, **browser_options).tap do |driver|
+            driver.browser.manage.window.size = Selenium::WebDriver::Dimension.new(*@screen_size)
+          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
+
+        def register_playwright(app)
+          screen = { width: @screen_size[0], height: @screen_size[1] } if @screen_size
+          options = {
+            screen: screen,
+            viewport: screen,
+            **@options
+          }.compact
+
+          Capybara::Playwright::Driver.new(app, **options)
+        end
+
+        def setup
+          Capybara.current_driver = name
+        end
+    end
+  end
+end

data/lib/action_dispatch/system_testing/server.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionDispatch
+  module SystemTesting
+    class Server # :nodoc:
+      class << self
+        attr_accessor :silence_puma
+      end
+
+      self.silence_puma = false
+
+      def run
+        setup
+      end
+
+      private
+        def setup
+          set_server
+          set_port
+        end
+
+        def set_server
+          Capybara.server = :puma, { Silent: self.class.silence_puma } if Capybara.server == Capybara.servers[:default]
+        end
+
+        def set_port
+          Capybara.always_include_port = true
+        end
+    end
+  end
+end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionDispatch
+  module SystemTesting
+    module TestHelpers
+      # Screenshot helper for system testing.
+      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)
+        #
+        # 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).
+        #
+        #     `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?
+
+          increment_unique
+          save_html if showing_html
+          save_image
+          show display_image(html: showing_html, screenshot_output: screenshot)
+        end
+
+        # Takes a screenshot of the current page in the browser if the test failed.
+        #
+        # `take_failed_screenshot` is called during system test teardown.
+        def take_failed_screenshot
+          return unless failed? && supports_screenshot? && Capybara::Session.instance_created?
+
+          take_screenshot
+          metadata[:failure_screenshot_path] = relative_image_path if Minitest::Runnable.method_defined?(:metadata)
+        end
+
+        private
+          attr_accessor :_screenshot_counter
+
+          def html_from_env?
+            ENV["RAILS_SYSTEM_TESTING_SCREENSHOT_HTML"] == "1"
+          end
+
+          def increment_unique
+            @_screenshot_counter ||= 0
+            @_screenshot_counter += 1
+          end
+
+          def unique
+            failed? ? "failures" : (_screenshot_counter || 0).to_s
+          end
+
+          def image_name
+            sanitized_method_name = method_name.gsub(/[^\w]+/, "-")
+            name = "#{unique}_#{sanitized_method_name}"
+            name[0...225]
+          end
+
+          def image_path
+            absolute_image_path.to_s
+          end
+
+          def html_path
+            absolute_html_path.to_s
+          end
+
+          def absolute_path
+            Rails.root.join(screenshots_dir, image_name)
+          end
+
+          def screenshots_dir
+            Capybara.save_path.presence || "tmp/screenshots"
+          end
+
+          def absolute_image_path
+            "#{absolute_path}.png"
+          end
+
+          def relative_image_path
+            "#{absolute_path.relative_path_from(Rails.root)}.png"
+          end
+
+          def absolute_html_path
+            "#{absolute_path}.html"
+          end
+
+          # rubocop:disable Lint/Debugger
+          def save_html
+            page.save_page(absolute_html_path)
+          end
+
+          def save_image
+            page.save_screenshot(absolute_image_path)
+          end
+          # rubocop:enable Lint/Debugger
+
+          def output_type
+            # Environment variables have priority
+            output_type = ENV["RAILS_SYSTEM_TESTING_SCREENSHOT"] || ENV["CAPYBARA_INLINE_SCREENSHOT"]
+
+            # Default to outputting a path to the screenshot
+            output_type ||= "simple"
+
+            output_type
+          end
+
+          def show(img)
+            puts img
+          end
+
+          def display_image(html:, screenshot_output:)
+            message = +"[Screenshot Image]: #{image_path}\n"
+            message << +"[Screenshot HTML]: #{html_path}\n" if html
+
+            case screenshot_output || output_type
+            when "artifact"
+              message << "\e]1338;url=artifact://#{absolute_image_path}\a\n"
+            when "inline"
+              name = inline_base64(File.basename(absolute_image_path))
+              image = inline_base64(File.read(absolute_image_path))
+              message << "\e]1337;File=name=#{name};height=400px;inline=1:#{image}\a\n"
+            end
+
+            message
+          end
+
+          def inline_base64(path)
+            Base64.strict_encode64(path)
+          end
+
+          def failed?
+            !passed? && !skipped?
+          end
+
+          def supports_screenshot?
+            Capybara.current_driver != :rack_test
+          end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionDispatch
+  module SystemTesting
+    module TestHelpers
+      module SetupAndTeardown # :nodoc:
+        def before_teardown
+          take_failed_screenshot
+        ensure
+          super
+        end
+
+        def after_teardown
+          Capybara.reset_sessions!
+        ensure
+          super
+        end
+      end
+    end
+  end
+end

data/lib/action_dispatch/testing/assertion_response.rb

@@ -0,0 +1,48 @@
+# 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.
+  class AssertionResponse
+    attr_reader :code, :name
+
+    GENERIC_RESPONSE_CODES = { # :nodoc:
+      success: "2XX",
+      missing: "404",
+      redirect: "3XX",
+      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).
+    def initialize(code_or_name)
+      if code_or_name.is_a?(Symbol)
+        @name = code_or_name
+        @code = code_from_name(code_or_name)
+      else
+        @name = name_from_code(code_or_name)
+        @code = code_or_name
+      end
+
+      raise ArgumentError, "Invalid response name: #{name}" if @code.nil?
+      raise ArgumentError, "Invalid response code: #{code}" if @name.nil?
+    end
+
+    def code_and_name
+      "#{code}: #{name}"
+    end
+
+    private
+      def code_from_name(name)
+        GENERIC_RESPONSE_CODES[name] || Rack::Utils.status_code(name)
+      end
+
+      def name_from_code(code)
+        GENERIC_RESPONSE_CODES.invert[code] || Rack::Utils::HTTP_STATUS_CODES[code]
+      end
+  end
+end