Implement a way to add browser capabilities:

* There is currently no way to define specific browser capabilities since our SystemTest driver override the `option` key [Ref](https://github.com/rails/rails/blob/a07d0680787ced3c04b362fa7a238c918211ac70/actionpack/lib/action_dispatch/system_testing/driver.rb#L35)
  This option key is used internally by selenium to add custom capabilities on the browser.

  Depending on the Browser, some option are allowed to be passed inside a hash, the driver takes care of setting whatever you passed on the driver option. An example [here](https://github.com/rails/rails/blob/a07d0680787ced3c04b362fa7a238c918211ac70/actionpack/lib/action_dispatch/system_testing/driver.rb#L35) where you are allowed to pass args such as `--no-sandbox` etc
  However this behavior was only meant for backward compatibility and as you can see it's deprecated.
  The non-deprecated behavior is to create a `<Driver>::Option` object containing all the capabilities we want. This is what we [currently do](https://github.com/rails/rails/blob/a07d0680787ced3c04b362fa7a238c918211ac70/actionpack/lib/action_dispatch/system_testing/browser.rb#L34-L36) when chrome or firefox are in headless mode.

  This PR allows to pass a block when calling `driven_by`, the block will be pased a `<Driver>::Option` instance. You can modify this object the way you want by adding any capabilities. The option object will be then passed to selenium.

  ```ruby
    driven_by :selenium, using: :chrome do |driver_option|
      driver_option.add_argument('--no-sandbox')
      driver_option.add_emulation(device: 'iphone 4')
    end
  ```

1 files changed, 18 insertions, 2 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