capybara 3.20.0 → 3.21.0

data/lib/capybara/node/element.rb

@@ -43,7 +43,7 @@ module Capybara
 
       ##
       #
-      # Retrieve the text of the element. If `Capybara.ignore_hidden_elements`
+      # Retrieve the text of the element. If {Capybara.configure ignore_hidden_elements}
       # is `true`, which it is by default, then this will return only text
       # which is visible. The exact semantics of this may differ between
       # drivers, but generally any text within elements with `display:none` is
@@ -61,7 +61,7 @@ module Capybara
 
       ##
       #
-      # Retrieve the given attribute
+      # Retrieve the given attribute.
       #
       #     element[:title] # => HTML title attribute
       #
@@ -74,7 +74,7 @@ module Capybara
 
       ##
       #
-      # Retrieve the given CSS styles
+      # Retrieve the given CSS styles.
       #
       #     element.style('color', 'font-size') # => Computed values of CSS 'color' and 'font-size' styles
       #
@@ -109,7 +109,7 @@ module Capybara
       # Set the value of the form element to the given value.
       #
       # @param [String] value    The new value
-      # @param [Hash{}] options  Driver specific options for how to set the value. Take default values from `Capybara#default_set_options` - See {Capybara::configure}
+      # @param [Hash] options    Driver specific options for how to set the value. Take default values from {Capybara.configure default_set_options}.
       #
       # @return [Capybara::Node::Element]  The element
       def set(value, **options)
@@ -122,8 +122,15 @@ module Capybara
 
       ##
       #
-      # Select this node if is an option element inside a select tag
+      # Select this node if it is an option element inside a select tag.
       #
+      # @!macro action_waiting_behavior
+      #   If the driver dynamic pages (JS) and the element is currently non-interactable, this method will
+      #   continuously retry the action until either the element becomes interactable or the maximum
+      #   wait time expires.
+      #
+      #   @param [false, Numeric] wait
+      #     Maximum time to wait for the action to succeed. Defaults to {Capybara.configure default_max_wait_time}.
       # @return [Capybara::Node::Element]  The element
       def select_option(wait: nil)
         synchronize(wait) { base.select_option }
@@ -132,8 +139,9 @@ module Capybara
 
       ##
       #
-      # Unselect this node if is an option element inside a multiple select tag
+      # Unselect this node if it is an option element inside a multiple select tag.
       #
+      # @macro action_waiting_behavior
       # @return [Capybara::Node::Element]  The element
       def unselect_option(wait: nil)
         synchronize(wait) { base.unselect_option }
@@ -142,11 +150,12 @@ module Capybara
 
       ##
       #
-      # Click the Element
+      # Click the Element.
       #
+      # @macro action_waiting_behavior
       # @!macro click_modifiers
-      #   Both x: and y: must be specified if an offset is wanted, if not specified the click will occur at the middle of the element
-      #   @overload $0(*modifier_keys, **offset)
+      #   Both x: and y: must be specified if an offset is wanted, if not specified the click will occur at the middle of the element.
+      #   @overload $0(*modifier_keys, wait: nil, **offset)
       #     @param *modifier_keys [:alt, :control, :meta, :shift] ([]) Keys to be held down when clicking
       #     @option offset [Integer] x  X coordinate to offset the click location from the top left corner of the element
       #     @option offset [Integer] y  Y coordinate to offset the click location from the top left corner of the element
@@ -160,8 +169,9 @@ module Capybara
 
       ##
       #
-      # Right Click the Element
+      # Right Click the Element.
       #
+      # @macro action_waiting_behavior
       # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
       def right_click(*keys, wait: nil, **offset)
@@ -173,8 +183,9 @@ module Capybara
 
       ##
       #
-      # Double Click the Element
+      # Double Click the Element.
       #
+      # @macro action_waiting_behavior
       # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
       def double_click(*keys, wait: nil, **offset)
@@ -186,7 +197,7 @@ module Capybara
 
       ##
       #
-      # Send Keystrokes to the Element
+      # Send Keystrokes to the Element.
       #
       # @overload send_keys(keys, ...)
       #   @param keys [String, Symbol, Array<String,Symbol>]
