capybara 2.0.3 → 2.1.0

data/History.md

@@ -1,3 +1,85 @@
+# Version 2.1.0
+
+Release date: Unreleased
+
+### Changed
+
+* Hard version requirement on Ruby >= 1.9.3. Capybara will no longer install
+  on 1.8.7. [Felix Schäfer]
+* Capybara no longer depends on the `selenium-webdriver` gem. Add it to
+  your Gemfile if you wish to use the Selenium driver. [Jonas Nicklas]
+* `Capybara.ignore_hidden_elements` defaults to `true`. [Jonas Nicklas]
+* In case of multiple matches `smart` matching is used by default. Set
+  `Capybara.match = :one` to revert to old behaviour. [Jonas Nicklas].
+* Options in select boxes use smart matching and no longer need to match
+  exactly. Set `Capybara.exact_options = false` to revert to old behaviour.
+  [Jonas Nicklas].
+* Visibility of text depends on `Capybara.ignore_hidden_elements` instead of
+  always returning only visible text. Set `Capybara.visible_text_only = true`
+  to revert to old behaviour. [Jonas Nicklas]
+* Cucumber cleans up session after scenario instead. This is consistent with
+  RSpec and makes more sense, since we raise server errors in `reset!`.
+  [Jonas Nicklas]
+
+### Added
+
+* All actions (`click_link`, `fill_in`, etc...) and finders now take an options
+  hash, which is passed through to `find`. [Jonas Nicklas]
+* CSS selectors are sent straight through to driver instead of being converted
+  to XPath first. Enables the use of some pseudo selectors, such as `invalid`
+  in some drivers. [Thomas Walpole]
+* `Capybara.asset_host` option, which inserts a `base` tag into the page on
+  `save_and_open_page`, eases debugging with the Rails asset pipeline.
+  [Steve Hull]
+* `exact` option, can specify whether to match substrings or entire text.
+  [Jonas Nicklas]
+* `match` option, can specify behaviour in case of multiple matches.
+  [Jonas Nicklas]
+* `wait` option, can specify how long to wait for a given action/finder.
+  [Jonas Nicklas]
+* Config option which disables bubbling of errors raised inside server.
+  [Jonas Nicklas]
+* `text` now takes a parameter which makes it possible to return either all
+  text or only visible text. The default depends on
+  `Capybara.ignore_hidden_elements`. `Capybara.visible_text_only` option is
+  available for compatibility. [Jonas Nicklas]
+* `has_content?` and `has_text?` now take the same count options as `has_selector?`
+  [Andrey Botalov]
+* `current_scope` is now public API, returns the current element when `within`
+  is used. [Martijn Walraven]
+* `find("input").disabled?` returns true if a node is disabled. [Ben Lovell]
+* Find disabled fields and buttons with `:disabled => false`. [Jonas Nicklas]
+* `find("input").hover` moves the mouse to the element in supported drivers.
+  [Thomas Walpole]
+* RackTest driver now support `form` attribute on form elements.
+  [Thomas Walpole]
+* `page.title` returns the page title. [Terry Progetto]
+* `has_title?` matcher to assert on page title. [Jonas Nicklas]
+* The gem is now signed with a certicficate. The public key is available in the
+  repo. [Jonas Nicklas]
+* `:select` and `:textarea` are valid options for the `:type` filter on `find_field`
+  and `has_field?`. [Yann Plancqueel]
+
+### Fixed
+
+* Fixed race conditions when synchronizing across multiple nodes [Jonas Nicklas]
+* Fixed race conditions in deeply nested selectors [Jonas Nicklas]
+* Fix issue with `within_frame`, where selecting multiple nested frames didn't
+  work as intended. [Thomas Walpole]
+* RackTest no longer fills in readonly textareas. [Thomas Walpole]
+* Don't use autoload to load files, require them directly instead. [Jonas Nicklas]
+* Rescue weird exceptions when booting server [John Wilger]
+* Non strings are now properly cast when using the maxlength attribute [Jonas Nicklas]
+
+# Version 2.0.3
+
+Release date: 2013-03-26
+
+* Check against Rails version fixed to work with Rails' master branch now returning
+  a Gem::Version [Jonas Nicklas]
+* Use posix character class for whitespace replace, solves various encoding
+  problems on Ruby 2.0.0 and JRuby. [Ben Cates]
+
 # Version 2.0.2
 
 Release date: 2012-12-31

data/README.md

@@ -23,19 +23,19 @@ GitHub): http://groups.google.com/group/ruby-capybara
 
 ## Setup
 
