capybara 2.0.0.beta2 → 2.0.0.beta4

data/History.txt

@@ -2,6 +2,35 @@
 
 ### Changed
 
+* `require 'capybara/rails'` will automatically enable `:respect_data_method`
+  on the RackTest driver, so the behavior matches Capybara 1.1.2 [Jo Liss]
+* Dropped official support for Ruby 1.8.x. [Jonas Nicklas]
+* All methods which find or manipulate fields or buttons now ignore them when
+  they are disabled. [Jonas Nicklas]
+* Can no longer find elements by id via `find(:foo)`, use `find("#foo")` or
+  `find_by_id("foo")` instead. [Jonas Nicklas]
+* Rename `Driver#body` to `Driver#html` (relevant only for driver authors) [Jo
+  Liss]
+
+### Added
+
+* Multiple files can be uploaded with `attach_file` [Jarl Friis]
+
+### Fixed
+
+* `has_text` (`has_content`) now accepts non-string arguments, like numbers.
+  [Jo Liss]
+* `has_text` and `text` now correctly normalize Unicode whitespace, such as
+  ` `. [Jo Liss]
+* RackTest allows protocol relative URLs [Jonas Nicklas]
+* Arguments are cast to string where necessary, so that e.g. `click_link(:foo)` works
+  as expected. [Jonas Nicklas]
+* `:count => 0` now works as expected [Jarl Friis]
+
+# Version 2.0.0.beta2
+
+### Changed
+
 * `respect_data_method` default to `false` for the RackTest driver, which means
   that Capybara no longer picks up `:method => :post` et. al. from links in Rails
   by default. [Jonas Nicklas]
@@ -77,7 +106,7 @@
   session is reset [James Tucker, Jonas Nicklas]
 * A ton of new selectors built in out of the box, like `field`, `link`, `button`,
   etc... [Adam McCrea, Jonas Nicklas]
-* `has_text`, `has_content` ... [Jonas Nicklas]
+* `has_text?` has been added as an alias for `has_content?` [Jonas Nicklas]
 * Add `Capybara.server_host` option (default: 127.0.0.1) [David Balatero]
 * Add `:type` option for `page.has_field?` [Gonzalo Rodríguez]
 * Custom matchers can now be specified in CSS in addition to XPath [Jonas Nicklas]

data/README.md

