capybara 2.0.3 → 2.1.0.beta1

data/History.md

@@ -1,3 +1,76 @@
+# 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]
+* Use posix character class for whitespace replace, solves various encoding
+  problems on Ruby 2.0.0 and JRuby. [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]
+
 # Version 2.0.2
 
 Release date: 2012-12-31

data/README.md

@@ -26,7 +26,7 @@ GitHub): http://groups.google.com/group/ruby-capybara
 To install, type
 
 ```bash
-sudo gem install capybara
+gem install capybara
 ```
 
 If you are using Rails, add this line to your test helper file:
@@ -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
 ```
@@ -401,7 +407,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 +421,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 +528,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 +622,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 +695,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

data/lib/capybara.rb

@@ -15,10 +15,10 @@ module Capybara
   class InfiniteRedirectError < CapybaraError; end
 
   class << self
-    attr_accessor :asset_root, :app_host, :run_server, :default_host, :always_include_port
-    attr_accessor :server_host, :server_port
+    attr_accessor :asset_host, :app_host, :run_server, :default_host, :always_include_port
+    attr_accessor :server_host, :server_port, :exact, :match, :exact_options, :visible_text_only
     attr_accessor :default_selector, :default_wait_time, :ignore_hidden_elements
-    attr_accessor :save_and_open_page_path, :automatic_reload
+    attr_accessor :save_and_open_page_path, :automatic_reload, :raise_server_errors
     attr_writer :default_driver, :current_driver, :javascript_driver, :session_name
     attr_accessor :app
 
@@ -33,9 +33,10 @@ module Capybara
     #
     # === Configurable options
     #
-    # [asset_root = String]               Where static assets are located, used by save_and_open_page
+    # [asset_host = String]               The hostname for a server from which assets can be loaded, used by save_and_open_page
     # [app_host = String]                 The default host to use when giving a relative URL to visit
     # [always_include_port = Boolean]     Whether the Rack server's port should automatically be inserted into every visited URL (Default: false)
+    # [asset_host = String]               Where dynamic assets are hosted - will be prepended to relative asset locations if present (Default: nil)
     # [run_server = Boolean]              Whether to start a Rack server for the given Rack app (Default: true)
     # [default_selector = :css/:xpath]    Methods which take a selector use the given type by default (Default: CSS)
     # [default_wait_time = Integer]       The number of seconds to wait for asynchronous processes to finish (Default: 2)
@@ -88,20 +89,12 @@ module Capybara
     #     page.find('table#myTable').has_selector?(:row, 3)
     #     within(:row, 3) { page.should have_content('$100.000') }
     #
-    # It might be convenient to specify that the selector is automatically chosen for certain
-    # values. This way you don't have to explicitly specify that you are looking for a row, or
-    # an id. Let's say we want Capybara to treat any Symbols sent into methods like find to be
-    # treated as though they were element ids. We could achieve this like so:
+    # Here is another example:
     #
     #     Capybara.add_selector(:id) do
     #       xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
-    #       match { |value| value.is_a?(Symbol) }
     #     end
     #
-    # Now we can retrieve elements by id like this:
-    #
-    #     find(:post_123)
-    #
     # Note that this particular selector already ships with Capybara.
     #
     # @param [Symbol] name    The name of the selector to add
@@ -124,7 +117,7 @@ module Capybara
     #       Rack::Handler::Mongrel.run(app, :Port => port)
     #     end
     #
-    # By default, Capybara will try to run thin, falling back to webrick.
+    # By default, Capybara will try to run webrick.
     #
     # @yield [app, port]                      This block recieves a rack app and port and should run a Rack handler
     #
@@ -294,53 +287,38 @@ module Capybara
   self.default_driver = nil
   self.current_driver = nil
 
-  autoload :DSL,        'capybara/dsl'
-  autoload :Server,     'capybara/server'
-  autoload :Session,    'capybara/session'
-  autoload :Selector,   'capybara/selector'
-  autoload :Query,      'capybara/query'
-  autoload :Result,     'capybara/result'
-  autoload :Helpers,    'capybara/helpers'
-  autoload :VERSION,    'capybara/version'
-
-  module Node
-    autoload :Base,       'capybara/node/base'
-    autoload :Simple,     'capybara/node/simple'
-    autoload :Element,    'capybara/node/element'
-    autoload :Document,   'capybara/node/document'
-    autoload :Finders,    'capybara/node/finders'
-    autoload :Matchers,   'capybara/node/matchers'
-    autoload :Actions,    'capybara/node/actions'
-  end
-
-  module Driver
-    autoload :Base,     'capybara/driver/base'
-    autoload :Node,     'capybara/driver/node'
-
-    class Selenium
-      def initialize(*args)
-        raise "Capybara::Driver::Selenium has been renamed to Capybara::Selenium::Driver"
-      end
-    end
-
-    class RackTest
-      def initialize(*args)
-        raise "Capybara::Driver::RackTest has been renamed to Capybara::RackTest::Driver"
-      end
-    end
-  end
-
-  module RackTest
-    autoload :Driver,  'capybara/rack_test/driver'
-    autoload :Node,    'capybara/rack_test/node'
-    autoload :Form,    'capybara/rack_test/form'
-    autoload :Browser, 'capybara/rack_test/browser'
-  end
-
-  module Selenium
-    autoload :Node,    'capybara/selenium/node'
-    autoload :Driver,  'capybara/selenium/driver'
-  end
+  module Driver; end
+  module RackTest; end
+  module Selenium; end
+
+  require 'capybara/helpers'
+  require 'capybara/session'
+  require 'capybara/dsl'
+  require 'capybara/server'
+  require 'capybara/selector'
+  require 'capybara/query'
+  require 'capybara/result'
+  require 'capybara/version'
+
+  require 'capybara/node/finders'
+  require 'capybara/node/matchers'
+  require 'capybara/node/actions'
+  require 'capybara/node/simple'
+  require 'capybara/node/base'
+  require 'capybara/node/element'
+  require 'capybara/node/document'
+
+  require 'capybara/driver/base'
+  require 'capybara/driver/node'
+
+  require 'capybara/rack_test/driver'
+  require 'capybara/rack_test/node'
+  require 'capybara/rack_test/form'
+  require 'capybara/rack_test/browser'
+  require 'capybara/rack_test/css_handlers.rb'
+
+  require 'capybara/selenium/node'
+  require 'capybara/selenium/driver'
 end
 
 Capybara.configure do |config|
@@ -349,9 +327,13 @@ Capybara.configure do |config|
   config.server {|app, port| Capybara.run_default_server(app, port)}
   config.default_selector = :css
   config.default_wait_time = 2
-  config.ignore_hidden_elements = false
+  config.ignore_hidden_elements = true
   config.default_host = "http://www.example.com"
   config.automatic_reload = true
+  config.match = :smart
+  config.exact = false
+  config.raise_server_errors = true
+  config.visible_text_only = false
 end
 
 Capybara.register_driver :rack_test do |app|

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