Updating and improve README (Bryan Helmkamp / Mike Gaffney)

README.rdoc

@@ -7,85 +7,66 @@
 
 == Description
 
-Webrat lets you quickly write robust and thorough acceptance tests for a Ruby
-web application. By leveraging the DOM, it can run tests similarly to an
-in-browser testing solution without the associated performance hit (and
-browser dependency). The result is tests that are less fragile and more
-effective at verifying that the app will respond properly to users.
+Webrat lets you quickly write expressive and robust acceptance tests for a Ruby
+web application. 
 
-When comparing Webrat with an in-browser testing solution like Watir or
-Selenium, the primary consideration should be how much JavaScript the
-application uses. In-browser testing is currently the only way to test JS, and
-that may make it a requirement for your project. If JavaScript is not central
-to your application, Webrat is a simpler, effective solution that will let you
-run your tests much faster and more frequently.
+== Features
 
-Initial development was sponsored by EastMedia[http://www.eastmedia.com].
+* 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)
+* 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.
 
-== Synopsis
+== Example
 
-    def test_sign_up
-      visit "/"
+  class SignupTest < ActionController::IntegrationTest
+  
+    def test_trial_account_sign_up
+      visit home_path
       click_link "Sign up"
       fill_in "Email", :with => "good@example.com"
       select "Free account"
       click_button "Register"
-      ...
     end
     
-Behind the scenes, this will perform the following work:
-
-1. Verify that loading the home page is successful
-2. Verify that a "Sign up" link exists on the home page
-3. Verify that loading the URL pointed to by the "Sign up" link leads to a
-   successful page
-4. Verify that there is an "Email" input field on the Sign Up page
-5. Verify that there is an select field on the Sign Up page with an option for
-   "Free account"
-6. Verify that there is a "Register" submit button on the page
-7. Verify that submitting the Sign Up form with the values "good@example.com"
-   and "Free account" leads to a successful page
-
-Take special note of the things _not_ specified in that test, that might cause
-tests to break unnecessarily as your application evolves:
-
-- The input field IDs or names (e.g. "user_email" or "user[email]"), which
-  could change if you rename a model
-- The ID of the form element (Webrat can do a good job of guessing, even if
-  there are multiple forms on the page.)
-- The URLs of links followed
-- The URL the form submission should be sent to, which could change if you
-  adjust your routes or controllers
-- The HTTP method for the login request
-
-A test written with Webrat can handle these changes to these without any modifications.
-
-== Merb
-To avoid losing sessions, you need this in environments/test.rb:
-
-  Merb::Config.use do |c|
-    c[:session_store] = 'memory' 
   end
   
-== Install
+Behind the scenes, Webrat will ensure:
 
-To install the latest release:
+* If a link, form field or button is missing, the test will fail.
+* If a URL is invalid, the test will fail.
+* If a page load or form submission is unsuccessful, the test will fail.
+
+== Install for Rails
+
+To install the latest release as a gem:
 
   sudo gem install webrat
   
-In your stories/helper.rb:
+To install the latest code as a plugin: (_Note:_ This may be less stable than using a released version)
 
-    require "webrat"
+  script/plugin install git://github.com/brynary/webrat.git
 
-You could also unpack the gem into vendor/plugins.
+In your test_helper.rb, spec_helper.rb, or env.rb (for Cucumber) add:
+
+  require "webrat/rails"
+  
+== Install with Merb
+
+Merb 1.0 has built-in, seamless Webrat support. Just start using
+methods from Webrat::Session in your specs.
 
 == Authors
 
 - Maintained by {Bryan Helmkamp}[mailto:bryan@brynary.com]
 - Original code written by {Seth Fitzsimmons}[mailto:seth@mojodna.net]
+- Initial development was sponsored by EastMedia[http://www.eastmedia.com]
 - Many other contributors. See attributions in History.txt
 
 == License
 
-Copyright (c) 2007 Bryan Helmkamp, Seth Fitzsimmons.
+Copyright (c) 2007-2008 Bryan Helmkamp, Seth Fitzsimmons.
 See MIT-LICENSE.txt in this directory.