Reconfigure how the drivers work

This removes the useless Rack Test Driver that Rails was providing and
moves to a shim like approach for default adapters.

If someone wants to use one of the default Capybara Drivers then we will
initialize a new `CapybaraDriver` that simply sets the default driver.

Rails though is much more opinionated than Capybara and to make system
testing a "works out of the box" framework in Rails we have the
`RailsSeleniumDriver`. This driver sets defaults that Rails deems
important for selenium testing. The purpose of this is to simply add a
test and it just works.

10 files changed, 154 insertions, 144 deletions

diff --git a/actionpack/lib/system_test_case.rb b/actionpack/lib/system_test_case.rb
index be3858bba8..196798495f 100644
--- a/actionpack/lib/system_test_case.rb
+++ b/actionpack/lib/system_test_case.rb
@@ -3,12 +3,17 @@ require 'system_testing/driver_adapter'
 
 module Rails
   # System tests are similar to Integration tests in that they incorporate multiple
-  # controllers and actions, but can be used to similate a real user experience.
+  # controllers and actions, but can be used to simulate a real user experience.
   # System tests are also known as Acceptance tests.
   #
   # To create a System Test in your application extend your test class from
   # <tt>Rails::SystemTestCase</tt>. System tests use Capybara as a base and
-  # allows you to configure the driver. The default driver is RackTest.
+  # allows you to configure the driver. The default driver is
+  # <tt>RailsSeleniumDriver</tt> which provides Capybara with no-setup
+  # configuration of the Selenium Driver. If you prefer you can use the bare
+  # Selenium driver and set your own configuration.
+  #
+  # A system test looks like the following:
   #
   #   require 'test_helper'
   #
@@ -24,29 +29,25 @@ module Rails
   #     end
   #   end
   #
-  # System tests in your application can be configured to use different drivers.
-  #
-  # To specify a driver, add the following to your Rails' configuration file for
-  # the test environment.
+  # System test driver can be configured in your Rails configuration file for the
+  # test environment.
   #
-  #   config.system_testing.driver = :capybara_selenium_driver
+  #   config.system_testing.driver = :rails_selenium_driver
   #
-  # You can also specify a driver with a new driver object. Through this method
-  # you can also change the default settings for the driver you're setting.
+  # You can also specify a driver by initializing a new driver object. This allows
+  # you to change the default settings for the driver you're setting.
   #
-  #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
-  #     useragent: 'My Useragent'
+  #   config.system_testing.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
+  #     browser: :firefox
   #   )
   #
   # A list of supported adapters can be found in DriverAdapters.
   #
-  # If you want to use a driver that is not supported by Rails but is available
-  # in Capybara, you can override Rails settings and use Capybara directly by
-  # setting the +Capybara.default_driver+ and +Capybara.javascript_driver+ in
-  # your test_help file.
-  #
-  # You can also skip using Rails system tests completely by not inheriting from
-  # <tt>Rails::SystemTestCase</tt> and following Capybara's instructions.
+  # If you want to use one of the default drivers provided by Capybara you can
+  # set the driver in your config to one of those defaults: +:rack_test+,
+  # +:selenium+, +:webkit+, or +:poltergeist+. These 4 drivers use Capyara's
+  # driver defaults whereas the <tt>RailsSeleniumDriver</tt> has pre-set
+  # configuration for browser, server, port, etc.
   class SystemTestCase < ActionDispatch::IntegrationTest
     include SystemTesting::TestHelper
     include SystemTesting::DriverAdapter
diff --git a/actionpack/lib/system_testing/driver_adapter.rb b/actionpack/lib/system_testing/driver_adapter.rb
index cf44a4fd6b..3d8545f3c6 100644
--- a/actionpack/lib/system_testing/driver_adapter.rb
+++ b/actionpack/lib/system_testing/driver_adapter.rb
@@ -4,32 +4,26 @@ module SystemTesting
   # The <tt>SystemTesting::DriverAdapter</tt> module is used to load the driver
   # set in your Rails' test configuration file.
   #
-  # The default driver adapters is the +:capybara_rack_test_driver+.
+  # The default driver adapter is the +:rails_selenium_driver+.
   module DriverAdapter
     extend ActiveSupport::Concern
 
     module ClassMethods
       def default_driver # :nodoc
