capybara 2.4.4 → 2.5.0

data/lib/capybara/node/actions.rb

@@ -16,12 +16,11 @@ module Capybara
 
       ##
       #
-      # Finds a link by id or text and clicks it. Also looks at image
+      # Finds a link by id, text or title and clicks it. Also looks at image
       # alt text inside the link.
       #
-      # @param [String] locator      Text or id of link
-      # @param options
-      # @option options [String] :href    The value the href attribute must be
+      # @param [String] locator         text, id, title or nested image's alt attribute
+      # @param options                  See {Capybara::Node::Finders#find_link}
       #
       def click_link(locator, options={})
         find(:link, locator, options).click
@@ -29,10 +28,13 @@ module Capybara
 
       ##
       #
-      # Finds a button by id, text or value and clicks it.
-      #
-      # @param [String] locator      Text, id or value of button
+      # Finds a button on the page and clicks it.
+      # This can be any \<input> element of type submit, reset, image, button or it can be a
+      # \<button> element. All buttons can be found by their id, value, or title. \<button> elements can also be found
+      # by their text content, and image \<input> elements by their alt attribute
       #
+      # @param [String] locator      Which button to find
+      # @param options     See {Capybara::Node::Finders#find_button}
       def click_button(locator, options={})
         find(:button, locator, options).click
       end
@@ -97,14 +99,17 @@ module Capybara
 
       ##
       #
-      # Find a select box on the page and select a particular option from it. If the select
-      # box is a multiple select, +select+ can be called multiple times to select more than
-      # one option. The select box can be found via its name, id or label text.
+      # If `:from` option is present, `select` finds a select box on the page
+      # and selects a particular option from it.
+      # Otherwise it finds an option inside current scope and selects it.
+      # If the select box is a multiple select, +select+ can be called multiple times to select more than
+      # one option.
+      # The select box can be found via its name, id or label text. The option can be found by its text.
       #
       #     page.select 'March', :from => 'Month'
       #
       # @param [String] value                   Which option to select
-      # @param [Hash{:from => String}] options  The id, name or label of the select box
+      # @option options [String] :from  The id, name or label of the select box
       #
       def select(value, options={})
         if options.has_key?(:from)

data/lib/capybara/node/base.rb

@@ -61,10 +61,10 @@ module Capybara
       #
       # 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 overridden through the `seconds`
+      # {Capybara.default_max_wait_time} and can be overridden 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`.
+      # time has passed. On rubies/platforms which don't support access to a monotonic process clock
+      # 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
       # @param options [Hash]
@@ -73,8 +73,8 @@ module Capybara
       # @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, options = {})
-        start_time = Time.now
+      def synchronize(seconds=Capybara.default_max_wait_time, options = {})
+        start_time = Capybara::Helpers.monotonic_time
 
         if session.synchronized
           yield
@@ -86,9 +86,9 @@ module Capybara
             session.raise_server_error!
             raise e unless driver.wait?
             raise e unless catch_error?(e, options[:errors])
