nimboids-capybara 1.1.2

data/History.txt

@@ -0,0 +1,289 @@
+# Version 1.1.0
+
+Release date: 2011-09-02
+
+### Fixed
+
+* Sensible inspect for Capybara::Session [Jo Liss]
+* Fix headers and host on redirect [Matt Colyer, Jonas Nicklas, Kim Burgestrand]
+* using_driver now restores the old driver instead of reverting to the default [Carol Nichols]
+* Errors when following links relative to the root path under rack-test [Jonas Nicklas, Kim Burgestrand]
+* Make sure exit codes are propagated properly [Edgar Beigarts]
+
+### Changed
+
+* resynchronization is off by default under Selenium
+
+### Added
+
+* Elements are automatically reloaded (including parents) during wait [Jonas Nicklas]
+* Rescue driver specific element errors, such as the dreaded ObsoleteElementError and retry [Jonas Nicklas]
+* Raise an error if something has frozen time [Jonas Nicklas]
+* Allow within to take a node instead of a selector [Peter Williams]
+* Using wait_time_time to change wait time for a block of code [Jonas Nicklas, Kim Burgestrand]
+* Option for rack-test driver to disable data-method hack [Jonas Nicklas, Kim Burgestrand]
+
+# Version 1.0.1
+
+Release date: 2011-08-12
+
+### Fixed
+
+* Dependend on selenium-webdriver ~>2.0 and fix deprecations [Thomas Walpole, Jo Liss]
+* Depend on Launch 2.0 [Jeremy Hinegardner]
+* Rack-Test ignores fill in on fields with maxlength=""
+
+# Version 1.0.0
+
+Release date: 2011-06-14
+
+### Added
+
+* Added DSL for acceptance tests, inspired by Luismi Cavallé's Steak [Luismi Cavalle and Jonas Nicklas]
+* Selenium driver automatically waits for AJAX requests to finish [mgiambalvo, Nicklas Ramhöj and Jonas Nicklas]
+* Support for switching between multiple named sessions [Tristan Dunn]
+* failure_message can be specified for Selectors [Jonas Nicklas]
+* RSpec matchers [David Chelimsky and Jonas Nicklas]
+* Added save_page to save tempfile without opening in browser [Jeff Kreeftmeijer]
+* Cucumber now switches automatically to a registered driver if the tag matches the name [Jonas Nicklas]
+* Added Session#text [Jonas Nicklas and Scott Cytacki]
+* Added Session#html as an alias for Session#body [Jo Liss]
+* Added Session#current_host method [Jonas Nicklas]
+* Buttons can now be clicked by title [Javier Martin]
+* :headers option for RackTest driver to set custom HTTP headers [Jonas Nicklas]
+
+### Removed
+
+* Culerity and Celerity drivers have been removed and split into separate gems [Gabriel Sobrinho]
+
+### Deprecated
+
+* `include Capybara` has been deprecated in favour of `include Capybara::DSL` [Jonas Nicklas]
+
+### Changed
+
+* Rack test driver class has been renamed from Capybara::Driver::RackTest to Capybara::RackTest::Driver [Jonas Nicklas]
+* Selenium driver class has been renamed from Capybara::Driver::Selenium to Capybara::Selenium::Driver [Jonas Nicklas]
+* Capybara now prefers visible elements over hidden elements, disable by setting Capybara.prefer_visible_elements = false [Jonas Nicklas and Nicklas Ramhöj]
+* For RSpec, :type => :request is now supported (and preferred over :acceptance) [Jo Liss]
+* Selenium driver tried to wait for AJAX requests to finish before proceeding [Jonas Nicklas and Nicklas Ramhöj]
+* Session no longer uses method missing, uses explicit delegates instead [Jonas Nicklas]
+
+### Fixed
+
+* The Rack::Test driver now respects maxlength on text fields [Guilherme Carvalho]
+* Allow for more than one save_and_open_page call per second [Jo Liss]
+* Automatically convert options to :count, :minimum, :maximum, etc. to integers [Keith Marcum]
+* Rack::Test driver honours maxlength on input fields [Guilherme Carvalho]
+* Rack::Test now works as expected with domains and subdomains [Jonas Nicklas]
+* Session is reset more thoroughly between tests. [Jonas Nicklas]
+* Raise error when uploading non-existant file [Jonas Nicklas]
+* Rack reponse body should respond to #each [Piotr Sarnacki]
+* Deprecation warnings with selenium webdriver 0.2.0 [Aaron Gibraltar]
+* Selenium Chrome no longer YELLS tagname [Carl Jackson & David W. Frank]
+* Capybara no longer strips encoding before sending to Rack [Jonas Nicklas]
+* Improve handling of relative URLs [John Barton]
+* Readd and fix build_rack_mock_session [Jonas Nicklas, Jon Leighton]
+
+# Version 0.4.1
+
+Release date: 2011-01-21
+
+### Added
+
+* New click_on alias for click_link_or_button, shorter yet unambiguous. [Jonas Nicklas]
+* Finders now accept :visible => false which will find all elements regardless of Capybara.ignore_hidden_elements [Jonas Nicklas]
+* Configure how the server is started via Capybara.server { |app, port| ... }. [John Firebough]
+* Added :between, :maximum and :minimum options to has_selector and friends [James B. Byrne]
+* New Capybara.string util function which allows matchers on arbitrary strings, mostly for helper and view specs [David Chelimsky and Jonas Nicklas]
+* Server boot timeout is now configurable, via Capybara.server_boot_timeout [Adam Cigánek]
+* Built in support for RSpec [Jonas Nicklas]
+* Capybara.using_driver to switch to a different driver temporarily [Jeff Kreeftmeijer]
+* Added Session#first which is somewhat speedier than Session#all, use it internally for speed boost [John Firebaugh]
+
+### Changed
+
+* Session#within now accepts the same arguments as other finders, like Session#all and Session#find [Jonas Nicklas]
+
+### Removed
+
+* All deprecations from 0.4.0 have been removed. [Jonas Nicklas]
+
+### Fixed
+
+* Don't mangle URLs in save_and_open_page when using self-closing tags [Adam Spiers]
+* Catch correct error when server boot times out [Jonas Nicklas]
+* Celerity driver now properly passes through options, making it configurable [Jonas Nicklas]
+* Better implementation of attributes in C[ue]lerity, should fix issues with attributes with strange names [Jonas Nicklas]
+* Session#find no longer swallows errors [Jonas Nicklas]
+* Fix problems with multiple file inputs [Philip Arndt]
+* Submit multipart forms as multipart under rack-test even if they contain no files [Ryan Kinderman]
+* Matchers like has_select? and has_checked_field? now work with dynamically changed values [John Firebaugh]
+* Preserve order of rack params [Joel Chippindale]
+* RackTest#reset! is more thorough [Joel Chippindale]
+
+# Version 0.4.0
+
+Release date: 2010-10-22
+
+### Changed
+
+* The Selector API was changed slightly, use Capybara.add_selector, see README
+
+### Fixed
+
+* Celerity driver is registered properly
+* has_selector? and has_no_selector? added to DSL
+* Multiple selects return correct values under C[cu]lerity
+* Naked query strings are handled correctly by rack-test
+
+# Version 0.4.0.rc
+
+Release date: 2010-10-12
+
+### Changed
+
+* within and find/locate now follow the XPath spec in that //foo finds all nodes in the document, instead of
+  only for the context node. See this post for details: http://groups.google.com/group/ruby-capybara/browse_thread/thread/b129067979df21b3
+* within now executes within the first found instance of the selector, not in all of them
+* find now waits for AJAX requests and raises an exception when the element is not found (same as locate used to do)
+* The default selector is now CSS, not XPath
+
+### Deprecated
+
+* Session#click has been renamed click_link_or_button and the old click has been deprecated
+* Node#node has been renamed native
+* Node#locate is deprecated in favor of Node#find, which now behaves identically
+* Session#drag is deprecated, please use Node#drag_to(other_node) instead
+
+### Added
+
+* Pretty much everything is properly documented now
+* It's now possible to call all session methods on nodes, like `find('#foo').fill_in(...)`
+* Custom selectors can be added with Capybara::Selector.add
+* The :id selector is added by default, use it lile `find(:id, 'foo')` or `find(:foo)`
+* Added Node#has_selector? so any kind of selector can be queried.
+* Added Capybara.configure for less wordy configuration
+* Added within_window to switch between different windows (currently Selenium only)
+* Capybara.server_port to provide a fixed port if wanted (defaults to automatic selection)
+
+### Fixed
+
+* CSS selectors with multiple selectors, such as "h1, h2" now work correctly
+* Port is automatically assigned instead of guessing
+* Strip encodings in rack-test, no more warnings!
+* RackTest no longer submits disabled fields
+* Servers no longer output annoying debug information when started
+* TCP port selection is left to Ruby to decide, no more port guessing
+* Select boxes now return option value instead of text if present
+* The default has been changed from localhost to 127.0.0.1, should fix some obscure selenium bugs
+* RackTest now supports complex field names, such as foo[bar][][baz]
+
+# Version 0.3.9
+
+Release date: 2010-07-03
+
+### Added
+
+* status_code which returns the HTTP status code of the last response (no Selenium!)
+* Capybara.save_and_open_page to store tempfiles
+* RackTest and Culerity drivers now clean up after themselves properly
+
+### Fixed
+
+* When no rack app is set and the app is called, a more descriptive error is raised
+* select now works with optgroups
+* Don't submit image buttons unless they were clicked under rack-test
+* Support custom field types under Selenium
+* Support input fields without a type, treat them as though they were text fields
+* Redirect now throws an error after 5 redirects, as per RFC
+* Selenium now properly raises an error when Node#trigger is called
+* Node#value now returns the correct value for textareas under rack-test
+
+# Version 0.3.8
+
+Release date: 2010-05-12
+
+### Added
+
+* Within_frame method to execute a block of code within a particular iframe (Selenium only!)
+
+### Fixed
+
+* Single quotes are properly escaped with `select` under rack-test and Selenium.
+* The :text option for searches now escapes regexp special characters when a string is given.
+* Selenium now correctly checks already checked checkboxes (same with uncheck)
+* Timing issue which caused Selenium to hang under certain circumstances.
+* Selenium now resolves attributes even if they are given as a Symbol
+
+# Version 0.3.7
+
+Release date: 2010-04-09
+
+This is a drop in compatible maintainance release. It's mostly
+important for driver authors.
+
+### Added
+
+* RackTest scans for data-method which rails3 uses to change the request method
+
+### Fixed
+
+* Don't hang when starting server on Windoze
+
+### Changed
+
+* The driver and session specs are now located inside lib! Driver authors can simply require them.
+
+# Version 0.3.6
+
+Release date: 2010-03-22
+
+This is a maintainance release with minor bug fixes, should be
+drop in compatible.
+
+### Added
+
+* It's now possible to load in external drivers
+
+### Fixed
+
+* has_content? ignores whitespace
+* Trigger events when choosing radios and checking checkboxes under Selenium
+* Make Capybara.app totally optional when running without server
+* Changed fallback host so it matches the one set up by Rails' integration tests
+
+# Version 0.3.5
+
+Release date: 2010-02-26
+
+This is a mostly backwards compatible release, it does break
+the API in some minor places, which should hopefully not affect
+too many users, please read the release notes carefully!
+
+### Breaking
+
+* Relative searching in a node (e.g. find('//p').all('//a')) will now follow XPath standard
+  this means that if you want to find descendant nodes only, you'll need to prefix a dot!
+* `visit` now accepts fully qualified URLs for drivers that support it.
+* Capybara will always try to run a rack server, unless you set Capybara.run_sever = false
+
+### Changed
+
+* thin is preferred over mongrel and webrick, since it is Ruby 1.9 compatible
+* click_button and click will find <input type="button">, clicking them does nothing in RackTest
+
+### Added
+
+* Much improved error messages in a multitude of places
+* More semantic page querying with has_link?, has_button?, etc...
+* Option to ignore hidden elements when querying and interacting with the page
+* Support for multiple selects
+
+### Fixed
+
+* find_by_id is no longer broken
+* clicking links where the image's alt attribute contains the text is now possible
+* within_fieldset and within_table work when the default selector is CSS
+* boolean attributes work the same across drivers (return true/false)
+

