capybara 1.1.4 → 2.0.0

data/lib/capybara/cucumber.rb

@@ -6,8 +6,9 @@ require 'capybara/rspec/matchers'
 World(Capybara::DSL)
 World(Capybara::RSpecMatchers)
 
-After do
+Before do
   Capybara.reset_sessions!
+  Capybara.use_default_driver
 end
 
 Before '@javascript' do
@@ -22,7 +23,3 @@ Before do |scenario|
     end
   end
 end
-
-After do
-  Capybara.use_default_driver
-end

data/lib/capybara/driver/base.rb

@@ -15,7 +15,7 @@ class Capybara::Driver::Base
     raise NotImplementedError
   end
 
-  def body
+  def html
     raise NotImplementedError
   end
 
@@ -27,6 +27,10 @@ class Capybara::Driver::Base
     raise Capybara::NotSupportedByDriverError
   end
 
+  def save_screenshot(path, options={})
+    raise Capybara::NotSupportedByDriverError
+  end
+
   def response_headers
     raise Capybara::NotSupportedByDriverError
   end
@@ -51,14 +55,10 @@ class Capybara::Driver::Base
     false
   end
 
-  def wait_until(*args)
-  end
-
   def reset!
   end
 
-  def has_shortcircuit_timeout?
+  def needs_server?
     false
   end
-
 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
@@ -65,9 +66,9 @@ module Capybara
       end
 
       def inspect