-To install, type
+Capybara requires Ruby 1.9.3 or later. To install, type:
 
 ```bash
-sudo gem install capybara
+gem install capybara
 ```
 
-If you are using Rails, add this line to your test helper file:
+If the application that you are testing is a Rails app, add this line to your test helper file:
 
 ```ruby
 require 'capybara/rails'
 ```
 
-If you are not using Rails, set Capybara.app to your rack app:
+If the application that you are testing is a Rack app, but not Rails, set Capybara.app to your Rack app:
 
 ```ruby
 Capybara.app = MyRackApp
@@ -102,11 +102,13 @@ describe "the signup process", :type => :feature do
   end
 
   it "signs me in" do
+    visit '/sessions/new'
     within("#session") do
       fill_in 'Login', :with => 'user@example.com'
       fill_in 'Password', :with => 'password'
     end
     click_link 'Sign in'
+    page.should have_content 'Success'
   end
 end
 ```
@@ -131,21 +133,25 @@ feature "Signing up" do
   end
 
   scenario "Signing in with correct credentials" do
+    visit '/sessions/new'
     within("#session") do
       fill_in 'Login', :with => 'user@example.com'
       fill_in 'Password', :with => 'caplin'
     end
     click_link 'Sign in'
+    page.should have_content 'Success'
   end
 
   given(:other_user) { User.make(:email => 'other@example.com', :password => 'rous') }
 
   scenario "Signing in as another user" do
+    visit '/sessions/new'
     within("#session") do
       fill_in 'Login', :with => other_user.email
       fill_in 'Password', :with => other_user.password
     end
     click_link 'Sign in'
+    page.should have_content 'Invalid email or password'
   end
 end
 ```
@@ -156,36 +162,14 @@ end
 
 ## Using Capybara with Test::Unit
 
-* If you are using Rails, add `database_cleaner` to your Gemfile:
-
-    ```ruby
-    group :test do
-      gem 'database_cleaner'
-    end
-    ```
-
-    Then add the following code in your `test_helper.rb` file to make
-    Capybara available in all test cases deriving from
+* If you are using Rails, add the following code in your `test_helper.rb` 
+    file to make Capybara available in all test cases deriving from
     `ActionDispatch::IntegrationTest`:
 
     ```ruby
-    # Transactional fixtures do not work with Selenium tests, because Capybara
-    # uses a separate server thread, which the transactions would be hidden
-    # from. We hence use DatabaseCleaner to truncate our test database.
-    DatabaseCleaner.strategy = :truncation
-
     class ActionDispatch::IntegrationTest
       # Make the Capybara DSL available in all integration tests
       include Capybara::DSL
-
-      # Stop ActiveRecord from wrapping tests in transactions
-      self.use_transactional_fixtures = false
-
-      teardown do
-        DatabaseCleaner.clean       # Truncate the database
-        Capybara.reset_sessions!    # Forget the (simulated) browser state
-        Capybara.use_default_driver # Revert Capybara.current_driver to Capybara.default_driver
-      end
     end
     ```
 
@@ -401,7 +385,6 @@ certain elements, and working with and manipulating those elements.
 ```ruby
 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')
@@ -416,7 +399,6 @@ You can use these with RSpec's magic matchers:
 ```ruby
 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')
@@ -524,6 +506,49 @@ Finally, in drivers that support it, you can save a screenshot:
 page.save_screenshot('screenshot.png')
 ```
 
+## Matching
+
+It is possible to customize how Capybara finds elements. At your disposal
+are two options, `Capybara.exact` and `Capybara.match`.
+
+### Exactness
+
+`Capybara.exact` and the `exact` option work together with the `is` expression
+inside the XPath gem. When `exact` is true, all `is` expressions match exactly,
+when it is false, they allow substring matches. Many of the selectors built into
+Capybara use the `is` expression. This way you can specify whether you want to
+allow substring matches or not. `Capybara.exact` is false by default.
+
+For example:
+
+```ruby
+click_link("Password") # also matches "Password confirmation"
+Capybara.exact = true
+click_link("Password") # does not match "Password confirmation"
+click_link("Password", exact: false) # can be overridden
+```
+
+### Strategy
+
+Using `Capybara.match` and the equivalent `match` option, you can control how
+Capybara behaves when multiple elements all match a query. There are currently
+four different strategies built into Capybara:
+
+1. **first:** Just picks the first element that matches.
+2. **one:** Raises an error if more than one element matches.
+3. **smart:** If `exact` is `true`, raises an error if more than one element
+   matches, just like `one`. If `exact` is `false`, it will first try to find
+   an exact match. An error is raised if more than one element is found. If no
+   element is found, a new search is performed which allows partial matches. If
+   that search returns multiple matches, an error is raised.
+4. **prefer_exact:** If multiple matches are found, some of which are exact,
+   and some of which are not, then the first exactly matching element is
+   returned.
+
+The default for `Capybara.match` is `:smart`. To emulate the behaviour in
+Capybara 2.0.x, set `Capybara.match` to `:one`. To emulate the behaviour in
+Capybara 1.x, set `Capybara.match` to `:prefer_exact`.
+
 ## Transactions and database setup
 
 Some Capybara drivers need to run against an actual HTTP server. Capybara takes
