From 2c26bc8dabf9cd36c80bc47cffdc3c7d9fd29007 Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Mon, 24 Nov 2008 23:30:10 -0500 Subject: [PATCH] Updating and improve README (Bryan Helmkamp / Mike Gaffney) --- README.rdoc | 95 +++++++++++++++++++++-------------------------------- 1 file changed, 38 insertions(+), 57 deletions(-) diff --git a/README.rdoc b/README.rdoc index 5f46d734..477aecb8 100644 --- a/README.rdoc +++ b/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 + +Behind the scenes, Webrat will ensure: -== Install +* 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. -To install the latest release: +== Install for Rails - sudo gem install webrat +To install the latest release as a gem: -In your stories/helper.rb: + sudo gem install webrat - require "webrat" +To install the latest code as a plugin: (_Note:_ This may be less stable than using a released version) + + script/plugin install git://github.com/brynary/webrat.git + +In your test_helper.rb, spec_helper.rb, or env.rb (for Cucumber) add: + + require "webrat/rails" -You could also unpack the gem into vendor/plugins. +== 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. -See MIT-LICENSE.txt in this directory. +Copyright (c) 2007-2008 Bryan Helmkamp, Seth Fitzsimmons. +See MIT-LICENSE.txt in this directory. \ No newline at end of file