capybara 2.15.0 → 3.0.0

data/lib/capybara/node/actions.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
+
 module Capybara
   module Node
     module Actions
-
       ##
       #
-      # Finds a button or link by id, text or value and clicks it. Also looks at image
-      # alt text inside the link.
+      # Finds a button or link and clicks it.  See {Capybara::Node::Actions#click_button} and
+      # {Capybara::Node::Actions#click_link} for what locator will match against for each type of element
       # @!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
@@ -16,12 +16,11 @@ module Capybara
       #
       # @overload click_link_or_button([locator], options)
       #
-      #   @param [String] locator      Text, id or value of link or button
+      #   @param [String] locator      See {Capybara::Node::Actions#click_button} and {Capybara::Node::Actions#click_link}
       #
       # @return [Capybara::Node::Element]  The element clicked
       #
-      def click_link_or_button(locator=nil, options={})
-        locator, options = nil, locator if locator.is_a? Hash
+      def click_link_or_button(locator = nil, **options)
         find(:link_or_button, locator, options).click
       end
       alias_method :click_on, :click_link_or_button
@@ -38,8 +37,7 @@ module Capybara
       #   @param options                  See {Capybara::Node::Finders#find_link}
       #
       # @return [Capybara::Node::Element]  The element clicked
-      def click_link(locator=nil, options={})
-        locator, options = nil, locator if locator.is_a? Hash
+      def click_link(locator = nil, **options)
         find(:link, locator, options).click
       end
 
@@ -56,8 +54,7 @@ module Capybara
       #   @param [String] locator      Which button to find
       #   @param options     See {Capybara::Node::Finders#find_button}
       # @return [Capybara::Node::Element]  The element clicked
-      def click_button(locator=nil, options={})
-        locator, options = nil, locator if locator.is_a? Hash
+      def click_button(locator = nil, **options)
         find(:button, locator, options).click
       end
 
@@ -80,15 +77,11 @@ module Capybara
       #   @option options [String] :id             Match fields that match the id attribute
       #   @option options [String] :name           Match fields that match the name attribute
       #   @option options [String] :placeholder    Match fields that match the placeholder attribute
-      #   @option options [String, Array<String>] :class    Match links that match the class(es) provided
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
       #
       # @return [Capybara::Node::Element]  The element filled_in
-      def fill_in(locator, options={})
-        locator, options = nil, locator if locator.is_a? Hash
-        raise "Must pass a hash containing 'with'" if not options.is_a?(Hash) or not options.has_key?(:with)
-        with = options.delete(:with)
-        fill_options = options.delete(:fill_options)
-        options[:with] = options.delete(:currently_with) if options.has_key?(:currently_with)
+      def fill_in(locator = nil, with:, fill_options: {}, **options)
+        options[:with] = options.delete(:currently_with) if options.key?(:currently_with)
         find(:fillable_field, locator, options).set(with, fill_options)
       end
 
@@ -108,13 +101,13 @@ module Capybara
       #   @option options [String] :option  Value of the radio_button to choose
       #   @option options [String] :id             Match fields that match the id attribute
       #   @option options [String] :name           Match fields that match the name attribute
-      #   @option options [String, Array<String>] :class    Match links that match the class(es) provided
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
       #   @macro waiting_behavior
       #   @macro label_click
       #
       # @return [Capybara::Node::Element]  The element chosen or the label clicked
-      def choose(locator, options={})
-        _check_with_label(:radio_button, true, locator, options)
+      def choose(locator = nil, **options)
+        _check_with_label(:radio_button, true, locator, **options)
       end
 
       ##
@@ -131,13 +124,13 @@ module Capybara
       #   @option options [String] :option  Value of the checkbox to select
       #   @option options [String] id       Match fields that match the id attribute
       #   @option options [String] name     Match fields that match the name attribute
-      #   @option options [String, Array<String>] :class    Match links that match the class(es) provided
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
       #   @macro label_click
       #   @macro waiting_behavior
       #
       # @return [Capybara::Node::Element]  The element checked or the label clicked