-        :capybara_rack_test_driver
+        :rails_selenium_driver
       end
 
       # Returns the current driver that is set. If no driver is set in the
-      # Rails' configuration file then +:capybara_rack_test_driver+ will be
+      # Rails' configuration file then +:rails_selenium_driver+ will be
       # initialized.
       def driver
-        @driver ||= DriverAdapters.lookup(default_driver).new
+        @driver ||= DriverAdapters.lookup(default_driver)
       end
 
       # Specify the adapter and settings for the system test driver set in the
       # Rails' configuration file.
-      def driver=(adapter)
-        @driver = case adapter
-        when Symbol
-          DriverAdapters.lookup(adapter).new
-        else
-          adapter
-        end
-
+      def driver=(driver)
+        @driver = DriverAdapters.lookup(driver)
         @driver.call
       end
     end
diff --git a/actionpack/lib/system_testing/driver_adapters.rb b/actionpack/lib/system_testing/driver_adapters.rb
index d0771f89cb..bb65fe9111 100644
--- a/actionpack/lib/system_testing/driver_adapters.rb
+++ b/actionpack/lib/system_testing/driver_adapters.rb
@@ -1,23 +1,45 @@
 module SystemTesting
   # == System Testing Driver Adapters
   #
-  # System testing supports the following drivers:
+  # By default Rails supports Capybara with the Selenium Driver. Rails provides
+  # configuration setup for using the selenium driver with Capybara.
+  # Additionally Rails can be used as a layer between Capybara and its other
+  # supported drivers: +:rack_test+, +:selenium+, +:webkit+, or +:poltergeist+.
   #
-  # * {RackTest}[https://github.com/brynary/rack-test]
-  # * {Selenium}[https://github.com/SeleniumHQ/selenium]
+  # *{RackTest}[https://github.com/jnicklas/capybara#racktest]
+  # *{Selenium}[http://seleniumhq.org/docs/01_introducing_selenium.html#selenium-2-aka-selenium-webdriver]
+  # *{Webkit}[https://github.com/thoughtbot/capybara-webkit]
+  # *{Poltergeist}[https://github.com/teampoltergeist/poltergeist]
+  #
+  # === Driver Features
+  #
+  # |                 | Default Browser       | Supports Screenshots? |
+  # |-----------------|-----------------------|-----------------------|
+  # | Rails' Selenium | Chrome                | Yes                   |
+  # | Rack Test       | No JS Support         | No                    |
+  # | Selenium        | Firefox               | Yes                   |
+  # | WebKit          | Headless w/ Qt        | Yes                   |
+  # | Poltergeist     | Headless w/ PhantomJS | Yes                   |
   module DriverAdapters
     extend ActiveSupport::Autoload
 
-    autoload :CapybaraRackTestDriver
-    autoload :CapybaraSeleniumDriver
+    autoload :CapybaraDriver
+    autoload :RailsSeleniumDriver
 
     class << self
       # Returns driver for specified name.
       #
-      #   SystemTesting::DriverAdapters.lookup(:capybara_selenium_driver)
-      #   # => SystemTesting::DriverAdapters::CapybaraSeleniumDriver
-      def lookup(name)
-        const_get(name.to_s.camelize)
+      #   SystemTesting::DriverAdapters.lookup(:rails_selenium_driver)
+      #   # => SystemTesting::DriverAdapters::RailsSeleniumDriver
+      def lookup(driver)
+        if CapybaraDriver::CAPYBARA_DEFAULTS.include?(driver)
+          CapybaraDriver.new(driver)
+        elsif driver.is_a?(Symbol)
+          klass = const_get(driver.to_s.camelize)
+          klass.new
+        else
+          driver
+        end
       end
     end
   end