@@ -194,65 +205,65 @@ module Capybara
       # Examples:
       #
       #     element.send_keys "foo"                     #=> value: 'foo'
-      #     element.send_keys "tet", :left, "s"   #=> value: 'test'
+      #     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
+      # 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
       #
       # @return [Capybara::Node::Element]  The element
       def send_keys(*args)
@@ -262,7 +273,7 @@ module Capybara
 
       ##
       #
-      # Hover on the Element
+      # Hover on the Element.
       #
       # @return [Capybara::Node::Element]  The element
       def hover
@@ -276,7 +287,7 @@ module Capybara
       #
       def tag_name
         # Element type is immutable so cache it
-        @tag_name ||= synchronize { base.tag_name }
+        @tag_name ||= initial_cache[:tag_name] || synchronize { base.tag_name }
       end
 
       ##
@@ -353,7 +364,7 @@ module Capybara
 
       ##
       #
-      # An XPath expression describing where on the page the element can be found
+      # An XPath expression describing where on the page the element can be found.
       #
       # @return [String]      An XPath expression
       #
@@ -394,17 +405,41 @@ module Capybara
 
       ##
       #
-      # Scroll the page or element
+      # Drop items on the current element.
+      #
+      #     target = page.find('#foo')
+      #     target.drop('/some/path/file.csv')
+      #
+      # @overload drop(path, ...)
+      #   @param [String, #to_path] path Location of the file to drop on the element
+      #
+      # @overload drop(strings, ...)
+      #   @param [Hash] strings A hash of type to data to be dropped - `{ "text/url" => "https://www.google.com" }`
+      #
+      # @return [Capybara::Node::Element]  The element
+      def drop(*args)
+        options = args.map do |arg|
+          return arg.to_path if arg.respond_to?(:to_path)
+
+          arg
+        end
+        synchronize { base.drop(*options) }
+        self
+      end
+
+      ##
+      #
+      # Scroll the page or element.
       #
-      # Scroll the page or element to its top, bottom or middle
       # @overload scroll_to(position, offset: [0,0])
+      #   Scroll the page or element to its top, bottom or middle.
       #   @param [:top, :bottom, :center, :current] position
-      #   @param :offset
+      #   @param [[Integer, Integer]] offset
       #
-      # Scroll the page or current element until the given element is aligned at the top, bottom, or center of it
       # @overload scroll_to(element, align: :top)
+      #   Scroll the page or current element until the given element is aligned at the top, bottom, or center of it.
       #   @param [Capybara::Node::Element] element   The element to be scrolled into view
-      #   @param [:top, :bottom, :center] :align Where to align the element being scrolled into view with relation to the current page/element if possible
+      #   @param [:top, :bottom, :center] align Where to align the element being scrolled into view with relation to the current page/element if possible
       #
       # @overload scroll_to(x,y)
       #   @param [Integer] x    Horizontal scroll offset
@@ -427,11 +462,11 @@ module Capybara
       ##
       #
       # Execute the given JS in the context of the element not returning a result. This is useful for scripts that return
-      # complex objects, such as jQuery statements. +execute_script+ should be used over
-      # +evaluate_script+ whenever possible. `this` in the script will refer to the element this is called on.
+      # complex objects, such as jQuery statements. {#execute_script} should be used over
+      # {#evaluate_script} whenever a result is not expected or needed. `this` in the script will refer to the element this is called on.
       #
       # @param [String] script   A string of JavaScript to execute
-      # @param args  Optional arguments that will be passed to the script.  Driver support for this is optional and types of objects supported may differ between drivers
+      # @param args  Optional arguments that will be passed to the script. Driver support for this is optional and types of objects supported may differ between drivers
       #
       def execute_script(script, *args)
         session.execute_script(<<~JS, self, *args)
@@ -444,7 +479,7 @@ module Capybara
       ##
       #
       # Evaluate the given JS in the context of the element and return the result. Be careful when using this with
-      # scripts that return complex objects, such as jQuery statements. +execute_script+ might
+      # scripts that return complex objects, such as jQuery statements. {#execute_script} might
       # be a better alternative. `this` in the script will refer to the element this is called on.
       #
       # @param  [String] script   A string of JavaScript to evaluate