-      def check(locator, options={})
-        _check_with_label(:checkbox, true, locator, options)
+      def check(locator, **options)
+        _check_with_label(:checkbox, true, locator, **options)
       end
 
       ##
@@ -154,13 +147,13 @@ module Capybara
       #   @option options [String] :option  Value of the checkbox to deselect
       #   @option options [String] id       Match fields that match the id attribute
       #   @option options [String] name     Match fields that match the name attribute
-      #   @option options [String, Array<String>] :class    Match links that match the class(es) provided
+      #   @option options [String, Array<String>] :class    Match fields that match the class(es) provided
       #   @macro label_click
       #   @macro waiting_behavior
       #
       # @return [Capybara::Node::Element]  The element unchecked or the label clicked
-      def uncheck(locator, options={})
-        _check_with_label(:checkbox, false, locator, options)
+      def uncheck(locator = nil, **options)
+        _check_with_label(:checkbox, false, locator, **options)
       end
 
       ##
@@ -180,13 +173,9 @@ module Capybara
       # @option options [String] :from  The id, name or label of the select box
       #
       # @return [Capybara::Node::Element]  The option element selected
-      def select(value, options={})
-        if options.has_key?(:from)
-          from = options.delete(:from)
-          find(:select, from, options).find(:option, value, options).select_option
-        else
-          find(:option, value, options).select_option
-        end
+      def select(value = nil, from: nil, **options)
+        scope = from ? find(:select, from, options) : self
+        scope.find(:option, value, options).select_option
       end
 
       ##
@@ -203,13 +192,9 @@ module Capybara
       # @param [Hash{:from => String}] options  The id, name or label of the select box
       #
       # @return [Capybara::Node::Element]  The option element unselected
-      def unselect(value, options={})
-        if options.has_key?(:from)
-          from = options.delete(:from)
-          find(:select, from, options).find(:option, value, options).unselect_option
-        else
-          find(:option, value, options).unselect_option
-        end
+      def unselect(value = nil, from: nil, **options)
+        scope = from ? find(:select, from, options) : self
+        scope.find(:option, value, options).unselect_option
       end
 
       ##
@@ -229,72 +214,48 @@ module Capybara
       # @option options [Boolean] multiple Match field which allows multiple file selection
       # @option options [String] id             Match fields that match the id attribute
       # @option options [String] name           Match fields that match the name attribute
-      # @option options [String, Array<String>] :class    Match links that match the class(es) provided
+      # @option options [String, Array<String>] :class    Match fields that match the class(es) provided
       # @option options [true, Hash] make_visible   A Hash of CSS styles to change before attempting to attach the file, if `true` { opacity: 1, display: 'block', visibility: 'visible' } is used (may not be supported by all drivers)
       #
       # @return [Capybara::Node::Element]  The file field element
-      def attach_file(locator, path, options={})
-        locator, path, options = nil, locator, path if path.is_a? Hash
+      def attach_file(locator = nil, path, make_visible: nil, **options) # rubocop:disable Style/OptionalArguments
         Array(path).each do |p|
           raise Capybara::FileNotFound, "cannot attach file, #{p} does not exist" unless File.exist?(p.to_s)
         end
         # Allow user to update the CSS style of the file input since they are so often hidden on a page
-        if style = options.delete(:make_visible)
-          style = { opacity: 1, display: 'block', visibility: 'visible' } if style == true
-          ff = find(:file_field, locator, options.merge({visible: :all}))
-          _update_style(ff, style)
-          if ff.visible?
-            begin
-              ff.set(path)
-            ensure
-              _reset_style(ff)
-            end
-          else
-            raise ExpectationNotMet, "The style changes in :make_visible did not make the file input visible"
-          end
+        if make_visible
+          ff = find(:file_field, locator, options.merge(visible: :all))
+          while_visible(ff, make_visible) { |el| el.set(path) }
         else
           find(:file_field, locator, options).set(path)
         end
       end
 
     private