diff --git a/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb b/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb
new file mode 100644
index 0000000000..84941a9929
--- /dev/null
+++ b/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb
@@ -0,0 +1,57 @@
+module SystemTesting
+  module DriverAdapters
+    # == CapybaraDriver for System Testing
+    #
+    # The <tt>CapybaraDriver</tt> is a shim that sits between Rails and
+    # Capybara.
+    #
+    # The drivers Capybara supports are: +:rack_test+, +:selenium+, +:webkit+,
+    # and +:poltergeist+.
+    #
+    # Rails provides its own defaults for Capybara with the Selenium driver
+    # through <tt>RailsSeleniumDriver</tt>, but allows users to use Selenium
+    # directly.
+    #
+    # To set your system tests to use one of Capybara's default drivers, add
+    # the following to yur Rails' configuration test environment:
+    #
+    #   config.system_testing.driver = :rack_test
+    #
+    # The +:rack_test+ driver is a basic test driver that doesn't support
+    # JavaScript testing and doesn't require a server.
+    #
+    # The +:poltergeist+ and +:webkit+ drivers are headless, but require some
+    # extra environment setup. Because the default server for Rails is Puma, each
+    # of the Capybara drivers will default to using Puma. Changing the configuration
+    # to use Webrick is possible by initalizing a new driver object.
+    #
+    # The default settings for the <tt>CapybaraDriver</tt> are:
+    #
+    #   #<SystemTesting::DriverAdapters::CapybaraDriver:0x007ff0e992c1d8
+    #     @name=:rack_test,
+    #     @server=:puma,
+    #     @port=28100
+    #    >
+    #
+    # The settings for the <tt>CapybaraDriver</tt> can be changed from
+    # Rails' configuration file.
+    #
+    #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraDriver.new(
+    #     name: :webkit,
+    #     server: :webrick
+    #   )
+    class CapybaraDriver
+      CAPYBARA_DEFAULTS = [ :rack_test, :selenium, :webkit, :poltergeist ]
+
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def call
+        Capybara.default_driver = @name
+      end
+    end
+  end
+end
diff --git a/actionpack/lib/system_testing/driver_adapters/capybara_rack_test_driver.rb b/actionpack/lib/system_testing/driver_adapters/capybara_rack_test_driver.rb
deleted file mode 100644
index 78abfa05ee..0000000000
--- a/actionpack/lib/system_testing/driver_adapters/capybara_rack_test_driver.rb
+++ /dev/null
@@ -1,43 +0,0 @@
-module SystemTesting
-  module DriverAdapters
-    # == CapybaraRackTestDriver for System Testing
-    #
-    # This is the default driver for Capybara. This driver does not support
-    # JavaScript because it doesn't open a browser when running the test suite.
-    #
-    # Although it does not support JavaScript testing the
-    # <tt>CapybaraRackTestDriver</tt> is fast and efficient. This driver requires
-    # no setup and becasue it does not need a webserver, additional configuration
-    # is not required.
-    #
-    # The <tt>CapybaraRackTestDriver</tt> only takes one argument for initialization
-    # which is +:useragent+.
-    #
-    # To set the useragent add the following to your
-    # Rails' configuration file:
-    #
-    #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
-    #     useragent: 'My UserAgent'
-    #   )
-    class CapybaraRackTestDriver
-      attr_reader :useragent
-
-      def initialize(useragent: 'Capybara') # :nodoc:
-        @useragent = useragent
-      end
-
-      def call # :nodoc:
-        registration
-      end
-
-      private
-        def registration
-          Capybara.register_driver :rack_test do |app|
-            Capybara::RackTest::Driver.new(app, headers: {
-              'HTTP_USER_AGENT' => @useragent
-            })
-          end
-        end
-    end
-  end
-end
diff --git a/actionpack/lib/system_testing/driver_adapters/capybara_selenium_driver.rb b/actionpack/lib/system_testing/driver_adapters/rails_selenium_driver.rb
index 5585b3e9f1..77533bf39b 100644
--- a/actionpack/lib/system_testing/driver_adapters/capybara_selenium_driver.rb
+++ b/actionpack/lib/system_testing/driver_adapters/rails_selenium_driver.rb
@@ -3,56 +3,57 @@ require 'selenium-webdriver'
 
 module SystemTesting
   module DriverAdapters
-    # == CapybaraSeleniumDriver for System Testing
+    # == RailsSeleniumDriver for System Testing
     #
-    # The <tt>CapybaraSeleniumDriver</t> uses the Selenium 2.0 webdriver. The
+    # The <tt>RailsSeleniumDriver</tt> uses the Selenium 2.0 webdriver. The
     # selenium-webdriver gem is required by this driver.
     #