@@ -4,14 +4,23 @@
 [![Dependency Status](https://gemnasium.com/jnicklas/capybara.png)](https://gemnasium.com/jnicklas/capybara)
 [![Code Quality](https://codeclimate.com/badge.png)](https://codeclimate.com/github/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.
+Capybara helps you test web 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.
 
 **Need help?** Ask on the mailing list (please do not open an issue on
 GitHub): http://groups.google.com/group/ruby-capybara
 
+## Key benefits
+
+- **No setup** necessary for Rails and Rack application. Works out of the box.
+- **Intuitive API** which mimics the language an actual user would use.
+- **Switch the backend** your tests run against from fast headless mode
+  to an actual browser with no changes to your tests.
+- **Powerful synchronization** features mean you never have to manually wait
+  for asynchronous processes to complete.
+
 ## Setup
 
 To install, type
@@ -32,6 +41,9 @@ If you are not using Rails, set Capybara.app to your rack app:
 Capybara.app = MyRackApp
 ```
 
+If you need to test JavaScript, or if your app interacts with (or is located at)
+a remote URL, you'll need to [use a different driver](#drivers).
+
 ## Using Capybara with Cucumber
 
 The `cucumber-rails` gem comes with Capybara support built-in. If you
@@ -126,11 +138,21 @@ feature "Signing up" do
     end
     click_link 'Sign in'
   end
+
+  given(:other_user) { User.make(:email => 'other@example.com', :password => 'rous') }
+  
+  scenario "Signing in as another user" do
+    within("#session") do
+      fill_in 'Login', :with => other_user.email
+      fill_in 'Password', :with => other_user.password
+    end
+    click_link 'Sign in'
+  end
 end
 ```
 
 `feature` is in fact just an alias for `describe ..., :type => :request`,
-`background` is an alias for `before`, and `scenario` for `it`.
+`background` is an alias for `before`, `scenario` for `it`, and `given`/`given!` aliases for `let`/`let!`, respectively.
 
 ## Using Capybara with Test::Unit
 
@@ -217,10 +239,11 @@ Capybara uses the same DSL to drive a variety of browser and headless drivers.
 
 ### Selecting the Driver
 
-By default, Capybara uses the `:rack_test` 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:
+By default, Capybara uses the `:rack_test` driver, which is fast but limited: it
+does not support JavaScript, nor is it able to access HTTP resources outside of
+your Rack application, such as remote APIs and OAuth services. To get around
+these limitations, 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:
 
 ```ruby
 Capybara.default_driver = :selenium
@@ -248,15 +271,17 @@ 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 against the Rack interface, it does not need any server to be started,
-it can work directly 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.
+have any support for executing JavaScript. Since the RackTest driver interacts
+directly with Rack interfaces, it does not require a server to be started.
+However, 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. Furthermore, you cannot use the RackTest driver to test a
+remote application, or to access remote URLs (e.g., redirects to external
+sites, external APIs, or OAuth services) that your application might interact
+with.
+
 [capybara-mechanize](https://github.com/jeroenvandijk/capybara-mechanize)
-intends to provide a similar driver which works against remote servers, it is a
-separate project.
+provides a similar driver that can access remote servers.
 
 RackTest can be configured with a set of headers like this:
 
@@ -474,14 +499,6 @@ that this may break with more complicated expressions:
 result = page.evaluate_script('4 + 4');
 ```
 
-### Saving screenshot
-
-In drivers which support it, you can save screenshot:
-
-```ruby
-page.save_screenshot('screenshot.png')
-```
-
 ### Debugging
 
 It can be useful to take a snapshot of the page as it currently is and take a
@@ -501,6 +518,12 @@ print page.html
 This is mostly useful for debugging. You should avoid testing against the
 contents of `page.html` and use the more expressive finder methods instead.
 
+Finally, in drivers that support it, you can save a screenshot:
+
+```ruby
+page.save_screenshot('screenshot.png')
+```
+
 ## Transactions and database setup
 
 Some Capybara drivers need to run against an actual HTTP server. Capybara takes
@@ -814,12 +837,6 @@ additional info about how the underlying driver can be configured.
 
 ## Development
 
-If you found a _reproducible_ bug, open a [GitHub
-Issue](http://github.com/jnicklas/capybara/issues) to submit a bug report.
-
-Even better, send a pull request! Make sure all changes are well tested,
-Capybara is a testing tool after all. Topic branches are good.
-
 To set up a development environment, simply do:
 
 ```bash
@@ -827,3 +844,7 @@ git submodule update --init
 bundle install
 bundle exec rake  # run the test suite
 ```
+
+See
+[CONTRIBUTING.md](https://github.com/jnicklas/capybara/blob/master/CONTRIBUTING.md)
+for how to send issues and pull requests.

data/lib/capybara.rb

@@ -308,6 +308,7 @@ module Capybara
   autoload :Selector,   'capybara/selector'
   autoload :Query,      'capybara/query'
   autoload :Result,     'capybara/result'
+  autoload :Helpers,    'capybara/helpers'
   autoload :VERSION,    'capybara/version'
 
   module Node

data/lib/capybara/driver/base.rb

@@ -15,7 +15,7 @@ class Capybara::Driver::Base
     raise NotImplementedError
   end
 
-  def body
+  def html
     raise NotImplementedError
   end
 

data/lib/capybara/driver/node.rb

@@ -20,6 +20,7 @@ module Capybara
         raise NotImplementedError
       end
 
+      # @param value String or Array. Array is only allowed if node has 'multiple' attribute
       def set(value)
         raise NotImplementedError
       end

data/lib/capybara/dsl.rb

@@ -2,6 +2,15 @@ require 'capybara'
 
 module Capybara
   module DSL
+    def self.included(base)
+      warn "including Capybara::DSL in the global scope is not recommended!" if base == Object
+      super
+    end
+
+    def self.extended(base)
+      warn "extending the main object with Capybara::DSL is not recommended!" if base == TOPLEVEL_BINDING.eval("self")
+      super
+    end
 
     ##
     #
@@ -38,11 +47,9 @@ module Capybara
     end
 
     Session::DSL_METHODS.each do |method|
-      class_eval <<-RUBY, __FILE__, __LINE__+1
-        def #{method}(*args, &block)
-          page.#{method}(*args, &block)
-        end
-      RUBY
+      define_method method do |*args, &block|
+        page.send method, *args, &block
+      end
     end
   end
 

data/lib/capybara/helpers.rb

@@ -0,0 +1,33 @@
+module Capybara
+  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)
+        # http://en.wikipedia.org/wiki/Whitespace_character#Unicode
+        # We should have a better reference.
+        # See also http://stackoverflow.com/a/11758133/525872
+        text.to_s.gsub(/[\s\u0085\u00a0\u1680\u180e\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/, ' ').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.escape(normalize_whitespace(text))
+      end
+    end
+  end
+end

data/lib/capybara/node/actions.rb

@@ -135,10 +135,12 @@ module Capybara
       #     page.attach_file(locator, '/path/to/file.png')
       #
       # @param [String] locator       Which field to attach the file to
-      # @param [String] path          The path of the file that will be attached
+      # @param [String] path          The path of the file that will be attached, or an array of paths
       #
       def attach_file(locator, path)
-        raise Capybara::FileNotFound, "cannot attach file, #{path} does not exist" unless File.exist?(path.to_s)
+        (String === path ? [path] : path).each do |p|
+          raise Capybara::FileNotFound, "cannot attach file, #{p} does not exist" unless File.exist?(p.to_s)
+        end
         find(:file_field, locator).set(path)
       end
     end

data/lib/capybara/node/base.rb

@@ -38,14 +38,47 @@ module Capybara
         self
       end
 
+      ##
+      #
+      # This method is Capybara's primary defence agains asynchronicity
+      # problems. It works by attempting to run a given block of code until it
+      # succeeds. The exact behaviour of this method depends on a number of
+      # factors. Basically there are certain exceptions which, when raised
+      # from the block, instead of bubbling up, are caught, and the block is
+      # re-run.
+      #
+      # Certain drivers, such as RackTest, have no support for aynchronous
+      # processes, these drivers run the block, and any error raised bubbles up
+      # immediately. This allows faster turn around in the case where an
+      # expectation fails.
+      #
+      # Only exceptions that are {Capybara::ElementNotFound} or any subclass
+      # thereof cause the block to be rerun. Drivers may specify additional
+      # exceptions which also cause reruns. This usually occurs when a node is
+      # manipulated which no longer exists on the page. For example, the
+      # Selenium driver specifies
+      # `Selenium::WebDriver::Error::ObsoleteElementError`.
+      #
+      # As long as any of these exceptions are thrown, the block is re-run,
+      # until a certain amount of time passes. The amount of time defaults to
+      # {Capybara.default_wait_time} and can be overriden through the `seconds`
+      # argument. This time is compared with the system time to see how much
+      # time has passed. If the return value of {Time.now} is stubbed out,
+      # Capybara will raise `Capybara::FrozenInTime`.
+      #
+      # @param [Integer] seconds          Number of seconds to retry this block
+      # @return [Object]                  The result of the given block
+      # @raise [Capybara::FrozenInTime]   If the return value of {Time.now} appears stuck
+      #
       def synchronize(seconds=Capybara.default_wait_time)
         start_time = Time.now
 
         begin
           yield
         rescue => e
+          raise e if @unsynchronized
           raise e unless driver.wait?
-          raise e unless driver.invalid_element_errors.include?(e.class) or e.is_a?(Capybara::ElementNotFound)
+          raise e unless driver.invalid_element_errors.include?(e.class) || e.is_a?(Capybara::ElementNotFound)
           raise e if (Time.now - start_time) >= seconds
           sleep(0.05)
           raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead" if Time.now == start_time
@@ -54,6 +87,24 @@ module Capybara
         end
       end
 
+      ##
+      #
+      # Within the given block, prevent synchronize from having any effect.
+      #
+      # This is an internal method which should not be called unless you are
+      # absolutely sure of what you're doing.
+      #
+      # @api private
+      # @return [Object]                  The result of the given block
+      #
+      def unsynchronized
+        orig = @unsynchronized
+        @unsynchronized = true
+        yield
+      ensure
+        @unsynchronized = orig
+      end
+
     protected
 
       def driver

data/lib/capybara/node/element.rb

@@ -177,18 +177,6 @@ module Capybara
         synchronize { base.drag_to(node.base) }
       end
 
-      def find(*args)
-        synchronize { super }
-      end
-
-      def first(*args)
-        synchronize { super }
-      end
-
-      def all(*args)
-        synchronize { super }
-      end
-
       def reload
         if @allow_reload
           reloaded = parent.reload.first(@query.name, @query.locator, @query.options)

data/lib/capybara/node/finders.rb

@@ -52,7 +52,7 @@ module Capybara
 
       ##
       #
-      # Find a button on the page. The link can be found by its id, name or value.
+      # Find a button on the page. The button can be found by its id, name or value.
       #
       # @param [String] locator       Which button to find
       # @return [Capybara::Element]   The found element

data/lib/capybara/node/matchers.rb

@@ -25,8 +25,7 @@ module Capybara
       # has_selector? can also accept XPath expressions generated by the
       # XPath gem:
       #
-      #     xpath = XPath.generate { |x| x.descendant(:p) }
-      #     page.has_selector?(:xpath, xpath)
+      #     page.has_selector?(:xpath, XPath.descendant(:p))
       #
       # @param (see Capybara::Node::Finders#all)
       # @option options [Integer] :count (nil)    Number of times the expression should occur
@@ -38,14 +37,6 @@ module Capybara
         return false
       end
 
-      def assert_selector(*args)
-        synchronize do
-          result = all(*args)
-          result.matches_count? or raise Capybara::ExpectationNotMet, result.failure_message
-        end
-        return true
-      end
-
       ##
       #
       # Checks if a given selector is not on the page or current node.
@@ -60,6 +51,51 @@ module Capybara
         return false
       end
 
+      ##
+      #
+      # Asserts that a given selector is on the page or current node.
+      #
+      #     page.assert_selector('p#foo')
+      #     page.assert_selector(:xpath, './/p[@id="foo"]')
+      #     page.assert_selector(:foo)
+      #
+      # By default it will check if the expression occurs at least once,
+      # but a different number can be specified.
+      #
+      #     page.assert_selector('p#foo', :count => 4)
+      #
+      # This will check if the expression occurs exactly 4 times.
+      #
+      # It also accepts all options that {Capybara::Node::Finders#all} accepts,
+      # such as :text and :visible.
+      #
+      #     page.assert_selector('li', :text => 'Horse', :visible => true)
+      #
+      # {assert_selector} can also accept XPath expressions generated by the
+      # XPath gem:
+      #
+      #     page.assert_selector(:xpath, XPath.descendant(:p))
+      #
+      # @param (see Capybara::Node::Finders#all)
+      # @option options [Integer] :count (nil)    Number of times the expression should occur
+      # @raise [Capybara::ExpectationNotMet]      If the selector does not exist
+      #
+      def assert_selector(*args)
+        synchronize do
+          result = all(*args)
+          result.matches_count? or raise Capybara::ExpectationNotMet, result.failure_message
+        end
+        return true
+      end
+
+      ##
+      #
+      # Asserts that a given selector is not on the page or current node.
+      # Usage is identical to Capybara::Node::Matchers#assert_selector
+      #
+      # @param (see Capybara::Node::Finders#assert_selector)
+      # @raise [Capybara::ExpectationNotMet]      If the selector exists
+      #
       def assert_no_selector(*args)
         synchronize do
           result = all(*args)
@@ -157,18 +193,17 @@ module Capybara
       # Checks if the page or current node has the given text content,
       # ignoring any HTML tags and normalizing whitespace.
       #
-      # Unlike has_content this only matches displayable text and specifically
-      # excludes text contained within non-display nodes such as script or head tags.
+      # This only matches displayable text and specifically excludes text
+      # contained within non-display nodes such as script or head tags.
       #
       # @param [String] content       The text to check for
       # @return [Boolean]             Whether it exists
       #
       def has_text?(content)
-        normalized_content = normalize_whitespace(content)
-
         synchronize do
-          normalize_whitespace(text).match(escape_regexp(normalized_content)) or
-          raise ExpectationNotMet
+          unless Capybara::Helpers.normalize_whitespace(text).match(Capybara::Helpers.to_regexp(content))
+            raise ExpectationNotMet
+          end
         end
         return true
       rescue Capybara::ExpectationNotMet
@@ -181,18 +216,17 @@ module Capybara
       # Checks if the page or current node does not have the given text
       # content, ignoring any HTML tags and normalizing whitespace.
       #
-      # Unlike has_content this only matches displayable text and specifically
-      # excludes text contained within non-display nodes such as script or head tags.
+      # This only matches displayable text and specifically excludes text
+      # contained within non-display nodes such as script or head tags.
       #
       # @param [String] content       The text to check for
-      # @return [Boolean]             Whether it exists
+      # @return [Boolean]             Whether it doesn't exist
       #
       def has_no_text?(content)
-        normalized_content = normalize_whitespace(content)
-
         synchronize do
-          !normalize_whitespace(text).match(escape_regexp(normalized_content)) or
-          raise ExpectationNotMet
+          if Capybara::Helpers.normalize_whitespace(text).match(Capybara::Helpers.to_regexp(content))
+            raise ExpectationNotMet
+          end
         end
         return true
       rescue Capybara::ExpectationNotMet
@@ -426,30 +460,6 @@ module Capybara
 
     private
 
-      ##
-      #
-      # 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.is_a?(Regexp) ? text : text.gsub(/\s+/, ' ').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 escape_regexp(text)
-        text.is_a?(Regexp) ? text : Regexp.escape(text)
-      end
     end
   end
 end