-      def _update_style(element, style)
-        script = <<-JS
-          var el = arguments[0];
-          el.capybara_style_cache = el.style.cssText;
-          var css = arguments[1];
-          for (var prop in css){
-            if (css.hasOwnProperty(prop)) {
-              el.style[prop] = css[prop]
-            }
-          }
-        JS
-        begin
-          session.execute_script(script, element, style)
-        rescue Capybara::NotSupportedByDriverError
-          warn "The :make_visible option is not supported by the current driver - ignoring"
-        end
-      end
 
-      def _reset_style(element)
-        script = <<-JS
-          var el = arguments[0];
-          if (el.hasOwnProperty('capybara_style_cache')) {
-            el.style.cssText = el.capybara_style_cache;
-            delete el.capybara_style_cache;
-          }
-        JS
+      def while_visible(element, visible_css)
+        visible_css = { opacity: 1, display: 'block', visibility: 'visible' } if visible_css == true
+        _update_style(element, visible_css)
+        raise ExpectationNotMet, "The style changes in :make_visible did not make the file input visible" unless element.visible?
         begin
-          session.execute_script(script, element)
-        rescue
+          yield element
+        ensure
+          _reset_style(element)
         end
       end
 
+      def _update_style(element, style)
+        session.execute_script(UPDATE_STYLE_SCRIPT, element, style)
+      rescue Capybara::NotSupportedByDriverError
+        warn "The :make_visible option is not supported by the current driver - ignoring"
+      end
 
-      def _check_with_label(selector, checked, locator, options)
-        locator, options = nil, locator if locator.is_a? Hash
-        allow_label_click = options.delete(:allow_label_click) { session_options.automatic_label_click }
+      def _reset_style(element)
+        session.execute_script(RESET_STYLE_SCRIPT, element)
+      rescue # swallow extra errors
+      end
 
+      def _check_with_label(selector, checked, locator, allow_label_click: session_options.automatic_label_click, **options)
         synchronize(Capybara::Queries::BaseQuery.wait(options, session_options.default_max_wait_time)) do
           begin
             el = find(selector, locator, options)
@@ -303,15 +264,33 @@ module Capybara
             raise unless allow_label_click && catch_error?(e)
             begin
               el ||= find(selector, locator, options.merge(visible: :all))
-              label = find(:label, for: el, visible: true)
-              label.click unless (el.checked? == checked)
-            rescue
+              res = find(:label, for: el, visible: true).click unless el.checked? == checked
+              res
+            rescue # swallow extra errors - raise original
               raise e
             end
           end
         end
       end
 
+      UPDATE_STYLE_SCRIPT = <<-'JS'.freeze
+        var el = arguments[0];
+        el.capybara_style_cache = el.style.cssText;
+        var css = arguments[1];
+        for (var prop in css){
+          if (css.hasOwnProperty(prop)) {
+            el.style[prop] = css[prop]
+          }
+        }
+      JS
+
+      RESET_STYLE_SCRIPT = <<-'JS'.freeze
+        var el = arguments[0];
+        if (el.hasOwnProperty('capybara_style_cache')) {
+          el.style.cssText = el.capybara_style_cache;
+          delete el.capybara_style_cache;
+        }
+      JS
     end
   end
 end

data/lib/capybara/node/base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
+
 module Capybara
   module Node
-
     ##
     #
     # A {Capybara::Node::Base} represents either an element on a page through the subclass
@@ -67,26 +67,23 @@ module Capybara
       # 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]
-      # @option options [Array<Exception>] :errors (driver.invalid_element_errors +
+      # @param  [Integer] seconds  (current sessions default_max_wait_time) Maximum number of seconds to retry this block
+      # @param  [Array<Exception>] errors (driver.invalid_element_errors +
       #   [Capybara::ElementNotFound]) exception types that cause the block to be rerun
       # @return [Object]                  The result of the given block
       # @raise  [Capybara::FrozenInTime]  If the return value of `Time.now` appears stuck
       #
-      def synchronize(seconds=session_options.default_max_wait_time, options = {})
-        start_time = Capybara::Helpers.monotonic_time
-
+      def synchronize(seconds = session_options.default_max_wait_time, errors: nil)
         if session.synchronized
           yield
         else
           session.synchronized = true