-    # The CapybaraSeleniumDriver is useful for real browser testing and
-    # support Chrome and Firefox.
+    # The <tt>RailsSeleniumDriver</tt> is useful for real browser testing and
+    # supports Chrome and Firefox.
     #
-    # To set your system testing to use the Selenium web driver add the
-    # following to your Rails' configuration test environment:
+    # By default Rails system testing will use Rails' configuration with Capybara
+    # and the Selenium driver. To explictly set the <tt>RailsSeleniumDriver</tt>
+    # add the following to your Rails' configuration test environment:
     #
-    #   config.system_testing.driver = :capybara_selenium_driver
+    #   config.system_testing.driver = :rails_selenium_driver
     #
     # Because this driver supports real browser testing it is required that a
     # server is configured.
     #
     # If no server is specified when the driver is initialized, Puma will be used
-    # by default. The default settings for the <tt>CapybaraSeleniumDriver</tt>
-    # are:
+    # by default. The default settings for the <tt>RailsSeleniumDriver</tt>
+    # are as follows:
     #
-    #   #<SystemTesting::DriverAdapters::CapybaraSeleniumDriver:0x007ff0e992c1d8
+    #   #<SystemTesting::DriverAdapters::RailsSeleniumDriver:0x007ff0e992c1d8
     #     @browser=:chrome,
     #     @server=:puma,
     #     @port=28100,
     #     @screen_size=[ 1400, 1400 ]
     #    >
     #
-    # The settings for the <tt>CapybaraSeleniumDriver</tt> can be changed from
-    # Rails' configuration file.
+    # The settings for the <tt>RailsSeleniumDriver</tt> can be changed in the
+    # Rails configuration file.
     #
-    #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
-    #     server: :webkit,
+    #   config.system_testing.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
+    #     server: :webrick,
     #     port: 28100,
     #     screen_size: [ 800, 800 ]
     #   )
     #
-    # The default browser is set to chrome because the current version of
+    # The default browser is set to Chrome because the current version of
     # Firefox does not work with selenium-webdriver. If you want to use Firefox,
     # you will need to use Firefox 45.0esr or 47.0 and ensure
     # that selenium-webdriver is version 2.53.4. To change the browser from
-    # +:chrome+ to +:firefox+, initialize the selenium driver in your Rails'
+    # +:chrome+ to +:firefox+, initialize the Selenium driver in your Rails'
     # test environment:
     #
-    #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    #   config.system_testing.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
     #     browser: :firefox
     #   )
-    class CapybaraSeleniumDriver
+    class RailsSeleniumDriver
       attr_reader :browser, :server, :port, :screen_size
 
-      def initialize(browser: :chrome, server: :puma, port: 28100, screen_size: [1400,1400]) # :nodoc:
+      def initialize(browser: :chrome, server: :puma, port: 28100, screen_size: [ 1400,1400 ]) # :nodoc:
         @browser     = browser
         @server      = server
         @port        = port
@@ -106,7 +107,7 @@ module SystemTesting
         end
 
         def register_webrick(app, port, host)
-          Rack::Handler::WEBrick.run(app, Host: host, Port: port, AccessLog: [], Logger: WEBrick::Log::new(nil, 0))
+          ::Rack::Handler::WEBrick.run(app, Host: host, Port: port, AccessLog: [], Logger: WEBrick::Log::new(nil, 0))
         end
 
         def set_server
