Update documentation and guides

Update the documentation after rewriting a majority of the functionality
for system testing.

4 files changed, 157 insertions, 103 deletions

diff --git a/actionsystemtest/README.md b/actionsystemtest/README.md
index 3710b8dbd4..87f4001a8d 100644
--- a/actionsystemtest/README.md
+++ b/actionsystemtest/README.md
@@ -1,8 +1,10 @@
 # Action System Test
 
-Action System Test adds Capybara integration to your Rails application for
-acceptance testing. This allows you to test the entire user experience
-of your application rather than just your controllers, or just your models.
+Action System Test adds Capybara integration to your Rails application and makes
+it possible to test your application and it's JavaScript interactions.
+
+This allows you to test the entire user experience of your application rather
+than your controllers, models, and views separately.
 
 Action System Test provides all of the setup out of the box for you to use
 Capybara with the Selenium Driver in your Rails application. Changing the
@@ -26,14 +28,14 @@ class UsersTest < ActionSystemTestCase
     visit users_path
   end
 
-  test 'creating a new user' do
-    click_on 'New User'
+  test "creating a new user" do
+    click_on "New User"
 
-    fill_in 'Name', with: 'Arya'
+    fill_in "Name", with: "Arya"
 
-    click_on 'Create User'
+    click_on "Create User"
 
-    assert_text 'Arya'
+    assert_text "Arya"
   end
 end
 ```
@@ -44,8 +46,6 @@ it will fill in the "Name" field with "Arya" and click on the "Create User"
 button. Lastly, we assert that the text on the Users show page is what we
 expected, which in this case is "Arya".
 
-For more helpers and how to write Capybara tests visit Capybara's README.
-
 ### Configuration
 
 When generating a new application Rails will include the Capybara gem, the
@@ -56,53 +56,47 @@ configuration if Rails doesn't work out of the box for you.
 The <tt>system_test_helper.rb</tt> file provides a home for all of your Capybara
 and Action System Test configuration.
 
-Rails preset configuration for Capybara with Selenium defaults to Puma for
-the web server on port 28100, Chrome for the browser, and a screen size of
-1400 x 1400.
+The default configuration uses the Selenium driver, with the Chrome browser,
+served by Puma on port 21800 with a screen size of 1400x1400.
 
 Changing the configuration is as simple as changing the driver in your
 <tt>system_test_helper.rb</tt>
 
 If you want to change the default settings of the Rails provided Selenium
-configuration options you can initialize a new <tt>RailsSeleniumDriver</tt>
-object.
-
-```ruby
-class ActionSystemTestCase < ActionSystemTest::Base
-  ActionSystemTest.driver = RailsSeleniumDriver.new(
-    browser: :firefox,
-    server: :webrick
-  )
-end
-```
+you can change `driven_by` in the helper file.
 
-Capybara itself provides 4 drivers: RackTest, Selenium, Webkit, and Poltergeist.
-Action System Test provides a shim between Rails and Capybara for these 4 drivers.
-Please note, that Rails is set up to use the Puma server by default for these
-4 drivers. Puma is the default in Rails and therefore is set as the default in
-the Rails Capybara integration.
+The driver name is a required argument for `driven_by`. The optional arguments
+that can be passed to `driven_by` are `:using` for the browser (this will only
+be used for non-headless drivers like Selenium), `:on` for the port Puma should
+use, and `:screen_size` to change the size of the screen for screenshots.
 
-To set your application tests to use any of Capybara's defaults with no configuration,
-set the following in your <tt>system_test_helper.rb</tt> file and follow setup instructions
-for environment requirements of these drivers.
+Below are some examples for changing the default configuration settings for
+system tests:
 
-The possible settings are +:rack_test+, +:selenium+, +:webkit+, or +:poltergeist+.
+Changing the browser, port for Puma, and screen size:
 
 ```ruby
 class ActionSystemTestCase < ActionSystemTest::Base
-  ActionSystemTest.driver = :poltergeist
+  driven_by :selenium, using: :firefox, on: 3000, screen_size: [ 800, 800 ]
 end
 ```
 
-If you want to change the default server (puma) or port (28100) for Capbyara drivers
-you can initialize a new object.
+The browser setting is not used by headless drivers like Poltergeist. When
+using a headless driver simply leave out the `:using` argument.
 
 ```ruby
 class ActionSystemTestCase < ActionSystemTest::Base