@@ -462,7 +497,7 @@ module Capybara
       #
       # Evaluate the given JavaScript in the context of the element and obtain the result from a
       # callback function which will be passed as the last argument to the script. `this` in the
-      # script will refer to the element this is called on
+      # script will refer to the element this is called on.
       #
       # @param  [String] script   A string of JavaScript to evaluate
       # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
@@ -475,6 +510,7 @@ module Capybara
         JS
       end
 
+      # @api private
       def reload
         if @allow_reload
           begin
@@ -487,6 +523,11 @@ module Capybara
         self
       end
 
+      ##
+      #
+      # A human-readable representation of the element.
+      #
+      # @return [String]  A string representation
       def inspect
         %(#<Capybara::Node::Element tag="#{base.tag_name}" path="#{base.path}">)
       rescue NotSupportedByDriverError

data/lib/capybara/node/finders.rb

@@ -8,19 +8,14 @@ module Capybara
       # Find an {Capybara::Node::Element} based on the given arguments. +find+ will raise an error if the element
       # is not found.
       #
-      # @!macro waiting_behavior
-      #   If the driver is capable of executing JavaScript, this method 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, true, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
-      #
       #  page.find('#foo').find('.bar')
       #  page.find(:xpath, './/div[contains(., "bar")]')
       #  page.find('li', text: 'Quox').click_link('Delete')
       #
       # @param (see Capybara::Node::Finders#all)
       #
+      # @macro waiting_behavior
+      #
       # @!macro system_filters
       #   @option options [String, Regexp] text      Only find elements which contain this text or match this regexp
       #   @option options [String, Boolean] exact_text (Capybara.exact_text) When String the elements contained text must match exactly, when Boolean controls whether the :text option must match exactly

data/lib/capybara/node/simple.rb

@@ -102,6 +102,7 @@ module Capybara
       #
       def visible?(check_ancestors = true)
         return false if (tag_name == 'input') && (native[:type] == 'hidden')
+        return false if tag_name == 'template'
 
         if check_ancestors
           !find_xpath(VISIBILITY_XPATH)

data/lib/capybara/selector/definition/css.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 Capybara.add_selector(:css, locator_type: [String, Symbol], raw_locator: true) do
-  css { |css| css }
+  css do |css|
+    warn "DEPRECATED: Passing a symbol (#{css.inspect}) as the CSS locator is deprecated - please pass a string instead." if css.is_a? Symbol
+    css
+  end
 end

data/lib/capybara/selector/regexp_disassembler.rb

@@ -166,11 +166,11 @@ module Capybara
         end
 
         def min_repeat
-          @exp.quantifier&.min || 1
+          @exp.repetitions.begin
         end
 
         def max_repeat
-          @exp.quantifier&.max || 1
+          @exp.repetitions.end
         end
 
         def fixed_repeat?

data/lib/capybara/selenium/extensions/html5_drag.rb

@@ -22,6 +22,69 @@ class Capybara::Selenium::Node
       native.property('draggable')
     end
 
+    def html5_drop(*args)
+      if args[0].is_a? String
+        input = driver.evaluate_script ATTACH_FILE
+        input.set_file(args)
+        driver.execute_script DROP_FILE, self, input
+      else
+        items = args.each_with_object([]) do |arg, arr|
+          arg.each_with_object(arr) do |(type, data), arr_|
+            arr_ << { type: type, data: data }
+          end
+        end
+        driver.execute_script DROP_STRING, items, self
+      end
+    end
+
+    DROP_STRING = <<~JS
+      var strings = arguments[0],
+          el = arguments[1],
+          dt = new DataTransfer(),
+          opts = { cancelable: true, bubbles: true, dataTransfer: dt };
+      for (var i=0; i < strings.length; i++){
+        if (dt.items) {
+          dt.items.add(strings[i]['data'], strings[i]['type']);
+        } else {
+          dt.setData(strings[i]['type'], strings[i]['data']);
+        }
+      }
+      var dropEvent = new DragEvent('drop', opts);
+      el.dispatchEvent(dropEvent);
+    JS
+
+    DROP_FILE = <<~JS
+      var el = arguments[0],
+          input = arguments[1],
+          files = input.files,
+          dt = new DataTransfer(),
+          opts = { cancelable: true, bubbles: true, dataTransfer: dt };
+      input.parentElement.removeChild(input);
+      if (dt.items){
+        for (var i=0; i<files.length; i++){
+          dt.items.add(files[i]);
+        }
+      } else {
+        Object.defineProperty(dt, "files", {
+          value: files,
+          writable: false
+        });
+      }
+      var dropEvent = new DragEvent('drop', opts);
+      el.dispatchEvent(dropEvent);
+    JS
+
+    ATTACH_FILE = <<~JS
+      (function(){
+        var input = document.createElement('INPUT');
+        input.type = "file";
+        input.id = "_capybara_drop_file";
+        input.multiple = true;
+        document.body.appendChild(input);
+        return input;
+      })()
+    JS
+
     MOUSEDOWN_TRACKER = <<~JS
       document.addEventListener('mousedown', ev => {
         window.capybara_mousedown_prevented = ev.defaultPrevented;

data/lib/capybara/selenium/node.rb

@@ -137,6 +137,10 @@ class Capybara::Selenium::Node < Capybara::Driver::Node
     element.scroll_if_needed { browser_action.move_to(element.native).release.perform }
   end
 
+  def drop(*_)
+    raise NotImplementedError, 'Out of browser drop emulation is not implemented for the current browser'
+  end
+
   def tag_name
     @tag_name ||= native.tag_name.downcase
   end

data/lib/capybara/selenium/nodes/chrome_node.rb

@@ -34,6 +34,10 @@ class Capybara::Selenium::ChromeNode < Capybara::Selenium::Node
     html5_drag_to(element)
   end
 
+  def drop(*args)
+    html5_drop(*args)
+  end
+
   def click(*)
     super
   rescue ::Selenium::WebDriver::Error::WebDriverError => e

data/lib/capybara/selenium/nodes/firefox_node.rb

@@ -52,6 +52,10 @@ class Capybara::Selenium::FirefoxNode < Capybara::Selenium::Node
     html5_drag_to(element)
   end
 
+  def drop(*args)
+    html5_drop(*args)
+  end
+
   def hover
     return super unless browser_version >= 65.0
 
@@ -117,19 +121,6 @@ private
     driver.browser.capabilities[:browser_version].to_f
   end
 
-  DISABLED_BY_FIELDSET_XPATH = XPath.generate do |x|
-    x.parent(:fieldset)[
-      x.attr(:disabled)
-    ] + x.ancestor[
-      ~x.self(:legend) |
-      x.preceding_sibling(:legend)
-    ][
-      x.parent(:fieldset)[
-        x.attr(:disabled)
-      ]
-    ]
-  end.to_s.freeze
-
   class ModifierKeysStack
     def initialize
       @stack = []

data/lib/capybara/selenium/nodes/ie_node.rb

@@ -4,8 +4,19 @@ require 'capybara/selenium/extensions/html5_drag'
 
 class Capybara::Selenium::IENode < Capybara::Selenium::Node
   def disabled?
-    # TODO: Doesn't work for a bunch of cases - need to get IE running to see if it can be done like this
-    # driver.evaluate_script("arguments[0].msMatchesSelector(':disabled, select:disabled *')", self)
-    super
+    # super
+    # optimize to one script call
+    driver.evaluate_script <<~JS.delete("\n"), self
+      arguments[0].msMatchesSelector('
+        :disabled,
+        select:disabled *,
+        optgroup:disabled *,
+        fieldset[disabled],
+        fieldset[disabled] > *:not(legend),
+        fieldset[disabled] > *:not(legend) *,
+        fieldset[disabled] > legend:nth-of-type(n+2),
+        fieldset[disabled] > legend:nth-of-type(n+2) *
+      ')
+    JS
   end
 end

data/lib/capybara/selenium/nodes/safari_node.rb

@@ -91,19 +91,6 @@ private
     driver.browser.send(:bridge)
   end
 
-  DISABLED_BY_FIELDSET_XPATH = XPath.generate do |x|
-    x.parent(:fieldset)[
-      x.attr(:disabled)
-    ] + x.ancestor[
-      ~x.self(:legend) |
-      x.preceding_sibling(:legend)
-    ][
-      x.parent(:fieldset)[
-        x.attr(:disabled)
-      ]
-    ]
-  end.to_s.freeze
-
   def _send_keys(keys, actions = browser_action, down_keys = ModifierKeysStack.new)
     case keys
     when *MODIFIER_KEYS

data/lib/capybara/spec/public/test.js

@@ -18,7 +18,33 @@ $(function() {
   });
   $('#drop_html5, #drop_html5_scroll').on('drop', function(ev){
     ev.preventDefault();
-    $(this).html('HTML5 Dropped ' + ev.originalEvent.dataTransfer.getData("text"));
+    var oev = ev.originalEvent;
+    if (oev.dataTransfer.items) {
+      for (var i = 0; i < oev.dataTransfer.items.length; i++){
+        var item = oev.dataTransfer.items[i];
+        if (item.kind === 'file'){
+          var file = item.getAsFile();
+          $(this).append('HTML5 Dropped file: ' + file.name);
+        } else {
+          var _this = this;
+          var callback = (function(type){
+            return function(s){
+              $(_this).append('HTML5 Dropped string: ' + type + ' ' + s)
+            }
+          })(item.type);
+          item.getAsString(callback);
+        }
+      }
+    } else {
+      $(this).html('HTML5 Dropped ' + oev.dataTransfer.getData("text"));
+      for (var i = 0; i < oev.dataTransfer.files.length; i++) {
+        $(this).append('HTML5 Dropped file: ' + oev.dataTransfer.files[i].name);
+      }
+      for (var i = 0; i < oev.dataTransfer.types.length; i++) {
+        var type = oev.dataTransfer.types[i];
+        $(this).append('HTML5 Dropped string: ' + type + ' ' + oev.dataTransfer.getData(type));
+      }
+    }
   });
   $('#clickable').click(function(e) {
     var link = $(this);
@@ -180,7 +206,7 @@ $(function() {
     sessionStorage.setItem('session', 'session_value');
     localStorage.setItem('local', 'local value');
   });
-  $('#multiple-file').change(function(e){
-    $('body').append($('<p class="file_change"input_event_triggered">File input changed</p>'));
+  $('#multiple-file, #hidden_file').change(function(e){
+    $('body').append($('<p class="file_change">File input changed</p>'));
   })
 });

data/lib/capybara/spec/session/attach_file_spec.rb

@@ -180,6 +180,12 @@ Capybara::SpecHelper.spec '#attach_file' do
       @session.attach_file('hidden_file', with_os_path_separators(__FILE__), make_visible: true)
       expect(@session.evaluate_script('arguments[0].style.display', @session.find(:css, '#hidden_file', visible: :all))).to eq 'none'
     end
+
+    it 'should fire change' do
+      @session.visit('/with_js')
+      @session.attach_file('hidden_file', with_os_path_separators(__FILE__), make_visible: true)
+      expect(@session).to have_css('.file_change')
+    end
   end
 
   context 'with a block', requires: %i[js] do
@@ -198,11 +204,13 @@ Capybara::SpecHelper.spec '#attach_file' do
       @session.click_button('awesome')
       expect(extract_results(@session)['hidden_image']).to end_with(File.basename(__FILE__))
     end
-  end
 
-private
-
-  def with_os_path_separators(path)
-    Gem.win_platform? ? path.to_s.tr('/', '\\') : path.to_s
+    it 'should fire change' do
+      @session.visit('/with_js')
+      @session.attach_file(with_os_path_separators(__FILE__)) do
+        @session.find(:label, 'Label for hidden file input').click
+      end
+      expect(@session).to have_css('.file_change')
+    end
   end
 end

data/lib/capybara/spec/session/has_css_spec.rb

@@ -10,10 +10,11 @@ Capybara::SpecHelper.spec '#has_css?' do
     expect(@session).to have_css('p a#foo')
   end
 
-  it 'should take a symbol as the selector' do
+  it 'should warn when passed a symbol' do
     # This was never a specifically accepted format but it has worked for a
-    # lot of versions. Probably should keep it until at least 4.0
-    # TODO: consider not supporting symbol for the CSS selector.
+    # lot of versions.
+    # TODO: Remove in 4.0
+    expect_any_instance_of(Kernel).to receive(:warn) # rubocop:disable RSpec/AnyInstance
     expect(@session).to have_css(:p)
   end