+          start_time = Capybara::Helpers.monotonic_time
           begin
             yield
           rescue => e
             session.raise_server_error!
-            raise e unless driver.wait?
-            raise e unless catch_error?(e, options[:errors])
+            raise e unless driver.wait? && catch_error?(e, errors)
             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 Capybara::Helpers.monotonic_time == start_time
@@ -108,24 +105,20 @@ module Capybara
         base.find_xpath(xpath)
       end
 
-      # @deprecated Use query_scope instead
-      def parent
-        warn "DEPRECATED: #parent is deprecated in favor of #query_scope - Note: #parent was not the elements parent in the document so it's most likely not what you wanted anyway"
-        query_scope
-      end
-
       # @api private
       def session_options
         session.config
       end
 
+      def to_capybara_node
+        self
+      end
+
     protected
 
       def catch_error?(error, errors = nil)
         errors ||= (driver.invalid_element_errors + [Capybara::ElementNotFound])
-        errors.any? do |type|
-          error.is_a?(type)
-        end
+        errors.any? { |type| error.is_a?(type) }
       end
 
       def driver

data/lib/capybara/node/document.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
+
 module Capybara
   module Node
-
     ##
     #
     # A {Capybara::Document} represents an HTML document. Any operation
@@ -20,7 +20,7 @@ module Capybara
       #
       # @return [String]    The text of the document
       #
-      def text(type=nil)
+      def text(type = nil)
         find(:xpath, '/html').text(type)
       end
 

data/lib/capybara/node/document_matchers.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Capybara
   module Node
     module DocumentMatchers
@@ -15,8 +16,8 @@ module Capybara
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #
-      def assert_title(title, options = {})
-        _verify_title(title,options) { |query| raise Capybara::ExpectationNotMet, query.failure_message unless query.resolves_for?(self) }
+      def assert_title(title, **options)
+        _verify_title(title, options) { |query| raise Capybara::ExpectationNotMet, query.failure_message unless query.resolves_for?(self) }
       end
 
       ##
@@ -26,8 +27,8 @@ module Capybara
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #
-      def assert_no_title(title, options = {})
-        _verify_title(title,options) { |query| raise Capybara::ExpectationNotMet, query.negative_failure_message if query.resolves_for?(self) }
+      def assert_no_title(title, **options)
+        _verify_title(title, options) { |query| raise Capybara::ExpectationNotMet, query.negative_failure_message if query.resolves_for?(self) }
       end
 
       ##
@@ -36,7 +37,7 @@ module Capybara
       # @macro title_query_params
       # @return [Boolean]
       #
-      def has_title?(title, options = {})
+      def has_title?(title, **options)
         assert_title(title, options)
       rescue Capybara::ExpectationNotMet
         return false
@@ -48,13 +49,13 @@ module Capybara
       # @macro title_query_params
       # @return [Boolean]
       #
-      def has_no_title?(title, options = {})
+      def has_no_title?(title, **options)
         assert_no_title(title, options)
       rescue Capybara::ExpectationNotMet
         return false
       end
 
-      private
+    private
 
       def _verify_title(title, options)
         query = Capybara::Queries::TitleQuery.new(title, options)
@@ -63,7 +64,6 @@ module Capybara
         end
         return true
       end
-
     end
   end
 end

data/lib/capybara/node/element.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
+
 module Capybara
   module Node
-
     ##
     #
     # A {Capybara::Node::Element} represents a single element on the page. It is possible
@@ -22,7 +22,6 @@ module Capybara
     # @see Capybara::Node
     #
     class Element < Base
-
       def initialize(session, base, query_scope, query)
         super(session, base)
         @query_scope = query_scope
@@ -54,7 +53,7 @@ module Capybara
       # @param [:all, :visible] type  Whether to return only visible or all text
       # @return [String]              The text of the element
       #
-      def text(type=nil)
+      def text(type = nil)
         type ||= :all unless session_options.ignore_hidden_elements or session_options.visible_text_only
         synchronize do
           if type == :all
