Amend documentation

Many changes have been made since the beginning so documentation needed
a refresher.

5 files changed, 46 insertions, 34 deletions

diff --git a/actionsystemtest/lib/action_system_test/driver_adapter.rb b/actionsystemtest/lib/action_system_test/driver_adapter.rb
index 892edd2d32..3a0ab0763a 100644
--- a/actionsystemtest/lib/action_system_test/driver_adapter.rb
+++ b/actionsystemtest/lib/action_system_test/driver_adapter.rb
@@ -2,22 +2,24 @@ require "action_system_test/driver_adapters"
 
 module ActionSystemTest
   # The <tt>ActionSystemTest::DriverAdapter</tt> module is used to load the driver
-  # set in your Rails' test configuration file.
+  # set in the +system_test_helper+ file generated with your application.
   #
   # The default driver adapter is the +:rails_selenium_driver+.
   module DriverAdapter
     extend ActiveSupport::Concern
 
     module ClassMethods
-      # Returns the current driver that is set. If no driver is set in the
-      # Rails' configuration file then +:rails_selenium_driver+ will be
-      # initialized.
+      # Returns the current driver that is set in the <tt>ActionSystemTestCase</tt>
+      # class generated with your Rails application. If no driver is set
+      # +:rails_selenium_driver+ will be initialized.
       def driver
         @driver ||= DriverAdapters.lookup(DEFAULT_DRIVER)
       end
 
       # Specify the adapter and settings for the system test driver set in the
       # Rails' configuration file.
+      #
+      # When set, the driver will be initialized.
       def driver=(driver)
         @driver = DriverAdapters.lookup(driver)
         @driver.call
diff --git a/actionsystemtest/lib/action_system_test/driver_adapters.rb b/actionsystemtest/lib/action_system_test/driver_adapters.rb
index aead9d6f60..6fb8675489 100644
--- a/actionsystemtest/lib/action_system_test/driver_adapters.rb
+++ b/actionsystemtest/lib/action_system_test/driver_adapters.rb
@@ -1,5 +1,5 @@
 module ActionSystemTest
-  # == System Testing Driver Adapters
+  # == Action System Testing Driver Adapters
   #
   # By default Rails supports Capybara with the Selenium Driver. Rails provides
   # configuration setup for using the selenium driver with Capybara.
@@ -14,7 +14,7 @@ module ActionSystemTest
   # === Driver Features
   #
   # |                 | Default Browser       | Supports Screenshots? |
-  # |-----------------|-----------------------|-----------------------|
+  # | --------------- | --------------------- | --------------------- |
   # | Rails' Selenium | Chrome                | Yes                   |
   # | Rack Test       | No JS Support         | No                    |
   # | Selenium        | Firefox               | Yes                   |
@@ -27,7 +27,7 @@ module ActionSystemTest
     autoload :RailsSeleniumDriver
 
     class << self
-      # Returns driver for specified name.
+      # Returns driver class for specified name.
       #
       #   ActionSystemTest::DriverAdapters.lookup(:rails_selenium_driver)
       #   # => ActionSystemTest::DriverAdapters::RailsSeleniumDriver
diff --git a/actionsystemtest/lib/action_system_test/driver_adapters/capybara_driver.rb b/actionsystemtest/lib/action_system_test/driver_adapters/capybara_driver.rb
index 5362f6db25..c1b395f712 100644
--- a/actionsystemtest/lib/action_system_test/driver_adapters/capybara_driver.rb
+++ b/actionsystemtest/lib/action_system_test/driver_adapters/capybara_driver.rb
@@ -4,8 +4,7 @@ module ActionSystemTest
   module DriverAdapters
     # == CapybaraDriver for System Testing
     #
-    # The <tt>CapybaraDriver</tt> is a shim that sits between Rails and
-    # Capybara.
+    # The <tt>CapybaraDriver</tt> is a shim between Rails and Capybara.
     #
     # The drivers Capybara supports are: +:rack_test+, +:selenium+, +:webkit+,
     # and +:poltergeist+.
@@ -15,16 +14,21 @@ module ActionSystemTest
     # directly.
     #
     # To set your system tests to use one of Capybara's default drivers, add
