Add documentation for system tests

* Document Rails::SystemTestCase
* Document setting drivers with the configration options
* Document using the getter/setter for driver adapters
* Document the CapybaraRackTestDriver and defaults
* Document the CapybaraSeleniumDriver and defaults
* Document custom assertions provided by System Testing
* Document custom form helpers provided by System Testing

9 files changed, 173 insertions, 7 deletions

diff --git a/actionpack/lib/system_test_case.rb b/actionpack/lib/system_test_case.rb
index 2072a88d22..be3858bba8 100644
--- a/actionpack/lib/system_test_case.rb
+++ b/actionpack/lib/system_test_case.rb
@@ -2,6 +2,51 @@ require 'system_testing/test_helper'
 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.
+  # 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.
+  #
+  #   require 'test_helper'
+  #
+  #   class Users::CreateTest < Rails::SystemTestCase
+  #     def adding_a_new_user
+  #       visit users_path
+  #       click_on 'New User'
+  #
+  #       fill_in 'Name', with: 'Arya'
+  #       click_on 'Create User'
+  #
+  #       assert_text 'Arya'
+  #     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.
+  #
+  #   config.system_testing.driver = :capybara_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.
+  #
+  #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
+  #     useragent: 'My Useragent'
+  #   )
+  #
+  # 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.
   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 47d37a26b7..cf44a4fd6b 100644
--- a/actionpack/lib/system_testing/driver_adapter.rb
+++ b/actionpack/lib/system_testing/driver_adapter.rb
@@ -1,18 +1,27 @@
 require 'system_testing/driver_adapters'
 
 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+.
   module DriverAdapter
     extend ActiveSupport::Concern
 
     module ClassMethods
-      def default_driver
+      def default_driver # :nodoc
         :capybara_rack_test_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
+      # initialized.
       def driver
         @driver ||= DriverAdapters.lookup(default_driver).new
       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
diff --git a/actionpack/lib/system_testing/driver_adapters.rb b/actionpack/lib/system_testing/driver_adapters.rb
index a8933b4496..d0771f89cb 100644
--- a/actionpack/lib/system_testing/driver_adapters.rb
+++ b/actionpack/lib/system_testing/driver_adapters.rb
@@ -1,4 +1,10 @@
 module SystemTesting
+  # == System Testing Driver Adapters
+  #
+  # System testing supports the following drivers:
+  #
+  # * {RackTest}[https://github.com/brynary/rack-test]
+  # * {Selenium}[https://github.com/SeleniumHQ/selenium]
   module DriverAdapters
     extend ActiveSupport::Autoload
 
@@ -6,6 +12,10 @@ module SystemTesting
     autoload :CapybaraSeleniumDriver
 
     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)
       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
index 2890686e29..78abfa05ee 100644
--- a/actionpack/lib/system_testing/driver_adapters/capybara_rack_test_driver.rb
+++ b/actionpack/lib/system_testing/driver_adapters/capybara_rack_test_driver.rb
@@ -1,13 +1,32 @@
 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')
+      def initialize(useragent: 'Capybara') # :nodoc:
         @useragent = useragent
       end
 
-      def call
+      def call # :nodoc:
         registration
       end
 
diff --git a/actionpack/lib/system_testing/driver_adapters/capybara_selenium_driver.rb b/actionpack/lib/system_testing/driver_adapters/capybara_selenium_driver.rb
index b4cb10da4f..5585b3e9f1 100644
--- a/actionpack/lib/system_testing/driver_adapters/capybara_selenium_driver.rb
+++ b/actionpack/lib/system_testing/driver_adapters/capybara_selenium_driver.rb
@@ -3,17 +3,63 @@ require 'selenium-webdriver'
 
 module SystemTesting
   module DriverAdapters
+    # == CapybaraSeleniumDriver for System Testing
+    #
+    # The <tt>CapybaraSeleniumDriver</t> 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.
+    #
+    # To set your system testing to use the Selenium web driver add the
+    # following to your Rails' configuration test environment:
+    #
+    #   config.system_testing.driver = :capybara_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:
+    #
+    #   #<SystemTesting::DriverAdapters::CapybaraSeleniumDriver: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.
+    #
+    #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    #     server: :webkit,
+    #     port: 28100,
+    #     screen_size: [ 800, 800 ]
+    #   )
+    #
+    # 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'
+    # test environment:
+    #
+    #   config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
+    #     browser: :firefox
+    #   )
     class CapybaraSeleniumDriver
       attr_reader :browser, :server, :port, :screen_size
 
