Browse files

Make README more terse and readable

This also takes into account that cucumber-rails now uses Capybara by
default (they dropped Webrat support a while back).
  • Loading branch information...
1 parent 897655c commit de76d8a50d48f27c356280fa2e0cdcb81e6c7500 @joliss joliss committed Dec 21, 2011
Showing with 42 additions and 80 deletions.
  1. +42 −80 README.rdoc
View
122 README.rdoc
@@ -1,62 +1,49 @@
= Capybara
-* http://github.com/jnicklas/capybara
+Capybara helps you test Rails and Rack applications by simulating how a real
+user would interact with your app. It is agnostic about the driver running your
+tests and comes with Rack::Test and Selenium support built in. WebKit is
+supported through an external gem.
-== Description:
+<b>Need help?</b> Ask on the mailing list: http://groups.google.com/group/ruby-capybara
-Capybara aims to simplify the process of integration testing Rack applications,
-such as Rails, Sinatra or Merb. Capybara simulates how a real user would
-interact with a web application. It is agnostic about the driver running your
-tests and currently comes with Rack::Test and Selenium support built in.
-WebKit is supported through external gem.
+== Setup
-A complete reference is available at
-{at rubydoc.info}[http://rubydoc.info/github/jnicklas/capybara/master].
+To install, type
-== Install:
+ sudo gem install capybara
-Install as a gem:
+If you are using Rails, add this line to your test helper file:
- sudo gem install capybara
+ require 'capybara/rails'
-On OSX you may have to install libffi, you can install it via MacPorts with:
+If you are not using Rails, set Capybara.app to your rack app:
- sudo port install libffi
+ Capybara.app = MyRackApp
-== Development:
+== Development
-* Source hosted at {GitHub}[http://github.com/jnicklas/capybara].
-* Please direct questions, discussion or problems to the {mailing list}[http://groups.google.com/group/ruby-capybara].
- Please do not open an issue on GitHub if you have a question.
-* If you found a reproducible bug, open a {GitHub Issue}[http://github.com/jnicklas/capybara/issues] to submit a bug report.
-* Please do not contact any of the maintainers directly, unless you have found a security related issue.
+If you found a _reproducible_ bug, open a {GitHub
+Issue}[http://github.com/jnicklas/capybara/issues] to submit a bug report.
-Pull requests are very welcome (and even better than bug reports)! Make sure
-your patches are well tested, Capybara is a testing tool after all. Please
-create a topic branch for every separate change you make.
+Even better, send a pull request! Make sure all changes are well tested,
+Capybara is a testing tool after all. Topic branches are good.
-Capybara uses bundler in development. To set up a development environment, simply do:
+To set up a development environment, simply do:
git submodule update --init
gem install bundler
bundle install
== Using Capybara with Cucumber
-Capybara is built to work nicely with Cucumber. Support for Capybara is built into
-cucumber-rails. In your Rails app, just run:
-
- rails generate cucumber:install --capybara
-
-And everything should be set up and ready to go.
-
-If you want to use Capybara with Cucumber outside Rails (for example with Merb
-or Sinatra), you'll need to require Capybara and set the Rack app manually:
+The <tt>cucumber-rails</tt> gem comes with Capybara support built-in. If you
+are not using Rails, manually load the <tt>capybara/cucumber</tt> module:
require 'capybara/cucumber'
Capybara.app = MyRackApp
-Now you can use it in your steps:
+You can use the Capybara DSL in your steps, like so:
When /I sign in/ do
within("#session") do
@@ -66,30 +53,30 @@ Now you can use it in your steps:
click_link 'Sign in'
end
-Capybara sets up some {tags}[https://github.com/cucumber/cucumber/wiki/tags]
-for you to use in Cucumber. Often you'll want to run only some scenarios with a
-driver that supports JavaScript, Capybara makes this easy: simply tag the
-scenario (or feature) with <tt>@javascript</tt>:
+You can switch to the <tt>Capybara.javascript_driver</tt> (<tt>:selenium</tt>
+by default) by tagging scenarios (or features) with <tt>@javascript</tt>:
@javascript
Scenario: do something Ajaxy
When I click the Ajax link
...
-You can change which driver Capybara uses for JavaScript:
-
- Capybara.javascript_driver = :webkit
-
There are also explicit <tt>@selenium</tt> and <tt>@rack_test</tt>
tags set up for you.
== Using Capybara with RSpec
-If you prefer RSpec to using Cucumber, you can use the built in RSpec support
-by adding the following line (typically to your <tt>spec_helper.rb</tt> file):
+Load RSpec 2.x support by adding the following line (typically to your
+<tt>spec_helper.rb</tt> file):
require 'capybara/rspec'
+If you are using Rails, put your Capybara specs in <tt>spec/requests</tt> or
+<tt>spec/integration</tt>.
+
+If you are not using Rails, tag all the example groups in which you want to use
+Capybara with <tt>:type => :request</tt>.
+
You can now write your specs like so:
describe "the signup process", :type => :request do
@@ -106,15 +93,9 @@ You can now write your specs like so:
end
end
-If you are using Rails, put your Capybara specs in <tt>spec/requests</tt> or
-<tt>spec/integration</tt>.
-
-If you are not using Rails, tag all the example groups in which you want to use
-Capybara with <tt>:type => :request</tt>.
-
-RSpec's metadata feature can be used to switch to a different driver. Use
-<tt>:js => true</tt> to switch to the javascript driver, or provide a
-<tt>:driver</tt> option to switch to one specific driver. For example:
+Use <tt>:js => true</tt> to switch to the <tt>Capybara.javascript_driver</tt>
+(<tt>:selenium</tt> by default), or provide a <tt>:driver</tt> option to switch
+to one specific driver. For example:
describe 'some stuff which requires js', :js => true do
it 'will use the default js driver'
@@ -137,13 +118,9 @@ Finally, Capybara also comes with a built in DSL for creating descriptive accept
end
end
-This is, in fact, just a shortcut for making a request spec, where
-<tt>feature</tt> is an alias for <tt>describe ..., :type => :request</tt>,
-<tt>background</tt> is an alias for <tt>before</tt>, and <tt>scenario</tt>
-is an alias for <tt>it</tt>/<tt>specify</tt>.
-
-Note that Capybara's built in RSpec support only works with RSpec 2.0 or later.
-You'll need to roll your own for earlier versions of RSpec.
+<tt>feature</tt> is in fact just an alias for <tt>describe ..., :type =>
+:request</tt>, <tt>background</tt> is an alias for <tt>before</tt>, and
+<tt>scenario</tt> for <tt>it</tt>.
== Using Capybara with Test::Unit
@@ -170,20 +147,6 @@ expectations for Capybara. For example:
page.must_have_content('Important!')
-== Using Capybara with Ruby on Rails
-
-If you are using the Rails framework, add this line to automatically configure
-Capybara to test against your Rails application:
-
- require 'capybara/rails'
-
-== Using Capybara with Rack
-
-If you're using Capybara with a non-Rails Rack application, set
-<tt>Capybara.app</tt> to your application class:
-
- Capybara.app = MyRackApp
-
== Drivers
Capybara uses the same DSL to drive a variety of browser and headless drivers.
@@ -265,14 +228,13 @@ And you can use it by:
Capybara.javascript_driver = :webkit
-
== The DSL
-Capybara's DSL (domain-specific language) is inspired by Webrat. While
-backwards compatibility is retained in a lot of cases, there are certain
-important differences. Unlike in Webrat, all searches in Capybara are *case
-sensitive*. This is because Capybara heavily uses XPath, which doesn't support
-case insensitivity.
+A complete reference is available at
+{at rubydoc.info}[http://rubydoc.info/github/jnicklas/capybara/master].
+
+Note: All searches in Capybara are <b>case sensitive</b>. This is because
+Capybara heavily uses XPath, which doesn't support case insensitivity.
=== Navigating

0 comments on commit de76d8a

Please sign in to comment.