3 files changed, 40 insertions, 10 deletions
diff --git a/actionpack/lib/action_dispatch/system_test_case.rb b/actionpack/lib/action_dispatch/system_test_case.rb
index c74c0ccced..644c703dc9 100644
--- a/actionpack/lib/action_dispatch/system_test_case.rb
+++ b/actionpack/lib/action_dispatch/system_test_case.rb
@@ -89,6 +89,20 @@ module ActionDispatch
   #       { js_errors: true }
   #   end
   #
+  # Most drivers won't let you add specific browser capabilities through the +options+ mentioned above.
+  # 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 to it.
+  # To make things easier, `driven_by` can be called 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 :chrome, screen_size: [1024, 768] do |driver_option|
+  #     driver_option.add_emulation(device: 'iPhone 6')
+  #     driver_option.add_extension('path/to/chrome_extension.crx')
+  #   end
+  # end
+  #
   # Because <tt>ActionDispatch::SystemTestCase</tt> 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.
@@ -134,8 +148,10 @@ module ActionDispatch
     #   driven_by :selenium, using: :firefox
     #
     #   driven_by :selenium, using: :headless_firefox
-    def self.driven_by(driver, using: :chrome, screen_size: [1400, 1400], options: {})
-      self.driver = SystemTesting::Driver.new(driver, using: using, screen_size: screen_size, options: options)
+    def self.driven_by(driver, using: :chrome, screen_size: [1400, 1400], options: {}, &desired_capabilities)
+      driver_options = { using: using, screen_size: screen_size, options: options }
+
+      self.driver = SystemTesting::Driver.new(driver, driver_options, &desired_capabilities)
     end
 
     driven_by :selenium
diff --git a/actionpack/lib/action_dispatch/system_testing/browser.rb b/actionpack/lib/action_dispatch/system_testing/browser.rb
index 1b0bce6b9e..9361b165ff 100644
--- a/actionpack/lib/action_dispatch/system_testing/browser.rb
+++ b/actionpack/lib/action_dispatch/system_testing/browser.rb
@@ -29,20 +29,27 @@ module ActionDispatch
         end
       end
 
+      def driver_option
+        @option ||= case type
+                    when :chrome
+                      Selenium::WebDriver::Chrome::Options.new
+                    when :firefox
+                      Selenium::WebDriver::Firefox::Options.new
+        end
+      end
+
       private
         def headless_chrome_browser_options
-          options = Selenium::WebDriver::Chrome::Options.new
-          options.args << "--headless"
-          options.args << "--disable-gpu" if Gem.win_platform?
+          driver_option.args << "--headless"
+          driver_option.args << "--disable-gpu" if Gem.win_platform?
 
-          options
+          driver_option
         end
 
         def headless_firefox_browser_options
-          options = Selenium::WebDriver::Firefox::Options.new
-          options.args << "-headless"
+          driver_option.args << "-headless"
 
-          options
+          driver_option
         end
     end
   end
diff --git a/actionpack/lib/action_dispatch/system_testing/driver.rb b/actionpack/lib/action_dispatch/system_testing/driver.rb
index 5252ff6746..87b72a2048 100644
--- a/actionpack/lib/action_dispatch/system_testing/driver.rb
+++ b/actionpack/lib/action_dispatch/system_testing/driver.rb
@@ -3,11 +3,12 @@
 module ActionDispatch
   module SystemTesting
     class Driver # :nodoc:
-      def initialize(name, **options)
+      def initialize(name, **options, &desired_capabilities)
         @name = name
         @browser = Browser.new(options[:using])
         @screen_size = options[:screen_size]
         @options = options[:options]
+        @desired_capabilities = desired_capabilities
       end
 
       def use
@@ -22,6 +23,8 @@ module ActionDispatch
         end
 
         def register
+          define_browser_capabilities(@browser.driver_option)
+
           Capybara.register_driver @name do |app|
             case @name
             when :selenium then register_selenium(app)
@@ -31,6 +34,10 @@ module ActionDispatch
           end
         end
 
+        def define_browser_capabilities(driver_option)
+          @desired_capabilities.call(driver_option) if @desired_capabilities
+        end
+
         def browser_options
           @options.merge(options: @browser.options).compact
         end