-      def initialize(browser: :chrome, server: :puma, port: 28100, screen_size: [1400,1400])
+      def initialize(browser: :chrome, server: :puma, port: 28100, screen_size: [1400,1400]) # :nodoc:
         @browser     = browser
         @server      = server
         @port        = port
         @screen_size = screen_size
       end
 
-      def call
+      def call # :nodoc:
         registration
         setup
       end
diff --git a/actionpack/lib/system_testing/railtie.rb b/actionpack/lib/system_testing/railtie.rb
index 6c1ddf1448..459a8e9623 100644
--- a/actionpack/lib/system_testing/railtie.rb
+++ b/actionpack/lib/system_testing/railtie.rb
@@ -1,7 +1,8 @@
 require 'system_test_case'
 
 module SystemTesting
-  class Railtie < Rails::Railtie
+  # = System Testing Railtie
+  class Railtie < Rails::Railtie # :nodoc:
     config.system_testing = ActiveSupport::OrderedOptions.new
 
     initializer "system_testing.set_configs" do |app|
diff --git a/actionpack/lib/system_testing/test_helper.rb b/actionpack/lib/system_testing/test_helper.rb
index 9f2778919c..2027a55d90 100644
--- a/actionpack/lib/system_testing/test_helper.rb
+++ b/actionpack/lib/system_testing/test_helper.rb
@@ -2,7 +2,7 @@ require 'capybara/dsl'
 require 'system_testing/test_helpers'
 
 module SystemTesting
-  module TestHelper
+  module TestHelper # :nodoc:
     include TestHelpers::FormHelper
     include TestHelpers::Assertions
     include Capybara::DSL
diff --git a/actionpack/lib/system_testing/test_helpers/assertions.rb b/actionpack/lib/system_testing/test_helpers/assertions.rb
index 865b5e59db..6e5b62e3c5 100644
--- a/actionpack/lib/system_testing/test_helpers/assertions.rb
+++ b/actionpack/lib/system_testing/test_helpers/assertions.rb
@@ -1,6 +1,11 @@
 module SystemTesting
   module TestHelpers
+    # Assertions for system testing that aren't included by default in Capybara.
+    # These are assertions that are useful specifically for Rails applications.
     module Assertions
+      # Asserts that all of the provided selectors are present on the given page.
+      #
+      #   assert_all_of_selectors('p', 'td')
       def assert_all_of_selectors(*items)
         options = items.extract_options!
         type = type_for_selector(items)
@@ -10,6 +15,9 @@ module SystemTesting
         end
       end
 
+      # Asserts that none of the provided selectors are present on the page.
+      #
+      #   assert_none_of_selectors('ul', 'ol')
       def assert_none_of_selectors(*items)
         options = items.extract_options!
         type = type_for_selector(items)
diff --git a/actionpack/lib/system_testing/test_helpers/form_helper.rb b/actionpack/lib/system_testing/test_helpers/form_helper.rb
index 6ce5c54864..4789694bbb 100644
--- a/actionpack/lib/system_testing/test_helpers/form_helper.rb
+++ b/actionpack/lib/system_testing/test_helpers/form_helper.rb
@@ -1,18 +1,46 @@
 module SystemTesting
   module TestHelpers
+    # Form helpers for system testing that aren't included by default in
+    # Capybara.
     module FormHelper
+      # Finds all provided fields or text areas and fills in with supplied values.
+      #
+      #   fill_in_all_fields('Name' => 'Eileen', 'Job Title' => 'Programmer')
       def fill_in_all_fields(fields)
         fields.each do |name, value|
           fill_in name, with: value
         end
       end
 
+      # Locates a checkbox that is present inside a label and checks it. When
+      # using styled boxes Selenium may not be able to see the checkbox. This
+      # form helper looks inside the checkbox and clicks the label instead of
+      # setting the value of the checkbox.
+      #
+      #   click_checkbox_label 'Admin'
+      #
+      # By default +click_checkbox_label+ looks for checkboxes that are not
+      # checked by default. To locate an already checked box and uncheck it
+      # set checked to true:
+      #
+      #   click_checkbox_label 'Admin', checked: true
       def click_checkbox_label(name, checked: false)
         field = find_checkbox(name, checked)
         label = find_label_wrapper(field)
         label.click
       end
 
+      # In lieu of locating a button and calling +click_on+, +press_enter+ will
+      # submit the form via enter. This method will only work for drivers that
+      # load a browser like Selenium.
+      #
+      #   test 'Adding a User' do
+      #     fill_in 'Name', with: 'Arya'
+      #
+      #     press_enter
+      #
+      #     assert_text 'Arya'
+      #   end
       def press_enter
         page.driver.browser.action.send_keys(:enter).perform
       end