Add docs for Webrat::Selenium

README.rdoc

@@ -16,7 +16,7 @@ web application.
 * Browser Simulator for expressive, high level acceptance testing without the
   performance hit and browser dependency of Selenium or Watir (See Webrat::Session)
 * Use the same API for Browser Simulator and real Selenium tests using
-  Webrat::SeleniumSession when necessary (eg. for testing AJAX interactions)
+  Webrat::Selenium when necessary (eg. for testing AJAX interactions)
 * Supports multiple Ruby web frameworks: Rails, Merb and Sinatra
 * Supports popular test frameworks: RSpec, Cucumber, Test::Unit and Shoulda
 * Webrat::Matchers API for verifying rendered HTML using CSS, XPath, etc.

lib/webrat/selenium.rb

@@ -36,7 +36,44 @@ def self.stop_app_server #:nodoc:
     system "mongrel_rails stop -c #{RAILS_ROOT} --pid #{pid_file}"
   end
 
-  module Selenium #:nodoc:
+  # To use Webrat's Selenium support, you'll need the selenium-client gem installed.
+  # Activate it with (for example, in your <tt>env.rb</tt>):
+  #
+  #   require "webrat/selenium"
+  # 
+  # Then, if you're using Cucumber, configure it to use a 
+  # <tt>Webrat::Selenium::Rails::World</tt> as the scenario context by adding
+  # the following to <tt>env.rb</tt>:
+  #
+  #   World do
+  #     Webrat::Selenium::Rails::World.new
+  #   end
+  #
+  # == Dropping down to the selenium-client API
+  #
+  # If you ever need to do something with Selenium not provided in the Webrat API,
+  # you can always drop down to the selenium-client API using the <tt>selenium</tt> method.
+  # For example:
+  #
+  #   When "I drag the photo to the left" do
+  #     selenium.dragdrop("id=photo_123", "+350, 0")
+  #   end
+  #
+  # == Auto-starting of the mongrel and java server
+  #
+  # Webrat will automatically start the Selenium Java server process and an instance
+  # of Mongrel when a test is run. The Mongrel will run in the "selenium" environment
+  # instead of "test", so ensure you've got that defined, and will run on port 3001.
+  #
+  # == Waiting
+  #
+  # In order to make writing Selenium tests as easy as possible, Webrat will automatically
+  # wait for the correct elements to exist on the page when trying to manipulate them
+  # with methods like <tt>fill_in</tt>, etc. In general, this means you should be able to write
+  # your Webrat::Selenium tests ignoring the concurrency issues that can plague in-browser
+  # testing, so long as you're using the Webrat API.
+  module Selenium
+
     module Rails #:nodoc:
       class World < ::ActionController::IntegrationTest