-            raise e if (Time.now - start_time) >= seconds
+            raise e if (Capybara::Helpers.monotonic_time - 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
+            raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead" if Capybara::Helpers.monotonic_time == start_time
             reload if Capybara.automatic_reload
             retry
           ensure

data/lib/capybara/node/document_matchers.rb

@@ -9,7 +9,7 @@ module Capybara
       #     @param string [String]           The string that title should include
       #   @overload $0(regexp, options = {})
       #     @param regexp [Regexp]           The regexp that title should match to
-      #   @option options [Numeric] :wait (Capybara.default_wait_time) Time that Capybara will wait for title to eq/match given string/regexp argument
+      #   @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time that Capybara will wait for title to eq/match given string/regexp argument
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #

data/lib/capybara/node/element.rb

@@ -3,7 +3,7 @@ module Capybara
 
     ##
     #
-    # A {Capybara::Element} represents a single element on the page. It is possible
+    # A {Capybara::Node::Element} represents a single element on the page. It is possible
     # to interact with the contents of this element the same as with a document:
     #
     #     session = Capybara::Session.new(:rack_test, my_app)
@@ -11,7 +11,7 @@ module Capybara
     #     bar = session.find('#bar')              # from Capybara::Node::Finders
     #     bar.select('Baz', :from => 'Quox')      # from Capybara::Node::Actions
     #
-    # {Capybara::Element} also has access to HTML attributes and other properties of the
+    # {Capybara::Node::Element} also has access to HTML attributes and other properties of the
     # element:
     #
     #      bar.value
@@ -93,10 +93,10 @@ module Capybara
       #
       def set(value, options={})
         options ||= {}
-        
+
         driver_supports_options = (base.method(:set).arity != 1)
 
-        unless options.empty? || driver_supports_options 
+        unless options.empty? || driver_supports_options
           warn "Options passed to Capybara::Node#set but the driver doesn't support them"
         end
 
@@ -114,6 +114,7 @@ module Capybara
       # Select this node if is an option element inside a select tag
       #
       def select_option
+        warn "Attempt to select disabled option: #{value || text}" if disabled?
         synchronize { base.select_option }
       end
 
@@ -149,6 +150,80 @@ module Capybara
         synchronize { base.double_click }
       end
 
+      ##
+      #
+      # Send Keystrokes to the Element
+      #
+      # @overload send_keys(keys, ...)
+      #   @param [String, Symbol, Array<String,Symbol>] keys
+      #
+      # Examples:
+      #
+      #     element.send_keys "foo"                     #=> value: 'foo'
+      #     element.send_keys "tet", :left, "s"   #=> value: 'test'
+      #     element.send_keys [:control, 'a'], :space   #=> value: ' ' - assuming ctrl-a selects all contents
+      #
+      # Symbols supported for keys
+      # :cancel
+      # :help
+      # :backspace
+      # :tab
+      # :clear
+      # :return
+      # :enter
+      # :shift
+      # :control
+      # :alt
+      # :pause
+      # :escape
+      # :space
+      # :page_up
+      # :page_down
+      # :end
+      # :home
+      # :left
+      # :up
+      # :right
+      # :down
+      # :insert
+      # :delete
+      # :semicolon
+      # :equals
+      # :numpad0
+      # :numpad1
+      # :numpad2
+      # :numpad3
+      # :numpad4
+      # :numpad5
+      # :numpad6
+      # :numpad7
+      # :numpad8
+      # :numpad9
+      # :multiply      - numeric keypad *
+      # :add           - numeric keypad +
+      # :separator     - numeric keypad 'separator' key ??
+      # :subtract      - numeric keypad -
+      # :decimal       - numeric keypad .
+      # :divide        - numeric keypad /
+      # :f1
+      # :f2
+      # :f3
+      # :f4
+      # :f5
+      # :f6
+      # :f7
+      # :f8
+      # :f9
+      # :f10
+      # :f11
+      # :f12
+      # :meta
+      # :command      - alias of :meta
+      #
+      def send_keys(*args)
+        synchronize { base.send_keys(*args) }
+      end
+
       ##
       #
       # Hover on the Element
@@ -235,7 +310,7 @@ module Capybara
       #     target = page.find('#bar')
       #     source.drag_to(target)
       #
-      # @param [Capybara::Element] node     The element to drag to
+      # @param [Capybara::Node::Element] node     The element to drag to
       #
       def drag_to(node)
         synchronize { base.drag_to(node.base) }
@@ -254,9 +329,9 @@ module Capybara
       end
 
       def inspect
-        %(#<Capybara::Element tag="#{tag_name}" path="#{path}">)
+        %(#<Capybara::Node::Element tag="#{tag_name}" path="#{path}">)
       rescue NotSupportedByDriverError
-        %(#<Capybara::Element tag="#{tag_name}">)
+        %(#<Capybara::Node::Element tag="#{tag_name}">)
       end
     end
   end

data/lib/capybara/node/finders.rb

@@ -4,13 +4,15 @@ module Capybara
 
       ##
       #
-      # Find an {Capybara::Element} based on the given arguments. +find+ will raise an error if the element
+      # Find an {Capybara::Node::Element} based on the given arguments. +find+ will raise an error if the element
       # is not found.
       #
-      # If the driver is capable of executing JavaScript, +find+ will wait for a set amount of time
-      # and continuously retry finding the element until either the element is found or the time
-      # expires. The length of time +find+ will wait is controlled through {Capybara.default_wait_time}
-      # and defaults to 2 seconds.
+      # @!macro waiting_behavior
+      #   If the driver is capable of executing JavaScript, +$0+ will wait for a set amount of time
+      #   and continuously retry finding the element until either the element is found or the time
+      #   expires. The length of time +find+ will wait is controlled through {Capybara.default_max_wait_time}
+      #   and defaults to 2 seconds.
+      #   @option options [false, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
       #
       # +find+ takes the same options as +all+.
       #
@@ -19,10 +21,10 @@ module Capybara
       #     page.find('li', :text => 'Quox').click_link('Delete')
       #
       # @param (see Capybara::Node::Finders#all)
+      #
       # @option options [Boolean] match        The matching strategy to use.
-      # @option options [false, Numeric] wait  How long to wait for the element to appear.
       #
-      # @return [Capybara::Element]            The found element
+      # @return [Capybara::Node::Element]      The found element
       # @raise  [Capybara::ElementNotFound]    If the element can't be found before time expires
       #
       def find(*args)
@@ -48,8 +50,17 @@ module Capybara
       #
       # Find a form field on the page. The field can be found by its name, id or label text.
       #
-      # @param [String] locator       Which field to find
-      # @return [Capybara::Element]   The found element
+      # @macro waiting_behavior
+      #
+      # @param [String] locator             Which field to find
+      #
+      # @option options [Boolean] checked  Match checked field?
+      # @option options [Boolean] unchecked   Match unchecked field?
+      # @option options [Boolean] disabled (false)  Match disabled field?
+      # @option options [Boolean] readonly Match readonly field?
+      # @option options [String] with   Value of field to match on
+      # @option options [String] type   Type of field to match on
+      # @return [Capybara::Node::Element]   The found element
       #
       def find_field(locator, options={})
         find(:field, locator, options)
@@ -60,8 +71,11 @@ module Capybara
       #
       # Find a link on the page. The link can be found by its id or text.
       #
-      # @param [String] locator       Which link to find
-      # @return [Capybara::Element]   The found element
+      # @macro waiting_behavior
+      #
+      # @param [String] locator             Which link to find
+      # @option options [String,Regexp] href        Value to match against the links href
+      # @return [Capybara::Node::Element]   The found element
       #
       def find_link(locator, options={})
         find(:link, locator, options)
@@ -69,10 +83,16 @@ module Capybara
 
       ##
       #
-      # Find a button on the page. The button can be found by its id, name or value.
+      # Find a button on the page.
+      # This can be any \<input> element of type submit, reset, image, button or it can be a
+      # \<button> element. All buttons can be found by their id, value, or title. \<button> elements can also be found
+      # by their text content, and image \<input> elements by their alt attribute
+
+      # @macro waiting_behavior
       #
-      # @param [String] locator       Which button to find
-      # @return [Capybara::Element]   The found element
+      # @param [String] locator             Which button to find
+      # @option options [Boolean] disabled (false)  Match disabled button?
+      # @return [Capybara::Node::Element]   The found element
       #
       def find_button(locator, options={})
         find(:button, locator, options)
@@ -82,8 +102,11 @@ module Capybara
       #
       # Find a element on the page, given its id.
       #
-      # @param [String] id            Which element to find
-      # @return [Capybara::Element]   The found element
+      # @macro waiting_behavior
+      #
+      # @param [String] id                  Which element to find
+      #
+      # @return [Capybara::Node::Element]   The found element
       #
       def find_by_id(id, options={})
         find(:id, id, options)
@@ -117,8 +140,9 @@ module Capybara
       #     page.all('#menu li', :visible => true)
       #
       # By default if no elements are found, an empty array is returned;
-      # however, expectations can be set on the number of elements to be
-      # found using:
+      # however, expectations can be set on the number of elements to be found which
+      # will trigger Capybara's waiting behavior for the expectations to match.The
+      # expectations can be set using
       #
       #     page.assert_selector('p#foo', :count => 4)
       #     page.assert_selector('p#foo', :maximum => 10)
@@ -132,13 +156,18 @@ module Capybara
       #   @param [:css, :xpath] kind                 The type of selector
       #   @param [String] locator                    The selector
       #   @option options [String, Regexp] text      Only find elements which contain this text or match this regexp
-      #   @option options [Boolean] visible          Only find elements that are visible on the page. Setting this to false
-      #                                              finds invisible _and_ visible elements.
+      #   @option options [Boolean, Symbol] visible  Only find elements with the specified visibility:
+      #                                              * true - only finds visible elements.
+      #                                              * false - finds invisible _and_ visible elements.
+      #                                              * :all - same as false; finds visible and invisible elements.
+      #                                              * :hidden - only finds invisible elements.
+      #                                              * :visible - same as true; only finds visible elements.
       #   @option options [Integer] count            Exact number of matches that are expected to be found
       #   @option options [Integer] maximum          Maximum number of matches that are expected to be found
       #   @option options [Integer] minimum          Minimum number of matches that are expected to be found
       #   @option options [Range]   between          Number of matches found must be within the given range
       #   @option options [Boolean] exact            Control whether `is` expressions in the given XPath match exactly or partially
+      #   @option options [Integer] wait (Capybara.default_max_wait_time)  The time to wait for element count expectations to become true
       # @return [Capybara::Result]                   A collection of found elements
       #
       def all(*args)
@@ -149,20 +178,31 @@ module Capybara
           result
         end
       end
+      alias_method :find_all, :all
 
       ##
       #
       # Find the first element on the page matching the given selector
-      # and options, or nil if no element matches.
+      # and options, or nil if no element matches.  By default no waiting
+      # behavior occurs, however if {Capybara.wait_on_first_by_default} is set to true
+      # it will trigger Capybara's waiting behavior for a minimum of 1 matching element to be found and
+      # return the first.  Waiting behavior can also be triggered by passing in any of the count
+      # expectation options.
       #
       # @overload first([kind], locator, options)
       #   @param [:css, :xpath] kind                 The type of selector
       #   @param [String] locator                    The selector
       #   @param [Hash] options                      Additional options; see {#all}
-      # @return [Capybara::Element]                  The found element or nil
+      # @return [Capybara::Node::Element]            The found element or nil
       #
       def first(*args)
+        if Capybara.wait_on_first_by_default
+          options = if args.last.is_a?(Hash) then args.pop.dup else {} end
+          args.push({minimum: 1}.merge(options))
+        end
         all(*args).first
+      rescue Capybara::ExpectationNotMet
+        nil
       end
     end
   end

data/lib/capybara/node/matchers.rb

@@ -220,7 +220,7 @@ module Capybara
       #
       # @param [String] locator           The text or id of a link to check for
       # @param options
-      # @option options [String] :href    The value the href attribute must be
+      # @option options [String, Regexp] :href    The value the href attribute must be
       # @return [Boolean]                 Whether it exists
       #
       def has_link?(locator, options={})
@@ -437,14 +437,14 @@ module Capybara
       #     @option options [Integer] :minimum (nil)   Minimum number of times the text is expected to occur
       #     @option options [Integer] :maximum (nil)   Maximum number of times the text is expected to occur
       #     @option options [Range]   :between (nil)   Range of times that is expected to contain number of times text occurs
-      #     @option options [Numeric] :wait (Capybara.default_wait_time)      Time that Capybara will wait for text to eq/match given string/regexp argument
+      #     @option options [Numeric] :wait (Capybara.default_max_wait_time)      Maximum time that Capybara will wait for text to eq/match given string/regexp argument
       #   @overload $0(text, options = {})
       #     @param [String, Regexp] text               The string/regexp to check for. If it's a string, text is expected to include it. If it's a regexp, text is expected to match it.
       #     @option options [Integer] :count (nil)     Number of times the text is expected to occur
       #     @option options [Integer] :minimum (nil)   Minimum number of times the text is expected to occur
       #     @option options [Integer] :maximum (nil)   Maximum number of times the text is expected to occur
       #     @option options [Range]   :between (nil)   Range of times that is expected to contain number of times text occurs
-      #     @option options [Numeric] :wait (Capybara.default_wait_time)      Time that Capybara will wait for text to eq/match given string/regexp argument
+      #     @option options [Numeric] :wait (Capybara.default_max_wait_time)      Maximum time that Capybara will wait for text to eq/match given string/regexp argument
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #

data/lib/capybara/node/simple.rb

@@ -146,7 +146,12 @@ module Capybara
       end
 
       def title
-        native.xpath("//title").first.text
+        if native.respond_to? :title
+          native.title
+        else
+          #old versions of nokogiri don't have #title - remove in 3.0
+          native.xpath('/html/head/title | /html/title').first.text
+        end
       end
 
       def inspect

data/lib/capybara/queries/base_query.rb

@@ -10,7 +10,7 @@ module Capybara
         if @options.has_key?(:wait)
           @options[:wait] || 0
         else
-          Capybara.default_wait_time
+          Capybara.default_max_wait_time
         end
       end