diff --git a/actionpack/test/system_testing/capybara_driver_test.rb b/actionpack/test/system_testing/capybara_driver_test.rb
new file mode 100644
index 0000000000..b409fdfab0
--- /dev/null
+++ b/actionpack/test/system_testing/capybara_driver_test.rb
@@ -0,0 +1,10 @@
+require 'abstract_unit'
+
+class CapybaraDriverTest < ActiveSupport::TestCase
+  def test_setting_useragent
+    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraDriver.new(
+      :rack_test
+    )
+    assert_equal :rack_test, Rails::SystemTestCase.driver.name
+  end
+end
diff --git a/actionpack/test/system_testing/capybara_rack_test_driver_test.rb b/actionpack/test/system_testing/capybara_rack_test_driver_test.rb
deleted file mode 100644
index 0f037760d3..0000000000
--- a/actionpack/test/system_testing/capybara_rack_test_driver_test.rb
+++ /dev/null
@@ -1,26 +0,0 @@
-require 'abstract_unit'
-
-class CapybaraRackTestDriverTest < ActiveSupport::TestCase
-  def test_default_driver_adapter
-    assert_kind_of SystemTesting::DriverAdapters::CapybaraRackTestDriver, Rails::SystemTestCase.driver
-  end
-
-  def test_default_settings
-    assert_equal 'Capybara', Rails::SystemTestCase.driver.useragent
-  end
-
-  def test_setting_useragent
-    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
-      useragent: 'x'
-    )
-    assert_equal 'x', Rails::SystemTestCase.driver.useragent
-  end
-
-  def test_does_not_accept_nonsense_kwargs
-    assert_raises ArgumentError do
-      Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
-        made_up_arg: 'x'
-      )
-    end
-  end
-end
diff --git a/actionpack/test/system_testing/driver_adapter_test.rb b/actionpack/test/system_testing/driver_adapter_test.rb
index bfbeaa63a2..220a755bd3 100644
--- a/actionpack/test/system_testing/driver_adapter_test.rb
+++ b/actionpack/test/system_testing/driver_adapter_test.rb
@@ -7,13 +7,7 @@ class DriverAdapterTest < ActiveSupport::TestCase
     end
 
     assert_nothing_raised do
-      Rails::SystemTestCase.driver = :capybara_selenium_driver
-    end
-  end
-
-  test 'settings can only be used for the appropriate adapter' do
-    assert_raises(ArgumentError) do
-      Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(something: 'test')
+      Rails::SystemTestCase.driver = :rack_test
     end
   end
 end
diff --git a/actionpack/test/system_testing/capybara_selenium_driver_test.rb b/actionpack/test/system_testing/rails_selenium_driver_test.rb
index 6357b35aa6..c239444838 100644
--- a/actionpack/test/system_testing/capybara_selenium_driver_test.rb
+++ b/actionpack/test/system_testing/rails_selenium_driver_test.rb
@@ -1,12 +1,12 @@
 require 'abstract_unit'
 
-class CapybaraSeleniumDriverTest < ActiveSupport::TestCase
+class RailsSeleniumDriverTest < ActiveSupport::TestCase
   def setup
-    Rails::SystemTestCase.driver = :capybara_selenium_driver
+    Rails::SystemTestCase.driver = :rails_selenium_driver
   end
 
-  def test_setting_driver_adapter_to_selenium
-    assert_kind_of SystemTesting::DriverAdapters::CapybaraSeleniumDriver, Rails::SystemTestCase.driver
+  def test_default_driver_adapter
+    assert_kind_of SystemTesting::DriverAdapters::RailsSeleniumDriver, Rails::SystemTestCase.driver
   end
 
   def test_default_settings
@@ -17,7 +17,7 @@ class CapybaraSeleniumDriverTest < ActiveSupport::TestCase
   end
 
   def test_setting_browser
-    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
       browser: :firefox
     )
 
@@ -25,7 +25,7 @@ class CapybaraSeleniumDriverTest < ActiveSupport::TestCase
   end
 
   def test_setting_server
-    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
       server: :webrick
     )
 
@@ -33,7 +33,7 @@ class CapybaraSeleniumDriverTest < ActiveSupport::TestCase
   end
 
   def test_setting_port
-    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
       port: 3000
     )
 
@@ -41,7 +41,7 @@ class CapybaraSeleniumDriverTest < ActiveSupport::TestCase
   end
 
   def test_setting_screen_size
-    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
       screen_size: [ 800, 800 ]
     )
 
@@ -50,7 +50,7 @@ class CapybaraSeleniumDriverTest < ActiveSupport::TestCase
 
   def test_does_not_accept_nonsense_kwargs
     assert_raises ArgumentError do
-      Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+      Rails::SystemTestCase.driver = SystemTesting::DriverAdapters::RailsSeleniumDriver.new(
         made_up_arg: 'x'
       )
     end