-    # the following to yur Rails' configuration test environment:
+    # the following to your +system_test_helper+ class file:
     #
-    #   config.system_testing.driver = :rack_test
+    #   class ActionSystemTestCase < ActionSystemTest::Base
+    #     ActionSystemTest.driver = :rack_test
+    #   end
     #
     # 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
+    # extra environment setup. Please see their README's for instructions on
+    # 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:
@@ -35,10 +39,10 @@ module ActionSystemTest
     #     @port=28100
     #    >
     #
-    # The settings for the <tt>CapybaraDriver</tt> can be changed from
-    # Rails' configuration file.
+    # The settings for the <tt>CapybaraDriver</tt> can be changed in the
+    # +system_test_helper+ file in your application's test directory.
     #
-    #   config.system_testing.driver = ActionSystemTest::DriverAdapters::CapybaraDriver.new(
+    #   ActionSystemTest.driver = ActionSystemTest::DriverAdapters::CapybaraDriver.new(
     #     name: :webkit,
     #     server: :webrick
     #   )
diff --git a/actionsystemtest/lib/action_system_test/driver_adapters/rails_selenium_driver.rb b/actionsystemtest/lib/action_system_test/driver_adapters/rails_selenium_driver.rb
index 16e485398a..543b14a029 100644
--- a/actionsystemtest/lib/action_system_test/driver_adapters/rails_selenium_driver.rb
+++ b/actionsystemtest/lib/action_system_test/driver_adapters/rails_selenium_driver.rb
@@ -2,7 +2,7 @@ require "action_system_test/driver_adapters/web_server"
 
 module ActionSystemTest
   module DriverAdapters
-    # == RailsSeleniumDriver for System Testing
+    # == RailsSeleniumDriver for Action System Test
     #
     # The <tt>RailsSeleniumDriver</tt> uses the Selenium 2.0 webdriver. The
     # selenium-webdriver gem is required by this driver.
@@ -12,9 +12,11 @@ module ActionSystemTest
     #
     # 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:
+    # add the following to your +system_test_helper+:
     #
-    #   config.system_testing.driver = :rails_selenium_driver
+    #   class ActionSystemTest < ActionSystemTest::Base
+    #     ActionSystemTest.driver = :rails_selenium_driver
+    #   end
     #
     # Because this driver supports real browser testing it is required that a
     # server is configured.
@@ -31,24 +33,27 @@ module ActionSystemTest
     #    >
     #
     # The settings for the <tt>RailsSeleniumDriver</tt> can be changed in the
-    # Rails configuration file.
+    # +system_test_helper+.
     #
-    #   config.system_testing.driver = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
-    #     server: :webrick,
-    #     port: 28100,
-    #     screen_size: [ 800, 800 ]
-    #   )
+    #   class ActionSystemTest < ActionSystemTest::Base
+    #     ActionSystemTest.driver = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
+    #       server: :webrick,
+    #       port: 28100,
+    #       screen_size: [ 800, 800 ]
+    #     )
+    #   end
     #
-    # 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,
+    # The default browser is set to Chrome. 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 = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
-    #     browser: :firefox
-    #   )
+    #   class ActionSystemTest < ActionSystemTest::Base
+    #     ActionSystemTest.driver = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
+    #       browser: :firefox
+    #     )
+    #   end
     class RailsSeleniumDriver
       include WebServer
 
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 3264ddc86e..1b198b9b29 100644
--- a/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb
+++ b/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb
@@ -2,14 +2,13 @@ module ActionSystemTest
   module TestHelpers
     # Screenshot helper for system testing
     module ScreenshotHelper
-      # Takes a screenshot of the current page in the browser if the system
-      # test driver supports screenshots and the test failed.
+      # Takes a screenshot of the current page in the browser.
       #
-      # Additionally +take_screenshot+ can be used within your tests at points
+      # +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 of the driver supports screenshots by running
+      # You can check if the driver supports screenshots by running
       #
       #   ActionSystemTest.driver.supports_screenshots?
       #   => true
@@ -18,6 +17,8 @@ module ActionSystemTest
         puts find_image
       end
 
+      # Takes a screenshot only if the test failed. This is included
+      # by default in +teardown+ of system test.
       def take_failed_screenshot
         take_screenshot unless passed?
       end