@@ -94,23 +93,10 @@ module Capybara
       # @param [Hash{}] options  Driver specific options for how to set the value
       #
       # @return [Capybara::Node::Element]  The element
-      def set(value, options={})
-        options ||= {}
-
-        driver_supports_options = (base.method(:set).arity != 1)
-
-        unless options.empty? || driver_supports_options
-          warn "Options passed to Capybara::Node#set but the driver doesn't support them"
-        end
-
-        synchronize do
-          if driver_supports_options
-            base.set(value, options)
-          else
-            base.set(value)
-          end
-        end
-        return self
+      def set(value, **options)
+        raise Capybara::ReadOnlyElementError, "Attempt to set readonly element with value: #{value}" if readonly?
+        synchronize { base.set(value, options) }
+        self
       end
 
       ##
@@ -121,7 +107,7 @@ module Capybara
       def select_option
         warn "Attempt to select disabled option: #{value || text}" if disabled?
         synchronize { base.select_option }
-        return self
+        self
       end
 
       ##
@@ -131,37 +117,43 @@ module Capybara
       # @return [Capybara::Node::Element]  The element
       def unselect_option
         synchronize { base.unselect_option }
-        return self
+        self
       end
 
       ##
       #
       # Click the Element
       #
+      # @!macro click_modifiers
+      #   @overload $0(*key_modifiers=[], offset={x: nil, y: nil})
+      #     @param [Array<:alt, :control, :meta, :shift>] *key_modifiers  Keys to be held down when clicking
+      #     @param [Hash] offset                          x and y coordinates to offset the click location from the top left corner of the element.  If not specified will click the middle of the element.
       # @return [Capybara::Node::Element]  The element
-      def click
-        synchronize { base.click }
-        return self
+      def click(*keys, **offset)
+        synchronize { base.click(keys, offset) }
+        self
       end
 
       ##
       #
       # Right Click the Element
       #
+      # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
-      def right_click
-        synchronize { base.right_click }
-        return self
+      def right_click(*keys, **offset)
+        synchronize { base.right_click(keys, offset) }
+        self
       end
 
       ##
       #
       # Double Click the Element
       #
+      # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
-      def double_click
-        synchronize { base.double_click }
-        return self
+      def double_click(*keys, **offset)
+        synchronize { base.double_click(keys, offset) }
+        self
       end
 
       ##
@@ -237,7 +229,7 @@ module Capybara
       # @return [Capybara::Node::Element]  The element
       def send_keys(*args)
         synchronize { base.send_keys(*args) }
-        return self
+        self
       end
 
       ##
@@ -247,7 +239,7 @@ module Capybara
       # @return [Capybara::Node::Element]  The element
       def hover
         synchronize { base.hover }
-        return self
+        self
       end
 
       ##
@@ -339,7 +331,7 @@ module Capybara
       # @return [Capybara::Node::Element]  The element
       def trigger(event)
         synchronize { base.trigger(event) }
-        return self
+        self
       end
 
       ##
@@ -355,7 +347,7 @@ module Capybara
       # @return [Capybara::Node::Element]  The element
       def drag_to(node)
         synchronize { base.drag_to(node.base) }
-        return self
+        self
       end
 
       def reload
@@ -371,15 +363,13 @@ module Capybara
       end
 
       def inspect
-        %(#<Capybara::Node::Element tag="#{tag_name}" path="#{path}">)
+        %(#<Capybara::Node::Element tag="#{base.tag_name}" path="#{base.path}">)
       rescue NotSupportedByDriverError
-        %(#<Capybara::Node::Element tag="#{tag_name}">)
+        %(#<Capybara::Node::Element tag="#{base.tag_name}">)
       rescue => e
-        if session.driver.invalid_element_errors.any? { |et| e.is_a?(et)}
-          %(Obsolete #<Capybara::Node::Element>)
-        else
-          raise
-        end
+        raise unless session.driver.invalid_element_errors.any? { |et| e.is_a?(et) }
+
+        %(Obsolete #<Capybara::Node::Element>)
       end
     end
   end