-        %(#<Capybara::Driver::Node tag="#{tag_name}" path="#{path}">)
+        %(#<#{self.class} tag="#{tag_name}" path="#{path}">)
       rescue NotSupportedByDriverError
-        %(#<Capybara::Driver::Node tag="#{tag_name}">)
+        %(#<#{self.class} tag="#{tag_name}">)
       end
     end
   end

data/lib/capybara/dsl.rb

@@ -1,127 +1,20 @@
 require 'capybara'
 
 module Capybara
-  def self.included(base)
-    base.send(:include, Capybara::DSL)
-    warn "`include Capybara` is deprecated please use `include Capybara::DSL` instead."
-  end
-
-  class << self
-    attr_writer :default_driver, :current_driver, :javascript_driver, :session_name
-
-    attr_accessor :app
-
-    ##
-    #
-    # @return [Symbol]    The name of the driver to use by default
-    #
-    def default_driver
-      @default_driver || :rack_test
-    end
-
-    ##
-    #
-    # @return [Symbol]    The name of the driver currently in use
-    #
-    def current_driver
-      @current_driver || default_driver
-    end
-    alias_method :mode, :current_driver
-
-    ##
-    #
-    # @return [Symbol]    The name of the driver used when JavaScript is needed
-    #
-    def javascript_driver
-      @javascript_driver || :selenium
-    end
-
-    ##
-    #
-    # Use the default driver as the current driver
-    #
-    def use_default_driver
-      @current_driver = nil
-    end
-
-    ##
-    #
-    # Yield a block using a specific driver
-    #
-    def using_driver(driver)
-      previous_driver = Capybara.current_driver
-      Capybara.current_driver = driver
-      yield
-    ensure
-      @current_driver = previous_driver
-    end
-
-    ##
-    #
-    # Yield a block using a specific wait time
-    #
-    def using_wait_time(seconds)
-      previous_wait_time = Capybara.default_wait_time
-      Capybara.default_wait_time = seconds
-      yield
-    ensure
-      Capybara.default_wait_time = previous_wait_time
-    end
-
-    ##
-    #
-    # The current Capybara::Session base on what is set as Capybara.app and Capybara.current_driver
-    #
-    # @return [Capybara::Session]     The currently used session
-    #
-    def current_session
-      session_pool["#{current_driver}:#{session_name}:#{app.object_id}"] ||= Capybara::Session.new(current_driver, app)
-    end
-
-    ##
-    #
-    # Reset sessions, cleaning out the pool of sessions. This will remove any session information such
-    # as cookies.
-    #
-    def reset_sessions!
-      session_pool.each { |mode, session| session.reset! }
-    end
-    alias_method :reset!, :reset_sessions!
-
-    ##
-    #
-    # The current session name.
-    #
-    # @return [Symbol]    The name of the currently used session.
-    #
-    def session_name
-      @session_name ||= :default
-    end
-
-    ##
-    #
-    # Yield a block using a specific session name.
-    #
-    def using_session(name)
-      self.session_name = name
-      yield
-    ensure
-      self.session_name = :default
+  module DSL
+    def self.included(base)
+      warn "including Capybara::DSL in the global scope is not recommended!" if base == Object
+      super
     end
 
-  private
-
-    def session_pool
-      @session_pool ||= {}
+    def self.extended(base)
+      warn "extending the main object with Capybara::DSL is not recommended!" if base == TOPLEVEL_BINDING.eval("self")
+      super
     end
-  end
-
-  module DSL
 
     ##
     #
-    # Shortcut to working in a different session. This is useful when Capybara is included
-    # in a class or module.
+    # Shortcut to working in a different session.
     #
     def using_session(name, &block)
       Capybara.using_session(name, &block)
@@ -129,8 +22,7 @@ module Capybara
 
     ##
     #
-    # Shortcut to working in a different session. This is useful when Capybara is included
-    # in a class or module.
+    # Shortcut to using a different wait time.
     #
     def using_wait_time(seconds, &block)
       Capybara.using_wait_time(seconds, &block)
@@ -138,8 +30,7 @@ module Capybara
 
     ##
     #
-    # Shortcut to accessing the current session. This is useful when Capybara is included in a
-    # class or module.
+    # Shortcut to accessing the current session.
     #
     #     class MyClass
     #       include Capybara::DSL
@@ -156,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

@@ -10,8 +10,7 @@ module Capybara
       # @param [String] locator      Text, id or value of link or button
       #
       def click_link_or_button(locator)
-        msg = "no link or button '#{locator}' found"
-        find(:xpath, XPath::HTML.link_or_button(locator), :message => msg).click
+        find(:link_or_button, locator).click
       end
       alias_method :click_on, :click_link_or_button
 
@@ -23,8 +22,7 @@ module Capybara
       # @param [String] locator      Text, id or text of link
       #
       def click_link(locator)
-        msg = "no link with title, id or text '#{locator}' found"
-        find(:xpath, XPath::HTML.link(locator), :message => msg).click
+        find(:link, locator).click
       end
 
       ##
@@ -34,8 +32,7 @@ module Capybara
       # @param [String] locator      Text, id or value of button
       #
       def click_button(locator)
-        msg = "no button with value or id or text '#{locator}' found"
-        find(:xpath, XPath::HTML.button(locator), :message => msg).click
+        find(:button, locator).click
       end
 
       ##
@@ -49,9 +46,8 @@ module Capybara
       # @param [Hash{:with => String}]    The value to fill in
       #
       def fill_in(locator, options={})
-        msg = "cannot fill in, no text field, text area or password field with id, name, or label '#{locator}' found"
         raise "Must pass a hash containing 'with'" if not options.is_a?(Hash) or not options.has_key?(:with)
-        find(:xpath, XPath::HTML.fillable_field(locator), :message => msg).set(options[:with])
+        find(:fillable_field, locator).set(options[:with])
       end
 
       ##
@@ -64,8 +60,7 @@ module Capybara
       # @param [String] locator           Which radio button to choose
       #
       def choose(locator)
-        msg = "cannot choose field, no radio button with id, name, or label '#{locator}' found"
-        find(:xpath, XPath::HTML.radio_button(locator), :message => msg).set(true)
+        find(:radio_button, locator).set(true)
       end
 
       ##
@@ -78,8 +73,7 @@ module Capybara
       # @param [String] locator           Which check box to check
       #
       def check(locator)
-        msg = "cannot check field, no checkbox with id, name, or label '#{locator}' found"
-        find(:xpath, XPath::HTML.checkbox(locator), :message => msg).set(true)
+        find(:checkbox, locator).set(true)
       end
 
       ##
@@ -92,8 +86,7 @@ module Capybara
       # @param [String] locator           Which check box to uncheck
       #
       def uncheck(locator)
-        msg = "cannot uncheck field, no checkbox with id, name, or label '#{locator}' found"
-        find(:xpath, XPath::HTML.checkbox(locator), :message => msg).set(false)
+        find(:checkbox, locator).set(false)
       end
 
       ##
@@ -109,13 +102,9 @@ module Capybara
       #
       def select(value, options={})
         if options.has_key?(:from)
-          no_select_msg = "cannot select option, no select box with id, name, or label '#{options[:from]}' found"
-          no_option_msg = "cannot select option, no option with text '#{value}' in select box '#{options[:from]}'"
-          select = find(:xpath, XPath::HTML.select(options[:from]), :message => no_select_msg)
-          select.find(:xpath, XPath::HTML.option(value), :message => no_option_msg).select_option
+          find(:select, options[:from]).find(:option, value).select_option
         else
-          no_option_msg = "cannot select option, no option with text '#{value}'"
-          find(:xpath, XPath::HTML.option(value), :message => no_option_msg).select_option
+          find(:option, value).select_option
         end
       end
 
@@ -132,13 +121,9 @@ module Capybara
       #
       def unselect(value, options={})
         if options.has_key?(:from)
-          no_select_msg = "cannot unselect option, no select box with id, name, or label '#{options[:from]}' found"
-          no_option_msg = "cannot unselect option, no option with text '#{value}' in select box '#{options[:from]}'"
-          select = find(:xpath, XPath::HTML.select(options[:from]), :message => no_select_msg)
-          select.find(:xpath, XPath::HTML.option(value), :message => no_option_msg).unselect_option
+          find(:select, options[:from]).find(:option, value).unselect_option
         else
-          no_option_msg = "cannot unselect option, no option with text '#{value}'"
-          find(:xpath, XPath::HTML.option(value), :message => no_option_msg).unselect_option
+          find(:option, value).unselect_option
         end
       end
 
@@ -150,12 +135,13 @@ 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)
-        msg = "cannot attach file, no file field with id, name, or label '#{locator}' found"
-        find(:xpath, XPath::HTML.file_field(locator), :message => msg).set(path)
+        (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
   end

data/lib/capybara/node/base.rb

@@ -33,29 +33,52 @@ module Capybara
         @base = base
       end
 
+      # overridden in subclasses, e.g. Capybara::Node::Element
       def reload
         self
       end
 
-      def without_wait
-        orig = @wait_disabled
-        @wait_disabled = true
-        yield
-      ensure
-        @wait_disabled = orig
-      end
-
-    protected
-
-      def wait_until(seconds=Capybara.default_wait_time)
+      ##
+      #
+      # 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 @wait_disabled
+          raise e if @unsynchronized
           raise e unless driver.wait?
-          raise e unless (driver.respond_to?(:invalid_element_errors) and 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
@@ -64,6 +87,26 @@ 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
         session.driver
       end

data/lib/capybara/node/element.rb

@@ -22,10 +22,10 @@ module Capybara
     #
     class Element < Base
 
-      def initialize(session, base, parent, selector)
+      def initialize(session, base, parent, query)
         super(session, base)
         @parent = parent
-        @selector = selector
+        @query = query
       end
 
       def allow_reload!
@@ -37,7 +37,7 @@ module Capybara
       # @return [Object]    The native element from the driver, this allows access to driver specific methods
       #
       def native
-        wait_until { base.native }
+        synchronize { base.native }
       end
 
       ##
@@ -45,7 +45,7 @@ module Capybara
       # @return [String]    The text of the element
       #
       def text
-        wait_until { base.text }
+        synchronize { base.text }
       end
 
       ##
@@ -58,7 +58,7 @@ module Capybara
       # @return [String]               The value of the attribute
       #
       def [](attribute)
-        wait_until { base[attribute] }
+        synchronize { base[attribute] }
       end
 
       ##
@@ -66,7 +66,7 @@ module Capybara
       # @return [String]    The value of the form element
       #
       def value
-        wait_until { base.value }
+        synchronize { base.value }
       end
 
       ##
@@ -76,7 +76,7 @@ module Capybara
       # @param [String] value    The new value
       #
       def set(value)
-        wait_until { base.set(value) }
+        synchronize { base.set(value) }
       end
 
       ##
@@ -84,7 +84,7 @@ module Capybara
       # Select this node if is an option element inside a select tag
       #
       def select_option
-        wait_until { base.select_option }
+        synchronize { base.select_option }
       end
 
       ##
@@ -92,7 +92,7 @@ module Capybara
       # Unselect this node if is an option element inside a multiple select tag
       #
       def unselect_option
-        wait_until { base.unselect_option }
+        synchronize { base.unselect_option }
       end
 
       ##
@@ -100,7 +100,7 @@ module Capybara
       # Click the Element
       #
       def click
-        wait_until { base.click }
+        synchronize { base.click }
       end
 
       ##
@@ -108,7 +108,7 @@ module Capybara
       # @return [String]      The tag name of the element
       #
       def tag_name
-        wait_until { base.tag_name }
+        synchronize { base.tag_name }
       end
 
       ##
@@ -119,7 +119,7 @@ module Capybara
       # @return [Boolean]     Whether the element is visible
       #
       def visible?
-        wait_until { base.visible? }
+        synchronize { base.visible? }
       end
 
       ##
@@ -129,7 +129,7 @@ module Capybara
       # @return [Boolean]     Whether the element is checked
       #
       def checked?
-        wait_until { base.checked? }
+        synchronize { base.checked? }
       end
 
       ##
@@ -139,7 +139,7 @@ module Capybara
       # @return [Boolean]     Whether the element is selected
       #
       def selected?
-        wait_until { base.selected? }
+        synchronize { base.selected? }
       end
 
       ##
@@ -149,7 +149,7 @@ module Capybara
       # @return [String]      An XPath expression
       #
       def path
-        wait_until { base.path }
+        synchronize { base.path }
       end
 
       ##
@@ -160,7 +160,7 @@ module Capybara
       # @param [String] event       The name of the event to trigger
       #
       def trigger(event)
-        wait_until { base.trigger(event) }
+        synchronize { base.trigger(event) }
       end
 
       ##
@@ -174,24 +174,12 @@ module Capybara
       # @param [Capybara::Element] node     The element to drag to
       #
       def drag_to(node)
-        wait_until { base.drag_to(node.base) }
-      end
-
-      def find(*args)
-        wait_until { super }
-      end
-
-      def first(*args)
-        wait_until { super }
-      end
-
-      def all(*args)
-        wait_until { super }
+        synchronize { base.drag_to(node.base) }
       end
 
       def reload
         if @allow_reload
-          reloaded = parent.reload.first(@selector.name, @selector.locator, @selector.options)
+          reloaded = parent.reload.first(@query.name, @query.locator, @query.options)
           @base = reloaded.base if reloaded
         end
         self