Add option to rspec:install generator to configure for Selenium in Docker #2878

Changelog.md

@@ -1,6 +1,11 @@
 ### Development
 [Full Changelog](https://github.com/rspec/rspec-rails/compare/v8.0.3...main)
 
+Enhancements:
+
+* Add `--selenium-container` option to `rspec:install` generator for Docker/devcontainer
+  Selenium configuration in system specs. (#2878)
+
 ### 8.0.3 / 2026-02-17
 [Full Changelog](https://github.com/rspec/rspec-rails/compare/v8.0.2...v8.0.3)
 

lib/generators/rspec/install/install_generator.rb

@@ -13,6 +13,8 @@ class InstallGenerator < ::Rails::Generators::Base
 DESC
 
       class_option :default_path, type: :string, default: 'spec'
+      class_option :selenium_container, type: :string, default: nil,
+                   desc: "Configure system specs for a Selenium container (provide container hostname, e.g. 'selenium')"
 
       def self.source_root
         @source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
@@ -30,8 +32,19 @@ def copy_rails_files
         template 'spec/rails_helper.rb', "#{default_path}/rails_helper.rb"
       end
 
+      def copy_system_test_configuration
+        return unless options[:selenium_container]
+
+        template 'spec/support/system_test_configuration.rb',
+                 "#{default_path}/support/system_test_configuration.rb"
+      end
+
     private
 
+      def selenium_container
+        options[:selenium_container]
+      end
+
       def generate_rspec_init(tmpdir)
         initializer = ::RSpec::Core::ProjectInitializer.new(
           destination: tmpdir,

lib/generators/rspec/install/templates/spec/support/system_test_configuration.rb

@@ -0,0 +1,20 @@
+# System test configuration for Selenium container support.
+# Generated by `rails generate rspec:install --selenium-container=<%= selenium_container %>`.
+#
+# Ensure this file is required in your rails_helper.rb by uncommenting:
+#   Rails.root.glob('spec/support/**/*.rb').sort_by(&:to_s).each { |f| require f }
+
+RSpec.configure do |config|
+  config.before(type: :system) do
+    if ENV["CAPYBARA_SERVER_PORT"]
+      served_by host: "rails-app", port: ENV["CAPYBARA_SERVER_PORT"]
+
+      driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400], options: {
+        browser: :remote,
+        url: "http://#{ENV.fetch("SELENIUM_HOST", "<%= selenium_container %>")}:4444"
+      }
+    else
+      driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400]
+    end
+  end
+end

spec/generators/rspec/install/install_generator_spec.rb

@@ -1,4 +1,5 @@
 # Generators are not automatically loaded by Rails
+require 'erb'
 require 'generators/rspec/install/install_generator'
 require 'support/generators'
 
@@ -107,6 +108,37 @@ def filter_rails_from_backtrace
     end
   end
 
+  context "with --selenium-container option" do
+    let(:container_name) { "selenium" }
+    let(:system_test_config) { content_for('spec/support/system_test_configuration.rb') }
+
+    before { run_generator ["--selenium-container=#{container_name}"] }
+
+    it "generates spec/support/system_test_configuration.rb matching the template" do
+      template_path = File.expand_path(
+        "../../../../lib/generators/rspec/install/templates/spec/support/system_test_configuration.rb",
+        __dir__
+      )
+      expected = ERB.new(File.read(template_path)).result_with_hash(selenium_container: container_name)
+      expect(system_test_config).to eq(expected)
+    end
+
+    context "with a custom container name" do
+      let(:container_name) { "chrome" }
+
+      it "uses the custom container name in the configuration" do
+        expect(system_test_config).to include(container_name)
+      end
+    end
+  end
+
+  context "without --selenium-container option" do
+    it "does not generate spec/support/system_test_configuration.rb" do
+      run_generator
+      expect(File.exist?(file('spec/support/system_test_configuration.rb'))).to be false
+    end
+  end
+
   context "generates spec/rails_helper.rb", "without ActiveRecord available" do
     before do
       hide_const("ActiveRecord")