@@ -575,7 +600,7 @@ 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
+exist yet. However Capybara is smart enough 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
@@ -648,7 +673,7 @@ This enables its use in unsupported testing frameworks, and for general-purpose
 ## 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
+can also use it to talk to a web server running anywhere on the internet, by
 setting app_host:
 
 ```ruby
@@ -737,25 +762,6 @@ find(:row, 3)
 find(:flash_type, :notice)
 ```
 
-You can specify an optional match option which will automatically use the
-selector if it matches the argument:
-
-```ruby
-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:
-
-```ruby
-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
@@ -840,7 +846,6 @@ additional info about how the underlying driver can be configured.
 To set up a development environment, simply do:
 
 ```bash
-git submodule update --init
 bundle install
 bundle exec rake  # run the test suite
 ```

data/lib/capybara/cucumber.rb

@@ -6,8 +6,11 @@ require 'capybara/rspec/matchers'
 World(Capybara::DSL)
 World(Capybara::RSpecMatchers)
 
-Before do
+After do
   Capybara.reset_sessions!
+end
+
+Before do
   Capybara.use_default_driver
 end
 

data/lib/capybara/driver/base.rb

@@ -7,7 +7,11 @@ class Capybara::Driver::Base
     raise NotImplementedError
   end
 
-  def find(query)
+  def find_xpath(query)
+    raise NotImplementedError
+  end
+  
+  def find_css(query)
     raise NotImplementedError
   end
 
@@ -16,31 +20,31 @@ class Capybara::Driver::Base
   end
 
   def execute_script(script)
-    raise Capybara::NotSupportedByDriverError
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#execute_script'
   end
 
   def evaluate_script(script)
-    raise Capybara::NotSupportedByDriverError
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#evaluate_script'
   end
 
   def save_screenshot(path, options={})
-    raise Capybara::NotSupportedByDriverError
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#save_screenshot'
   end
 
   def response_headers
-    raise Capybara::NotSupportedByDriverError
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#response_headers'
   end
 
   def status_code
-    raise Capybara::NotSupportedByDriverError
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#status_code'
   end
 
-  def within_frame(frame_id)
-    raise Capybara::NotSupportedByDriverError
+  def within_frame(frame_handle)
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#within_frame'
   end
 
   def within_window(handle)
-    raise Capybara::NotSupportedByDriverError
+    raise Capybara::NotSupportedByDriverError, 'Capybara::Driver::Base#within_window'
   end
 
   def invalid_element_errors

data/lib/capybara/driver/node.rb

@@ -8,7 +8,11 @@ module Capybara
         @native = native
       end
 
-      def text
+      def all_text
+        raise NotImplementedError
+      end
+
+      def visible_text
         raise NotImplementedError
       end
 
@@ -37,6 +41,10 @@ module Capybara
         raise NotImplementedError
       end
 
+      def hover
+        raise NotImplementedError
+      end
+      
       def drag_to(element)
         raise NotImplementedError
       end
@@ -57,22 +65,26 @@ module Capybara
         raise NotImplementedError
       end
 
+      def disabled?
+        raise NotImplementedError
+      end
+
       def path
-        raise NotSupportedByDriverError
+        raise NotSupportedByDriverError, 'Capybara::Driver::Node#path'
       end
-      
+
       def trigger(event)