-  ActionSystemTest.driver = ActionSystemTest::DriverAdapters::CapybaraDriver.new(
-    name: :poltergeist,
-    server: :webkit,
-    port: 3000
-  )
+  driven_by :poltergeist, on: 3000
 end
 ```
+
+### Running the tests
+
+Because system tests are time consuming and can use a lot of resources
+they are not automatically run with `rails test`.
+
+To run all the tests in the system suite run the system test command:
+
+```
+$ rails test:system
+```
diff --git a/actionsystemtest/lib/action_system_test.rb b/actionsystemtest/lib/action_system_test.rb
index ded2b96584..d28e30d116 100644
--- a/actionsystemtest/lib/action_system_test.rb
+++ b/actionsystemtest/lib/action_system_test.rb
@@ -1,54 +1,25 @@
-# System tests are similar to Integration tests in that they incorporate multiple
-# 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>ActionSystemTestCase</tt>. System tests use Capybara as a base and
-# allow you to configure the driver. The default driver is
-# <tt>RailsSeleniumDriver</tt> which provides a Capybara and the Selenium
-# Driver with no configuration. It's intended to work out of the box.
-#
-# A system test looks like the following:
-#
-#   require 'system_test_helper'
-#
-#   class Users::CreateTest < ActionSystemTestCase
-#     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
-#
-# When generating an application or scaffold a +system_test_helper.rb+ will also
-# be generated containing the base class for system testing. This is where you can
-# change the driver, add Capybara settings, and other configuration for your system
-# tests.
-#
-#   class ActionSystemTestCase < ActionSystemTest::Base
-#     ActionSystemTest.driver = :rack_test
-#   end
-#
-# 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.
-#
-#   class ActionSystemTestCase < ActionSystemTest::Base
-#     ActionSystemTest.driver = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
-#       browser: :firefox
-#     )
-#   end
-#
-# A list of supported adapters can be found in DriverAdapters.
-#
-# 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.
+#--
+## Copyright (c) 2014-2017 David Heinemeier Hansson
+##
+## Permission is hereby granted, free of charge, to any person obtaining
+## a copy of this software and associated documentation files (the
+## "Software"), to deal in the Software without restriction, including
+## without limitation the rights to use, copy, modify, merge, publish,
+## distribute, sublicense, and/or sell copies of the Software, and to
+## permit persons to whom the Software is furnished to do so, subject to
+## the following conditions:
+##
+## The above copyright notice and this permission notice shall be
+## included in all copies or substantial portions of the Software.
+##
+## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+## EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+## MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+## NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+## LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+## OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+## WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+##++
 
 require "capybara/dsl"
 require "action_controller"
@@ -57,7 +28,91 @@ require "action_system_test/browser"
 require "action_system_test/server"
 require "action_system_test/test_helpers/screenshot_helper"
 
-module ActionSystemTest
+module ActionSystemTest # :nodoc:
+  # = Action System Test
+  #
+  # System tests let you test real application in the browser. Because system tests
+  # use a real browser experience you can test all of your JavaScript easily
+  # from your test suite.
+  #
+  # To create an ActionSystemTest in your application, extend your test class
+  # from <tt>ActionSystemTestCase</tt>. System tests use Capybara as a base and
+  # allow you to configure the settings through your <tt>system_test_helper.rb</tt>
+  # file that is generated with a new application or scaffold.
+  #
+  # Here is an example system test:
+  #
+  #   require 'system_test_helper'
+  #
+  #   class Users::CreateTest < ActionSystemTestCase
+  #     test "adding a new user" do
+  #       visit users_path
+  #       click_on 'New User'
+  #
+  #       fill_in 'Name', with: 'Arya'
+  #       click_on 'Create User'
+  #
+  #       assert_text 'Arya'
+  #     end
+  #   end
+  #
+  # When generating an application or scaffold a +system_test_helper.rb+ will also
+  # be generated containing the base class for system testing. This is where you
+  # can change the driver, add Capybara settings, and other configuration for
+  # your system tests.
+  #
+  #   require "test_helper"
+  #
+  #   class ActionSystemTestCase < ActionSystemTest::Base
+  #     teardown do
+  #       take_failed_screenshot
+  #       Capybara.reset_sessions!
+  #     end
+  #   end
+  #
+  # By default, <tt>ActionSystemTest</tt> is driven by the Selenium driver, with
+  # the Chrome browser, on port 21800, and a browser size of 1400x1400.
+  #
+  # Changing the driver configuration options are easy. Let's say you want to use
+  # port 3000, and the Firefox browser instead. In your +system_test_helper.rb+
+  # file add the following:
+  #
+  #   require "test_helper"
+  #
+  #   class ActionSystemTestCase < ActionSystemTest::Base
+  #     driven_by :selenium, using: :firefox, on: 3000
+  #
+  #     teardown do
+  #       take_failed_screenshot
+  #       Capybara.reset_sessions!
+  #     end
+  #   end
+  #
+  # +driven_by+ has a required argument for the driver name. The keyword
+  # arguments are +:using+ for the browser (not applicable for headless drivers),
+  # +:on+ for port (the server is always Puma), and +:screen_size+ to change
+  # the size of the screen when taking screenshots.
+  #
+  # To use a headless driver, like Poltergeist, update your Gemfile to use
+  # Poltergeist instead of Selenium and then declare the driver name in the
+  # +system_test_helper.rb+ file. In this case you would leave out the +:using+
+  # option because the driver is headless.
+  #
+  #   require "test_helper"
+  #   require "capybara/poltergeist"
+  #
+  #   class ActionSystemTestCase < ActionSystemTest::Base
+  #     driven_by :poltergeist
+  #
+  #     teardown do
+  #       take_failed_screenshot
+  #       Capybara.reset_sessions!
+  #     end
+  #   end
+  #
+  # Because <tt>ActionSystemTest</tt> is a shim between Capybara and Rails, any
+  # driver that is supported by Capybara is supported by Action System Test as
+  # long as you include the required gems and files.
   include Capybara::DSL
   include ActionSystemTest::TestHelpers::ScreenshotHelper
 
@@ -72,6 +127,16 @@ module ActionSystemTest
       end
     end
 
+    # Action System Test configuration options
+    #
+    # The defaults settings are Selenium, using Chrome, on port 21800, with a
+    # screen size of 1400x1400.
+    #
+    # Examples:
+    #
+    #   driven_by :poltergeist
+    #
+    #   driven_by :selenium, using: :firefox, on: 3000
     def self.driven_by(driver, using: :chrome, on: 21800, screen_size: [1400, 1400])
       Driver.new(driver).run
       Server.new(on).run
diff --git a/actionsystemtest/lib/action_system_test/browser.rb b/actionsystemtest/lib/action_system_test/browser.rb
index 09b72721c5..220d8b6807 100644
--- a/actionsystemtest/lib/action_system_test/browser.rb
+++ b/actionsystemtest/lib/action_system_test/browser.rb
@@ -1,5 +1,5 @@
 module ActionSystemTest
-  class Browser
+  class Browser # :nodoc:
     def initialize(name, screen_size)
       @name = name
       @screen_size = screen_size
diff --git a/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb b/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb
index d4d0d79e95..af83ca3ec8 100644
--- a/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb
+++ b/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb
@@ -4,14 +4,9 @@ module ActionSystemTest
     module ScreenshotHelper
       # Takes a screenshot of the current page in the browser.
       #
-      # +take_screenshot+ can be used within your tests at points
-      # you want to take a screenshot if the driver supports screenshots. The
-      # Rack Test driver does not support screenshots.
-      #
-      # You can check if the driver supports screenshots by running
-      #
-      #   ActionSystemTest.driver.supports_screenshots?
-      #   => true
+      # +take_screenshot+ can be used at any point in your system tests to take
+      # a screenshot of the current state. This can be useful for debugging or
+      # automating visual testing.
       def take_screenshot
         save_image
         puts "[Screenshot]: #{image_path}"
@@ -23,7 +18,7 @@ module ActionSystemTest
       #
       # +take_screenshot+ is included in <tt>system_test_helper.rb</tt> that is
       # generated with the application. To take screenshots when a test fails
-      # add +take_failed_screenshot+ to the teardown block before clearing any
+      # add +take_failed_screenshot+ to the teardown block before clearing
       # sessions.
       def take_failed_screenshot
         take_screenshot unless passed?