data/README.rdoc

@@ -0,0 +1,722 @@
+= Capybara
+
+* http://github.com/jnicklas/capybara
+
+== Description:
+
+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.
+HtmlUnit, WebKit and env.js are supported through external gems.
+
+A complete reference is available at
+{at rubydoc.info}[http://rubydoc.info/github/jnicklas/capybara/master].
+
+== Install:
+
+Install as a gem:
+
+    sudo gem install capybara
+
+On OSX you may have to install libffi, you can install it via MacPorts with:
+
+    sudo port install libffi
+
+== 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].
+* 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.
+
+Capybara uses bundler in development. 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:
+
+    require 'capybara/cucumber'
+    Capybara.app = MyRackApp
+
+Now you can use it in your steps:
+
+    When /I sign in/ do
+      within("#session") do
+        fill_in 'Login', :with => 'user@example.com'
+        fill_in 'Password', :with => 'password'
+      end
+      click_link 'Sign in'
+    end
+
+Capybara sets up some {tags}[http://wiki.github.com/aslakhellesoy/cucumber/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>:
+
+    @javascript
+    Scenario: do something Ajaxy
+      When I click the Ajax link
+      ...
+
+You can change which driver Capybara uses for JavaScript:
+
+    Capybara.javascript_driver = :culerity
+
+There are also explicit <tt>@selenium</tt>, <tt>@culerity</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):
+
+    require 'capybara/rspec'
+
+You can now write your specs like so:
+
+    describe "the signup process", :type => :request do
+      before :each do
+        User.make(:email => 'user@example.com', :password => 'caplin')
+      end
+
+      it "signs me in" do
+        within("#session") do
+          fill_in 'Login', :with => 'user@example.com'
+          fill_in 'Password', :with => 'password'
+        end
+        click_link 'Sign in'
+      end
+    end
+
+Capybara is only included in example groups tagged with
+<tt>:type => :request</tt> (or <tt>:acceptance</tt> for compatibility with Steak).
+
+If you are testing a Rails app and using the <tt>rspec-rails</tt> gem, these
+<tt>:request</tt> example groups may look familiar to you. That's because they
+are RSpec versions of Rails integration tests. So, in this case essentially what you are getting are Capybara-enhanced request specs. This means that you can
+use the Capybara helpers <i>and</i> you have access to things like named route
+helpers in your tests (so you are able to say, for instance, <tt>visit
+edit_user_path(user)</tt>, instead of <tt>visit "/users/#{user.id}/edit"</tt>,
+if you prefer that sort of thing). A good place to put these specs is
+<tt>spec/requests</tt>, as <tt>rspec-rails</tt> will automatically tag them with
+<tt>:type => :request</tt>. (In fact, <tt>spec/integration</tt> and
+<tt>spec/acceptance</tt> will work just as well.)
+
+<tt>rspec-rails</tt> will also automatically include Capybara in <tt>:controller</tt> and <tt>:mailer</tt> example groups.
+
+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:
+
+    describe 'some stuff which requires js', :js => true do
+      it 'will use the default js driver'
+      it 'will switch to one specific driver', :driver => :celerity
+    end
+
+Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:
+
+    feature "Signing up" do
+      background do
+        User.make(:email => 'user@example.com', :password => 'caplin')
+      end
+
+      scenario "Signing in with correct credentials" do
+        within("#session") do
+          fill_in 'Login', :with => 'user@example.com'
+          fill_in 'Password', :with => 'caplin'
+        end
+        click_link 'Sign in'
+      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.
+
+== Using Capybara with Test::Unit
+
+To use Capybara with Test::Unit, include the DSL (<tt>include Capybara</tt> up
+until version 0.4.x, <tt>include Capybara::DSL</tt> for newer versions) in
+whatever test class you are using.  For example, if your classes derive from
+<tt>ActionDispatch::IntegrationTest</tt>, use
+
+    class ActionDispatch::IntegrationTest
+      include Capybara::DSL
+    end
+
+Test::Unit does not support selecting the driver through test metadata, but you
+can switch the driver for specific classes using the <tt>setup</tt> and
+<tt>teardown</tt> methods.  See the section "Selecting the Driver".
+
+== 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.
+
+=== Selecting the Driver
+
+By default, Capybara uses the <tt>:rack_test</tt> driver, which is fast but does not
+support JavaScript.  You can set up a different default driver for your
+features. For example if you'd prefer to run everything in Selenium, you could
+do:
+
+    Capybara.default_driver = :selenium
+
+However, if you are using RSpec or Cucumber, you may instead want to consider
+leaving the faster <tt>:rack_test</tt> as the +default_driver+, and marking only those
+tests that require a JavaScript-capable driver using <tt>:js => true</tt> or
+<tt>@javascript</tt>, respectively.  By default, JavaScript tests are run using the
+<tt>:selenium</tt> driver.  You can change this by setting
+<tt>Capybara.javascript_driver</tt>.
+
+You can also change the driver temporarily (typically in the Before/setup and
+After/teardown blocks):
+
+    Capybara.current_driver = :culerity  # temporarily select different driver
+    ... tests ...
+    Capybara.use_default_driver  # switch back to default driver
+
+Note that switching the driver creates a new session, so you may not be able to
+switch in the middle of a test.
+
+=== RackTest
+
+RackTest is Capybara's default driver. It is written in pure Ruby and does not
+have any support for executing JavaScript. Since the RackTest driver works
+directly agains the Rack interface, it does not need any server to be started,
+it can work directly work against any Rack app. This means that if your
+application is not a Rack application (Rails, Sinatra and most other Ruby
+frameworks are Rack applications) then you cannot use this driver. You cannot
+use the RackTest driver to test a remote application.
+{capybara-mechanize}[https://github.com/jeroenvandijk/capybara-mechanize]
+intends to provide a similar driver which works against remote servers, it is a
+separate project.
+
+RackTest can be configured with a set of headers like this:
+
+    Capybara.register_driver :rack_test do |app|
+      Capybara::RackTest::Driver.new(app, :browser => :chrome)
+    end
+
+See the section on adding and configuring drivers.
+
+=== Selenium
+
+At the moment, Capybara supports {Selenium 2.0
+(Webdriver)}[http://seleniumhq.org/docs/01_introducing_selenium.html#selenium-2-aka-selenium-webdriver],
+*not* Selenium RC. Provided Firefox is installed, everything is set up for you,
+and you should be able to start using Selenium right away.
+
+Capybara can block and wait for Ajax requests to finish after you've interacted
+with the page. To enable this behaviour, set the <tt>:resynchronize</tt> driver
+option to <tt>true</tt>. This should normally not be necessary, since
+Capybara's automatic reloading should take care of any asynchronicity problems.
+See the section on Asynchronous JavaScript for details.
+
+Note: Selenium does not support transactional fixtures; see the section
+"Transactional Fixtures" below.
+
+=== HtmlUnit
+
+There are three different drivers, maintained as external gems, that you can
+use to drive {HtmlUnit}[http://htmlunit.sourceforge.net/]:
+
+* {Akephalos}[https://github.com/bernerdschaefer/akephalos] might be the best
+  HtmlUnit driver right now.
+
+* {Celerity}[https://github.com/sobrinho/capybara-celerity] only runs on JRuby,
+  so you'll need to install the celerity gem under JRuby: <tt>jruby -S gem
+  install celerity</tt>
+
+* {Culerity}[https://github.com/sobrinho/capybara-culerity]: Install celerity
+  as noted above, and make sure that JRuby is in your path. Note that Culerity
+  does not seem to be working under Ruby 1.9 at the moment.
+
+Note: HtmlUnit does not support transactional fixtures; see the section
+"Transactional Fixtures" below.
+
+=== env.js
+
+The {capybara-envjs driver}[http://github.com/smparkes/capybara-envjs]
+uses the envjs gem ({GitHub}[http://github.com/smparkes/env-js],
+{rubygems.org}[http://rubygems.org/gems/envjs]) to interpret
+JavaScript outside the browser. The driver is installed by installing the capybara-envjs gem:
+
+  gem install capybara-envjs
+
+More info about the driver and env.js are available through the links above. The envjs gem only supports
+Ruby 1.8.7 at this time.
+
+Note: Envjs does not support transactional fixtures; see the section
+"Transactional Fixtures" below.
+
+=== Capybara-webkit
+
+The {capybara-webkit drive}[https://github.com/thoughtbot/capybara-webkit] is for true headless
+testing. It uses WebKitQt to start a rendering engine process. It can execute JavaScript as well.
+It is significantly faster than drivers like Selenium since it does not load an entire browser.
+
+You can install it with:
+
+  gem install capybara-webkit
+
+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.
+
+=== Navigating
+
+You can use the
+<tt>{visit}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#visit-instance_method]</tt>
+method to navigate to other pages:
+
+    visit('/projects')
+    visit(post_comments_path(post))
+
+The visit method only takes a single parameter, the request method is *always*
+GET.
+
+You can get the {current
+path}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#current_path-instance_method]
+of the browsing session for test assertions:
+
+    current_path.should == post_comments_path(post)
+
+=== Clicking links and buttons
+
+<em>Full reference: {Capybara::Node::Actions}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions]</em>
+
+You can interact with the webapp by following links and buttons. Capybara
+automatically follows any redirects, and submits forms associated with buttons.
+
+    click_link('id-of-link')
+    click_link('Link Text')
+    click_button('Save')
+    click_on('Link Text')  # clicks on either links or buttons
+    click_on('Button Value')
+
+=== Interacting with forms
+
+<em>Full reference: {Capybara::Node::Actions}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions]</em>
+
+There are a number of tools for interacting with form elements:
+
+    fill_in('First Name', :with => 'John')
+    fill_in('Password', :with => 'Seekrit')
+    fill_in('Description', :with => 'Really Long Text...')
+    choose('A Radio Button')
+    check('A Checkbox')
+    uncheck('A Checkbox')
+    attach_file('Image', '/path/to/image.jpg')
+    select('Option', :from => 'Select Box')
+
+=== Querying
+
+<em>Full reference: {Capybara::Node::Matchers}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Matchers]</em>
+
+Capybara has a rich set of options for querying the page for the existence of
+certain elements, and working with and manipulating those elements.
+
+    page.has_selector?('table tr')
+    page.has_selector?(:xpath, '//table/tr')
+    page.has_no_selector?(:content)
+
+    page.has_xpath?('//table/tr')
+    page.has_css?('table tr.foo')
+    page.has_content?('foo')
+
+You can use these with RSpec's magic matchers:
+
+    page.should have_selector('table tr')
+    page.should have_selector(:xpath, '//table/tr')
+    page.should have_no_selector(:content)
+
+    page.should have_xpath('//table/tr')
+    page.should have_css('table tr.foo')
+    page.should have_content('foo')
+    page.should have_no_content('foo')
+
+Note that <tt>page.should have_no_xpath</tt> is preferred over
+<tt>page.should_not have_xpath</tt>. Read the section on asynchronous JavaScript
+for an explanation.
+
+If all else fails, you can also use the
+<tt>{page.html}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#html-instance_method]</tt>
+method to test against the raw HTML:
+
+    page.html.should match /<span>.../i
+
+=== Finding
+
+<em>Full reference: {Capybara::Node::Finders}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Finders]</em>
+
+You can also find specific elements, in order to manipulate them:
+
+    find_field('First Name').value
+    find_link('Hello').visible?
+    find_button('Send').click
+
+    find(:xpath, "//table/tr").click
+    find("#overlay").find("h1").click
+    all('a').each { |a| a[:href] }
+
+Note that <tt>find</tt> will wait for an element to appear on the page, as explained in the
+Ajax section. If the element does not appear it will raise an error.
+
+These elements all have all the Capybara DSL methods available, so you can restrict them
+to specific parts of the page:
+
+    find('#navigation').click_link('Home')
+    find('#navigation').should have_button('Sign out')
+
+=== Scoping
+
+Capybara makes it possible to restrict certain actions, such as interacting with
+forms or clicking links and buttons, to within a specific area of the page. For
+this purpose you can use the generic
+<tt>{within}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session#within-instance_method]</tt>
+method. Optionally you can specify which kind of selector to use.
+
+    within("li#employee") do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+    within(:xpath, "//li[@id='employee']") do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+Note that <tt>within</tt> will scope the actions to the _first_ (not _any_)
+element that matches the selector.
+
+There are special methods for restricting the scope to a specific fieldset,
+identified by either an id or the text of the fieldet's legend tag, and to a
+specific table, identified by either id or text of the table's caption tag.
+
+    within_fieldset('Employee') do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+    within_table('Employee') do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+=== Scripting
+
+In drivers which support it, you can easily execute JavaScript:
+
+    page.execute_script("$('body').empty()")
+
+For simple expressions, you can return the result of the script. Note
+that this may break with more complicated expressions:
+
+    result = page.evaluate_script('4 + 4');
+
+=== Debugging
+
+It can be useful to take a snapshot of the page as it currently is and take a
+look at it:
+
+    save_and_open_page
+
+== Transactional fixtures
+
+Transactional fixtures only work in the default Rack::Test driver, but not for
+other drivers like Selenium.  Cucumber takes care of this automatically, but
+with Test::Unit or RSpec, you may have to use the
+{database_cleaner}[https://github.com/bmabey/database_cleaner] gem.  See {this
+explanation}[https://groups.google.com/d/msg/ruby-capybara/JI6JrirL9gM/R6YiXj4gi_UJ]
+(and code for {solution
+2}[http://opinionated-programmer.com/2011/02/capybara-and-selenium-with-rspec-and-rails-3/#comment-220]
+and {solution 3}[http://pastie.org/1745020]) for details.
+
+== Asynchronous JavaScript (Ajax and friends)
+
+When working with asynchronous JavaScript, you might come across situations
+where you are attempting to interact with an element which is not yet present
+on the page. Capybara automatically deals with this by waiting for elements
+to appear on the page.
+
+When issuing instructions to the DSL such as:
+
+    click_link('foo')
+    click_link('bar')
+    page.should have_content('baz')
+
+If clicking on the *foo* link triggers an asynchronous process, such as
+an Ajax request, which, when complete will add the *bar* link to the page,
+clicking on the *bar* link would be expected to fail, since that link doesn't
+exist yet. However Capybara is smart enought to retry finding the link for a
+brief period of time before giving up and throwing an error. The same is true of
+the next line, which looks for the content *baz* on the page; it will retry
+looking for that content for a brief time. You can adjust how long this period
+is (the default is 2 seconds):
+
+    Capybara.default_wait_time = 5
+
+Be aware that because of this behaviour, the following two statements are *not*
+equivalent, and you should *always* use the latter!
+
+    page.should_not have_xpath('a')
+    page.should have_no_xpath('a')
+
+The former would incorrectly wait for the content to appear, since the
+asynchronous process has not yet removed the element from the page, it would
+therefore fail, even though the code might be working correctly. The latter
+correctly waits for the element to disappear from the page.
+
+Capybara's waiting behaviour is quite advanced, and can deal with situations
+such as the following line of code:
+
+    find('#sidebar').find('h1').should have_content('Something')
+
+Even if JavaScript causes <tt>#sidebar</tt> to disappear off the page, Capybara
+will automatically reload it and any elements it contains. So if an AJAX
+request causes the contents of <tt>#sidebar</tt> to change, which would update
+the text of the <tt>h1</tt> to "Something", and this happened, this test would
+pass. If you do not want this behaviour, you can set
+<tt>Capybara.automatic_reload</tt> to <tt>false</tt>.
+
+== Using the DSL in unsupported testing frameworks
+
+You can mix the DSL into any context by including +Capybara::DSL+:
+
+
+    require 'capybara'
+    require 'capybara/dsl'
+
+    Capybara.default_driver = :culerity
+
+    module MyModule
+      include Capybara::DSL
+
+      def login!
+        within("//form[@id='session']") do
+          fill_in 'Login', :with => 'user@example.com'
+          fill_in 'Password', :with => 'password'
+        end
+        click_link 'Sign in'
+      end
+    end
+
+== Calling remote servers
+
+Normally Capybara expects to be testing an in-process Rack application, but you
+can also use it to talk to a web server running anywhere on the internets, by
+setting app_host:
+
+    Capybara.current_driver = :selenium
+    Capybara.app_host = 'http://www.google.com'
+    ...
+    visit('/')
+
+Note that the default driver (<tt>:rack_test</tt>) does not support running
+against a remote server. With drivers that support it, you can also visit any
+URL directly:
+
+    visit('http://www.google.com')
+
+By default Capybara will try to boot a rack application automatically. You
+might want to switch off Capybara's rack server if you are running against a
+remote application:
+
+    Capybara.run_server = false
+
+== Using the sessions manually
+
+For ultimate control, you can instantiate and use a
+{Session}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session]
+manually.
+
+    require 'capybara'
+
+    session = Capybara::Session.new(:culerity, my_rack_app)
+    session.within("//form[@id='session']") do
+      session.fill_in 'Login', :with => 'user@example.com'
+      session.fill_in 'Password', :with => 'password'
+    end
+    session.click_link 'Sign in'
+
+== XPath, CSS and selectors
+
+Capybara does not try to guess what kind of selector you are going to give it,
+and will always use CSS by default.  If you want to use XPath, you'll need to
+do:
+
+    within(:xpath, '//ul/li') { ... }
+    find(:xpath, '//ul/li').text
+    find(:xpath, '//li[contains(.//a[@href = "#"]/text(), "foo")]').value
+
+Alternatively you can set the default selector to XPath:
+
+    Capybara.default_selector = :xpath
+    find('//ul/li').text
+
+Capybara allows you to add custom selectors, which can be very useful if you
+find yourself using the same kinds of selectors very often:
+
+    Capybara.add_selector(:id) do
+      xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+    end
+
+    Capybara.add_selector(:row) do
+      xpath { |num| ".//tbody/tr[#{num}]" }
+    end
+
+The block given to xpath must always return an XPath expression as a String, or
+an XPath expression generated through the XPath gem. You can now use these
+selectors like this:
+
+    find(:id, 'post_123')
+    find(:row, 3)
+
+You can specify an optional match option which will automatically use the
+selector if it matches the argument:
+
+    Capybara.add_selector(:id) do
+      xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+      match { |value| value.is_a?(Symbol) }
+    end
+
+Now use it like this:
+
+    find(:post_123)
+
+This :id selector is already built into Capybara by default, so you don't
+need to add it yourself.
+
+== Beware the XPath // trap
+
+In XPath the expression // means something very specific, and it might not be what
+you think. Contrary to common belief, // means "anywhere in the document" not "anywhere
+in the current context". As an example:
+
+    page.find(:xpath, '//body').all(:xpath, '//script')
+
+You might expect this to find all script tags in the body, but actually, it finds all
+script tags in the entire document, not only those in the body! What you're looking
+for is the .// expression which means "any descendant of the current node":
+
+    page.find(:xpath, '//body').all(:xpath, './/script')
+
+The same thing goes for within:
+
+    within(:xpath, '//body') do
+      page.find(:xpath, './/script')
+      within(:xpath, './/table/tbody') do
+        ...
+      end
+    end
+
+== Configuring and adding drivers
+
+Capybara makes it convenient to switch between different drivers. It also exposes
+an API to tweak those drivers with whatever settings you want, or to add your own
+drivers. This is how to switch the selenium driver to use chrome:
+
+    Capybara.register_driver :selenium do |app|
+      Capybara::Selenium::Driver.new(app, :browser => :chrome)
+    end
+
+However, it's also possible to give this a different name, so tests can switch
+between using different browsers effortlessly:
+
+    Capybara.register_driver :selenium_chrome do |app|
+      Capybara::Selenium::Driver.new(app, :browser => :chrome)
+    end
+
+Whatever is returned from the block should conform to the API described by
+Capybara::Driver::Base, it does not however have to inherit from this class.
+Gems can use this API to add their own drivers to Capybara.
+
+The {Selenium wiki}[http://code.google.com/p/selenium/wiki/RubyBindings] has
+additional info about how the underlying driver can be configured.
+
+== Gotchas:
+
+* Access to session and request is not possible from the test, Access to
+  response is limited. Some drivers allow access to response headers and HTTP
+  status code, but this kind of functionality is not provided by some drivers,
+  such as Selenium.
+
+* Access to Rails specific stuff (such as <tt>controller</tt>) is unavailable,
+  since we're not using Rails' integration testing.
+
+* Freezing time: It's common practice to mock out the Time so that features
+  that depend on the current Date work as expected. This can be problematic,
+  since Capybara's Ajax timing uses the system time, resulting in Capybara
+  never timing out and just hanging when a failure occurs. It's still possible to
+  use plugins which allow you to travel in time, rather than freeze time.
+  One such plugin is {Timecop}[http://github.com/jtrupiano/timecop].
+
+* When using Rack::Test, beware if attempting to visit absolute URLs. For
+  example, a session might not be shared between visits to <tt>posts_path</tt>
+  and <tt>posts_url</tt>. If testing an absolute URL in an Action Mailer email,
+  set <tt>default_url_options</tt> to match the Rails default of
+  <tt>www.example.com</tt>.
+
+== License:
+
+(The MIT License)
+
+Copyright (c) 2009 Jonas Nicklas
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.