capybara 3.1.1 → 3.2.0

data/lib/capybara/selector/css.rb

@@ -5,7 +5,7 @@ module Capybara
     class CSS
       def self.escape(str)
         value = str.dup
-        out = "".dup
+        out = +""
         out << value.slice!(0...1) if value =~ /^[-_]/
         out << (value[0] =~ NMSTART ? value.slice!(0...1) : escape_char(value.slice!(0...1)))
         out << value.gsub(/[^a-zA-Z0-9_-]/) { |c| escape_char c }
@@ -16,7 +16,7 @@ module Capybara
         c =~ %r{[ -/:-~]} ? "\\#{c}" : format("\\%06x", c.ord)
       end
 
-      S = '\u{80}-\u{D7FF}\u{E000}-\u{FFFD}\u{10000}-\u{10FFFF}'.freeze
+      S = '\u{80}-\u{D7FF}\u{E000}-\u{FFFD}\u{10000}-\u{10FFFF}'
       H = /[0-9a-fA-F]/
       UNICODE  = /\\#{H}{1,6}[ \t\r\n\f]?/
       NONASCII = /[#{S}]/

data/lib/capybara/selector/filter_set.rb

@@ -5,17 +5,20 @@ require 'capybara/selector/filter'
 module Capybara
   class Selector
     class FilterSet
-      attr_reader :descriptions
+      attr_reader :descriptions, :node_filters, :expression_filters
 
       def initialize(name, &block)
         @name = name
         @descriptions = []
+        @expression_filters = {}
+        @node_filters = {}
         instance_eval(&block)
       end
 
-      def filter(name, *types_and_options, &block)
+      def node_filter(name, *types_and_options, &block)
         add_filter(name, Filters::NodeFilter, *types_and_options, &block)
       end
+      alias_method :filter, :node_filter
 
       def expression_filter(name, *types_and_options, &block)
         add_filter(name, Filters::ExpressionFilter, *types_and_options, &block)
@@ -27,21 +30,7 @@ module Capybara
 
       def description(**options)
         opts = options_with_defaults(options)
-        @descriptions.map do |desc|
-          desc.call(opts).to_s
-        end.join
-      end
-
-      def filters
-        @filters ||= {}
-      end
-
-      def node_filters
-        filters.reject { |_n, f| f.nil? || f.is_a?(Filters::ExpressionFilter) }.freeze
-      end
-
-      def expression_filters
-        filters.select { |_n, f| f.nil? || f.is_a?(Filters::ExpressionFilter) }.freeze
+        @descriptions.map { |desc| desc.call(opts).to_s }.join
       end
 
       class << self
@@ -62,15 +51,22 @@ module Capybara
 
       def options_with_defaults(options)
         options = options.dup
-        filters.each do |name, filter|
-          options[name] = filter.default if filter.default? && !options.key?(name)
+        [expression_filters, node_filters].each do |filters|
+          filters.select { |_n, f| f.default? }.each do |name, filter|
+            options[name] = filter.default unless options.key?(name)
+          end
         end
         options
       end
 
-      def add_filter(name, filter_class, *types, **options, &block)
+      def add_filter(name, filter_class, *types, matcher: nil, **options, &block)
         types.each { |k| options[k] = true }
-        filters[name] = filter_class.new(name, block, options)
+        raise "ArgumentError", ":default option is not supported for filters with a :matcher option" if matcher && options[:default]
+        if filter_class <= Filters::ExpressionFilter
+          @expression_filters[name] = filter_class.new(name, matcher, block, options)
+        else
+          @node_filters[name] = filter_class.new(name, matcher, block, options)
+        end
       end
     end
   end

data/lib/capybara/selector/filters/base.rb

@@ -4,8 +4,9 @@ module Capybara
   class Selector
     module Filters
       class Base
-        def initialize(name, block, **options)
+        def initialize(name, matcher, block, **options)
           @name = name
+          @matcher = matcher
           @block = block
           @options = options
           @options[:valid_values] = [true, false] if options[:boolean]
@@ -23,8 +24,30 @@ module Capybara
           @options.key?(:skip_if) && value == @options[:skip_if]
         end
 
+        def matcher?
+          !@matcher.nil?
+        end
+
+        def handles_option?(option_name)
+          if matcher?
+            option_name =~ @matcher
+          else
+            @name == option_name
+          end
+        end
+
       private
 
+        def apply(subject, name, value, skip_value)
+          return skip_value if skip?(value)
+          raise ArgumentError, "Invalid value #{value.inspect} passed to #{self.class.name.split('::').last} #{name}#{" : #{@name}" if @name.is_a?(Regexp)}" unless valid_value?(value)
+          if @block.arity == 2
+            @block.call(subject, value)
+          else
+            @block.call(subject, name, value)
+          end
+        end
+
         def valid_value?(value)
           !@options.key?(:valid_values) || Array(@options[:valid_values]).include?(value)
         end

data/lib/capybara/selector/filters/expression_filter.rb

@@ -6,17 +6,15 @@ module Capybara
   class Selector
     module Filters
       class ExpressionFilter < Base
-        def apply_filter(expr, value)
-          return expr if skip?(value)
-          raise "ArgumentError", "Invalid value #{value.inspect} passed to expression filter #{@name}" unless valid_value?(value)
-          @block.call(expr, value)
+        def apply_filter(expr, name, value)
+          apply(expr, name, value, expr)
         end
       end
 
       class IdentityExpressionFilter < ExpressionFilter
         def initialize; end
         def default?; false; end
-        def apply_filter(expr, _value); expr; end
+        def apply_filter(expr, _name, _value); expr; end
       end
     end
   end

data/lib/capybara/selector/filters/node_filter.rb

@@ -6,10 +6,10 @@ module Capybara
   class Selector
     module Filters
       class NodeFilter < Base
-        def matches?(node, value)
-          return true if skip?(value)
-          raise ArgumentError, "Invalid value #{value.inspect} passed to filter #{@name}" unless valid_value?(value)
-          @block.call(node, value)
+        def matches?(node, name, value)
+          apply(node, name, value, true)
+        rescue Capybara::ElementNotFound
+          false
         end
       end
     end

data/lib/capybara/selector/selector.rb

@@ -1,27 +1,165 @@
 # frozen_string_literal: true
 
+# rubocop:disable Style/AsciiComments
+
 require 'capybara/selector/filter_set'
 require 'capybara/selector/css'
-require 'xpath'
-
-# Patch XPath to allow a nil condition in where
-module XPath
-  class Renderer
-    undef :where if method_defined?(:where)
-    def where(on, condition)
-      condition = condition.to_s
-      if !condition.empty?
-        "#{on}[#{condition}]"
-      else
-        on.to_s
-      end
-    end
-  end
-end
 
 module Capybara
+  #
+  # ## Built-in Selectors
+  #
+  #   * **:xpath** - Select elements by XPath expression
+  #     * Locator: An XPath expression
+  #
+  #   * **:css** - Select elements by CSS selector
+  #     * Locator: A CSS selector
+  #
+  #   * **:id** - Select element by id
+  #     * Locator: The id of the element to match
+  #
+  #   * **:field** - Select field elements (input [not of type submit, image, or hidden], textarea, select)
+  #     * Locator: Matches against the id, name, or placeholder
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :name (String) — Matches the name attribute
+  #       * :placeholder (String) — Matches the placeholder attribute
+  #       * :type (String) — Matches the type attribute of the field or element type for 'textarea' and 'select'
+  #       * :readonly (Boolean)
+  #       * :with (String) — Matches the current value of the field
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #       * :checked (Boolean) — Match checked fields?
+  #       * :unchecked (Boolean) — Match unchecked fields?
+  #       * :disabled (Boolean) — Match disabled field?
+  #       * :multiple (Boolean) — Match fields that accept multiple values
+  #
+  #   * **:fieldset** - Select fieldset elements
+  #     * Locator: Matches id or contents of wrapped legend
+  #     * Filters:
+  #       * :id (String) — Matches id attribute
+  #       * :legend (String) — Matches contents of wrapped legend
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #
+  #   * **:link** - Find links ( <a> elements with an href attribute )
+  #     * Locator: Matches the id or title attributes, or the string content of the link, or the alt attribute of a contained img element
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :title (String) — Matches the title attribute
+  #       * :alt (String) — Matches the alt attribute of a contained img element
+  #       * :class (String) — Matches the class(es) provided
+  #       * :href (String, Regexp, nil) — Matches the normalized href of the link, if nil will find <a> elements with no href attribute
+  #
+  #   * **:button** - Find buttons ( input [of type submit, reset, image, button] or button elements )
+  #     * Locator: Matches the id, value, or title attributes, string content of a button, or the alt attribute of an image type button or of a descendant image of a button
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :title (String) — Matches the title attribute
+  #       * :class (String) — Matches the class(es) provided
+  #       * :value (String) — Matches the value of an input button
+  #       * :type
+  #
+  #   * **:link_or_button** - Find links or buttons
+  #     * Locator: See :link and :button selectors
+  #
+  #   * **:fillable_field** - Find text fillable fields ( textarea, input [not of type submit, image, radio, checkbox, hidden, file] )
+  #     * Locator: Matches against the id, name, or placeholder
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :name (String) — Matches the name attribute
+  #       * :placeholder (String) — Matches the placeholder attribute
+  #       * :with (String) — Matches the current value of the field
+  #       * :type (String) — Matches the type attribute of the field or element type for 'textarea'
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #       * :disabled (Boolean) — Match disabled field?
+  #       * :multiple (Boolean) — Match fields that accept multiple values
+  #
+  #   * **:radio_button** - Find radio buttons
+  #     * Locator: Match id, name, or associated label text
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :name (String) — Matches the name attribute
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #       * :checked (Boolean) — Match checked fields?
+  #       * :unchecked (Boolean) — Match unchecked fields?
+  #       * :disabled (Boolean) — Match disabled field?
+  #       * :option (String) — Match the value
+  #
+  #   * **:checkbox** - Find checkboxes
+  #     * Locator: Match id, name, or associated label text
+  #     * Filters:
+  #       * *:id (String) — Matches the id attribute
+  #       * *:name (String) — Matches the name attribute
+  #       * *:class (String, Array<String>) — Matches the class(es) provided
+  #       * *:checked (Boolean) — Match checked fields?
+  #       * *:unchecked (Boolean) — Match unchecked fields?
+  #       * *:disabled (Boolean) — Match disabled field?
+  #       * *:option (String) — Match the value
+  #
+  #   * **:select** - Find select elements
+  #     * Locator: Match id, name, placeholder, or associated label text
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :name (String) — Matches the name attribute
+  #       * :placeholder (String) — Matches the placeholder attribute
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #       * :disabled (Boolean) — Match disabled field?
+  #       * :multiple (Boolean) — Match fields that accept multiple values
+  #       * :options (Array<String>) — Exact match options
+  #       * :with_options (Array<String>) — Partial match options
+  #       * :selected (String, Array<String>) — Match the selection(s)
+  #       * :with_selected (String, Array<String>) — Partial match the selection(s)
+  #
+  #   * **:option** - Find option elements
+  #     * Locator: Match text of option
+  #     * Filters:
+  #       * :disabled (Boolean) — Match disabled option
+  #       * :selected (Boolean) — Match selected option
+  #
+  #   * **:datalist_input**
+  #     * Locator:
+  #     * Filters:
+  #       * :disabled
+  #       * :name
+  #       * :placeholder
+  #
+  #   * **:datalist_option**
+  #     * Locator:
+  #
+  #   * **:file_field** - Find file input elements
+  #     * Locator: Match id, name, or associated label text
+  #     * Filters:
+  #       * :id (String) — Matches the id attribute
+  #       * :name (String) — Matches the name attribute
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #       * :disabled (Boolean) — Match disabled field?
+  #       * :multiple (Boolean) — Match field that accepts multiple values
+  #
+  #   * **:label** - Find label elements
+  #     * Locator: Match id or text contents
+  #     * Filters:
+  #       * :for (Element, String) — The element or id of the element associated with the label
+  #
+  #   * **:table** - Find table elements
+  #     * Locator: id or caption text of table
+  #     * Filters:
+  #       * :id (String) — Match id attribute of table
+  #       * :caption (String) — Match text of associated caption
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #
+  #   * **:frame** - Find frame/iframe elements
+  #     * Locator: Match id or name
+  #     * Filters:
+  #       * :id (String) — Match id attribute
+  #       * :name (String) — Match name attribute
+  #       * :class (String, Array<String>) — Matches the class(es) provided
+  #
+  #   * **:element**
+  #     * Locator: Type of element ('div', 'a', etc) - if not specified defaults to '*'
+  #     * Filters: Matches on any element attribute
+  #
   class Selector
     attr_reader :name, :format
+    extend Forwardable
 
     class << self
       def all
@@ -56,7 +194,8 @@ module Capybara
     end
 
     def custom_filters
-      @filter_set.filters
+      warn "Deprecated: Selector#custom_filters is not valid when same named expression and node filter exist - don't use"
+      node_filters.merge(expression_filters).freeze
     end
 
     def node_filters
@@ -81,10 +220,10 @@ module Capybara
     # @overload xpath()
     # @return [#call]                             The block that will be called to generate the XPath expression
     #
-    def xpath(*expression_filters, &block)
+    def xpath(*allowed_filters, &block)
       if block
         @format, @expression = :xpath, block
-        expression_filters.flatten.each { |ef| custom_filters[ef] = Filters::IdentityExpressionFilter.new }
+        allowed_filters.flatten.each { |ef| expression_filters[ef] = Filters::IdentityExpressionFilter.new }
       end
       format == :xpath ? @expression : nil
     end
@@ -103,10 +242,10 @@ module Capybara
     # @overload css()
     # @return [#call]                             The block that will be called to generate the CSS selector
     #
-    def css(*expression_filters, &block)
+    def css(*allowed_filters, &block)
       if block
         @format, @expression = :css, block
-        expression_filters.flatten.each { |ef| custom_filters[ef] = nil }
+        allowed_filters.flatten.each { |ef| expression_filters[ef] = nil }
       end
       format == :css ? @expression : nil
     end
@@ -143,12 +282,10 @@ module Capybara
     #
     # Description of the selector
     #
-    # @param [Hash] options            The options of the query used to generate the description
-    # @return [String]                 Description of the selector when used with the options passed
-    #
-    def description(**options)
-      @filter_set.description(options)
-    end
+    # @!method description(options)
+    #   @param [Hash] options            The options of the query used to generate the description
+    #   @return [String]                 Description of the selector when used with the options passed
+    def_delegator :@filter_set, :description
 
     def call(locator, **options)
       if format
@@ -168,41 +305,58 @@ module Capybara
     # @return [Boolean]           Whether or not to use this selector
     #
     def match?(locator)
-      @match and @match.call(locator)
+      @match&.call(locator)
     end
 
     ##
     #
-    # Define a non-expression filter for use with this selector
+    # Define a node filter for use with this selector
     #
-    # @overload filter(name, *types, options={}, &block)
-    #   @param [Symbol] name            The filter name
+    # @!method node_filter(name, *types, options={}, &block)
+    #   @param [Symbol, Regexp] name            The filter name
     #   @param [Array<Symbol>] types    The types of the filter - currently valid types are [:boolean]
     #   @param [Hash] options ({})      Options of the filter
     #   @option options [Array<>] :valid_values Valid values for this filter
     #   @option options :default        The default value of the filter (if any)
     #   @option options :skip_if        Value of the filter that will cause it to be skipped
+    #   @option options [Regexp] :matcher (nil) A Regexp used to check whether a specific option is handled by this filter.  If not provided the filter will be used for options matching the filter name.
     #
-    def filter(name, *types_and_options, &block)
-      add_filter(name, Filters::NodeFilter, *types_and_options, &block)
-    end
+    # If a Symbol is passed for the name the block should accept | node, option_value |, while if a Regexp
+    # is passed for the name the block should accept | node, option_name, option_value |. In either case
+    # the block should return `true` if the node passes the filer or `false` if it doesn't
 
-    def expression_filter(name, *types_and_options, &block)
-      add_filter(name, Filters::ExpressionFilter, *types_and_options, &block)
-    end
+    # @!method filter
+    #   See {Selector#node_filter}
+
+    ##
+    #
+    # Define an expression filter for use with this selector
+    #
+    # @!method expression_filter(name, *types, options={}, &block)
+    #   @param [Symbol, Regexp] name            The filter name
+    #   @param [Regexp] matcher (nil)   A Regexp used to check whether a specific option is handled by this filter
+    #   @param [Array<Symbol>] types    The types of the filter - currently valid types are [:boolean]
+    #   @param [Hash] options ({})      Options of the filter
+    #   @option options [Array<>] :valid_values Valid values for this filter
+    #   @option options :default        The default value of the filter (if any)
+    #   @option options :skip_if        Value of the filter that will cause it to be skipped
+    #   @option options [Regexp] :matcher (nil) A Regexp used to check whether a specific option is handled by this filter.  If not provided the filter will be used for options matching the filter name.
+    #
+    # If a Symbol is passed for the name the block should accept | current_expression, option_value |, while if a Regexp
+    # is passed for the name the block should accept | current_expression, option_name, option_value |. In either case
+    # the block should return the modified expression
+
+    def_delegators :@filter_set, :node_filter, :expression_filter, :filter
 
     def filter_set(name, filters_to_use = nil)
       f_set = FilterSet.all[name]
-      f_set.filters.each do |n, filter|
-        custom_filters[n] = filter if filters_to_use.nil? || filters_to_use.include?(n)
-      end
-
+      filter_selector = filters_to_use.nil? ? ->(*) { true } : ->(n, _) { filters_to_use.include? n }
+      @filter_set.expression_filters.merge!(f_set.expression_filters.select(&filter_selector))
+      @filter_set.node_filters.merge!(f_set.node_filters.select(&filter_selector))
       f_set.descriptions.each { |desc| @filter_set.describe(&desc) }
     end
 
-    def describe(&block)
-      @filter_set.describe(&block)
-    end
+    def_delegator :@filter_set, :describe
 
     ##
     #
@@ -218,40 +372,36 @@ module Capybara
     end
 
     def default_visibility(fallback = Capybara.ignore_hidden_elements)
-      if @default_visibility.nil?
-        fallback
-      else
-        @default_visibility
-      end
+      return @default_visibility unless @default_visibility.nil?
+      fallback
     end
 
   private
 
-    def add_filter(name, filter_class, *types, **options, &block)
-      types.each { |k| options[k] = true }
-      custom_filters[name] = filter_class.new(name, block, options)
-    end
-
     def locate_field(xpath, locator, enable_aria_label: false, **_options)
+      return xpath if locator.nil?
       locate_xpath = xpath # Need to save original xpath for the label wrap
-      if locator
-        locator = locator.to_s
-        attr_matchers = [XPath.attr(:id) == locator,
-                         XPath.attr(:name) == locator,
-                         XPath.attr(:placeholder) == locator,
-                         XPath.attr(:id) == XPath.anywhere(:label)[XPath.string.n.is(locator)].attr(:for)].reduce(:|)
-        attr_matchers |= XPath.attr(:'aria-label').is(locator) if enable_aria_label
-
-        locate_xpath = locate_xpath[attr_matchers]
-        locate_xpath = locate_xpath.union(XPath.descendant(:label)[XPath.string.n.is(locator)].descendant(xpath))
-      end
-
-      # locate_xpath = [:name, :placeholder].inject(locate_xpath) { |memo, ef| memo[find_by_attr(ef, options[ef])] }
-      locate_xpath
+      locator = locator.to_s
+      attr_matchers = [XPath.attr(:id) == locator,
+                       XPath.attr(:name) == locator,
+                       XPath.attr(:placeholder) == locator,
+                       XPath.attr(:id) == XPath.anywhere(:label)[XPath.string.n.is(locator)].attr(:for)].reduce(:|)
+      attr_matchers |= XPath.attr(:'aria-label').is(locator) if enable_aria_label
+
+      locate_xpath = locate_xpath[attr_matchers]
+      locate_xpath + XPath.descendant(:label)[XPath.string.n.is(locator)].descendant(xpath)
     end
 
     def describe_all_expression_filters(**opts)
-      expression_filters.keys.map { |ef| " with #{ef} #{opts[ef]}" if opts.key?(ef) }.join
+      expression_filters.map do |ef_name, ef|
+        if ef.matcher?
+          opts.keys.map do |k|
+            " with #{ef_name}[#{k} => #{opts[k]}]" if ef.handles_option?(k) && !::Capybara::Queries::SelectorQuery::VALID_KEYS.include?(k)
+          end.join
+        elsif opts.key?(ef_name)
+          " with #{ef_name} #{opts[ef_name]}"
+        end
+      end.join
     end
 
     def find_by_attr(attribute, value)
@@ -268,3 +418,5 @@ module Capybara
     end
   end
 end
+
+# rubocop:enable Style/AsciiComments