-        raise NotSupportedByDriverError
+        raise NotSupportedByDriverError, 'Capybara::Driver::Node#trigger'
       end
 
       def inspect
         %(#<#{self.class} tag="#{tag_name}" path="#{path}">)
-      rescue NotSupportedByDriverError
+      rescue NotSupportedByDriverError, 'Capybara::Driver::Node#inspect'
         %(#<#{self.class} tag="#{tag_name}">)
       end
 
       def ==(other)
-        raise NotSupportedByDriverError
+        raise NotSupportedByDriverError, 'Capybara::Driver::Node#=='
       end
     end
   end

data/lib/capybara/helpers.rb

@@ -1,31 +1,120 @@
 # encoding: UTF-8
 
 module Capybara
+
+  # @api private
   module Helpers
-    class << self
-      ##
-      #
-      # Normalizes whitespace space by stripping leading and trailing
-      # whitespace and replacing sequences of whitespace characters
-      # with a single space.
-      #
-      # @param [String] text     Text to normalize
-      # @return [String]         Normalized text
-      #
-      def normalize_whitespace(text)
-        text.to_s.gsub(/[[:space:]]+/, ' ').strip
+    extend self
+
+    ##
+    #
+    # Normalizes whitespace space by stripping leading and trailing
+    # whitespace and replacing sequences of whitespace characters
+    # with a single space.
+    #
+    # @param [String] text     Text to normalize
+    # @return [String]         Normalized text
+    #
+    def normalize_whitespace(text)
+      text.to_s.gsub(/[[:space:]]+/, ' ').strip
+    end
+
+    ##
+    #
+    # Escapes any characters that would have special meaning in a regexp
+    # if text is not a regexp
+    #
+    # @param [String] text Text to escape
+    # @return [String]     Escaped text
+    #
+    def to_regexp(text)
+      text.is_a?(Regexp) ? text : Regexp.new(Regexp.escape(normalize_whitespace(text)))
+    end
+
+    ##
+    #
+    # Injects a `<base>` tag into the given HTML code, pointing to
+    # `Capybara.asset_host`.
+    #
+    # @param [String] html     HTML code to inject into
+    # @return [String]         The modified HTML code
+    #
+    def inject_asset_host(html)
+      if Capybara.asset_host
+        if Nokogiri::HTML(html).css("base").empty? and match = html.match(/<head[^<]*?>/)
+          html.clone.insert match.end(0), "<base href='#{Capybara.asset_host}' />"
+        end
+      else
+        html
       end
+    end
+
+    ##
+    #
+    # Checks if the given count matches the given count options. By default,
+    # when no options are given, count should be larger than zero.
+    #
+    # @param [Integer] count     The actual number. Should be coercible via Integer()
+    # @option [Range] between    Count must be within the given range
+    # @option [Integer] count    Count must be exactly this
+    # @option [Integer] maximum  Count must be smaller than or equal to this value
+    # @option [Integer] minimum  Count must be larger than or equal to this value
+    #
+    def matches_count?(count, options={})
+      case
+      when options[:between]
+        options[:between] === count
+      when options[:count]
+        Integer(options[:count]) == count
+      when options[:maximum]
+        Integer(options[:maximum]) >= count
+      when options[:minimum]
+        Integer(options[:minimum]) <= count
+      else
+        count > 0
+      end
+    end
+
+    ##
+    #
+    # Generates a failure message given a description of the query and count
+    # options.
+    #
+    # @param [String] description   Description of a query
+    # @option [Range] between       Count should have been within the given range
+    # @option [Integer] count       Count should have been exactly this
+    # @option [Integer] maximum     Count should have been smaller than or equal to this value
+    # @option [Integer] minimum     Count should have been larger than or equal to this value
+    #
+    def failure_message(description, options={})
+      message = "expected to find #{description}"
+      if options[:count]
+        message << " #{options[:count]} #{declension('time', 'times', options[:count])}"
+      elsif options[:between]
+        message << " between #{options[:between].first} and #{options[:between].last} times"
+      elsif options[:maximum]
+        message << " at most #{options[:maximum]} #{declension('time', 'times', options[:maximum])}"
+      elsif options[:minimum]
+        message << " at least #{options[:minimum]} #{declension('time', 'times', options[:minimum])}"
+      end
+      message
+    end
 
-      ##
-      #
-      # Escapes any characters that would have special meaning in a regexp
-      # if text is not a regexp
-      #
-      # @param [String] text Text to escape
-      # @return [String]     Escaped text
-      #
-      def to_regexp(text)
-        text.is_a?(Regexp) ? text : Regexp.escape(normalize_whitespace(text))
+    ##
+    #
+    # A poor man's `pluralize`. Given two declensions, one singular and one
+    # plural, as well as a count, this will pick the correct declension. This
+    # way we can generate gramatically correct error message.
+    #
+    # @param [String] singular     The singular form of the word
+    # @param [String] plural       The plural form of the word
+    # @param [Integer] count       The number of items
+    #
+    def declension(singular, plural, count)
+      if count == 1
+        singular
+      else
+        plural
       end
     end
   end