capybara 3.8.1 → 3.33.0

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:table, locator_type: [String, Symbol]) do
+  xpath do |locator, caption: nil, **|
+    xpath = XPath.descendant(:table)
+    unless locator.nil?
+      locator_matchers = (XPath.attr(:id) == locator.to_s) | XPath.descendant(:caption).is(locator.to_s)
+      locator_matchers |= XPath.attr(test_id) == locator if test_id
+      xpath = xpath[locator_matchers]
+    end
+    xpath = xpath[XPath.descendant(:caption) == caption] if caption
+    xpath
+  end
+
+  expression_filter(:with_cols, valid_values: [Array]) do |xpath, cols|
+    col_conditions = cols.map do |col|
+      if col.is_a? Hash
+        col.reduce(nil) do |xp, (header, cell_str)|
+          header = XPath.descendant(:th)[XPath.string.n.is(header)]
+          td = XPath.descendant(:tr)[header].descendant(:td)
+          cell_condition = XPath.string.n.is(cell_str)
+          if xp
+            prev_cell = XPath.ancestor(:table)[1].join(xp)
+            cell_condition &= (prev_cell & prev_col_position?(prev_cell))
+          end
+          td[cell_condition]
+        end
+      else
+        cells_xp = col.reduce(nil) do |prev_cell, cell_str|
+          cell_condition = XPath.string.n.is(cell_str)
+
+          if prev_cell
+            prev_cell = XPath.ancestor(:tr)[1].preceding_sibling(:tr).join(prev_cell)
+            cell_condition &= (prev_cell & prev_col_position?(prev_cell))
+          end
+
+          XPath.descendant(:td)[cell_condition]
+        end
+        XPath.descendant(:tr).join(cells_xp)
+      end
+    end.reduce(:&)
+    xpath[col_conditions]
+  end
+
+  expression_filter(:cols, valid_values: [Array]) do |xpath, cols|
+    raise ArgumentError, ':cols must be an Array of Arrays' unless cols.all?(Array)
+
+    rows = cols.transpose
+    col_conditions = rows.map { |row| match_row(row, match_size: true) }.reduce(:&)
+    xpath[match_row_count(rows.size)][col_conditions]
+  end
+
+  expression_filter(:with_rows, valid_values: [Array]) do |xpath, rows|
+    rows_conditions = rows.map { |row| match_row(row) }.reduce(:&)
+    xpath[rows_conditions]
+  end
+
+  expression_filter(:rows, valid_values: [Array]) do |xpath, rows|
+    rows_conditions = rows.map { |row| match_row(row, match_size: true) }.reduce(:&)
+    xpath[match_row_count(rows.size)][rows_conditions]
+  end
+
+  describe_expression_filters do |caption: nil, **|
+    " with caption \"#{caption}\"" if caption
+  end
+
+  def prev_col_position?(cell)
+    XPath.position.equals(cell_position(cell))
+  end
+
+  def cell_position(cell)
+    cell.preceding_sibling(:td).count.plus(1)
+  end
+
+  def match_row(row, match_size: false)
+    xp = XPath.descendant(:tr)[
+      if row.is_a? Hash
+        row_match_cells_to_headers(row)
+      else
+        XPath.descendant(:td)[row_match_ordered_cells(row)]
+      end
+    ]
+    xp = xp[XPath.descendant(:td).count.equals(row.size)] if match_size
+    xp
+  end
+
+  def match_row_count(size)
+    XPath.descendant(:tbody).descendant(:tr).count.equals(size) |
+      (XPath.descendant(:tr).count.equals(size) & ~XPath.descendant(:tbody))
+  end
+
+  def row_match_cells_to_headers(row)
+    row.map do |header, cell|
+      header_xp = XPath.ancestor(:table)[1].descendant(:tr)[1].descendant(:th)[XPath.string.n.is(header)]
+      XPath.descendant(:td)[
+        XPath.string.n.is(cell) & XPath.position.equals(header_xp.preceding_sibling.count.plus(1))
+      ]
+    end.reduce(:&)
+  end
+
+  def row_match_ordered_cells(row)
+    row_conditions = row.map do |cell|
+      XPath.self(:td)[XPath.string.n.is(cell)]
+    end
+    row_conditions.reverse.reduce do |cond, cell|
+      cell[XPath.following_sibling[cond]]
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:table_row, locator_type: [Array, Hash]) do
+  xpath do |locator|
+    xpath = XPath.descendant(:tr)
+    if locator.is_a? Hash
+      locator.reduce(xpath) do |xp, (header, cell)|
+        header_xp = XPath.ancestor(:table)[1].descendant(:tr)[1].descendant(:th)[XPath.string.n.is(header)]
+        cell_xp = XPath.descendant(:td)[
+          XPath.string.n.is(cell) & XPath.position.equals(header_xp.preceding_sibling.count.plus(1))
+        ]
+        xp[cell_xp]
+      end
+    else
+      initial_td = XPath.descendant(:td)[XPath.string.n.is(locator.shift)]
+      tds = locator.reverse.map { |cell| XPath.following_sibling(:td)[XPath.string.n.is(cell)] }
+                   .reduce { |xp, cell| xp[cell] }
+      xpath[initial_td[tds]]
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:xpath, locator_type: [:to_xpath, String], raw_locator: true) do
+  xpath { |xpath| xpath }
+end

data/lib/capybara/selector/definition.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'capybara/selector/filter_set'
+require 'capybara/selector/css'
+require 'capybara/selector/regexp_disassembler'
+require 'capybara/selector/builders/xpath_builder'
+require 'capybara/selector/builders/css_builder'
+
+module Capybara
+  class Selector
+    class Definition
+      attr_reader :name, :expressions
+
+      extend Forwardable
+
+      def initialize(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block)
+        @name = name
+        @filter_set = Capybara::Selector::FilterSet.add(name) {}
+        @match = nil
+        @label = nil
+        @failure_message = nil
+        @expressions = {}
+        @expression_filters = {}
+        @locator_filter = nil
+        @default_visibility = nil
+        @locator_type = locator_type
+        @raw_locator = raw_locator
+        @supports_exact = supports_exact
+        instance_eval(&block)
+      end
+
+      def custom_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
+        @filter_set.node_filters
+      end
+
+      def expression_filters
+        @filter_set.expression_filters
+      end
+
+      ##
+      #
+      # Define a selector by an xpath expression
+      #
+      # @overload xpath(*expression_filters, &block)
+      #   @param [Array<Symbol>] expression_filters ([])  Names of filters that are implemented via this expression, if not specified the names of any keyword parameters in the block will be used
+      #   @yield [locator, options]                       The block to use to generate the XPath expression
+      #   @yieldparam [String] locator                    The locator string passed to the query
+      #   @yieldparam [Hash] options                      The options hash passed to the query
+      #   @yieldreturn [#to_xpath, #to_s]                 An object that can produce an xpath expression
+      #
+      # @overload xpath()
+      # @return [#call]                             The block that will be called to generate the XPath expression
+      #
+      def xpath(*allowed_filters, &block)
+        expression(:xpath, allowed_filters, &block)
+      end
+
+      ##
+      #
+      # Define a selector by a CSS selector
+      #
+      # @overload css(*expression_filters, &block)
+      #   @param [Array<Symbol>] expression_filters ([])  Names of filters that can be implemented via this CSS selector
+      #   @yield [locator, options]                   The block to use to generate the CSS selector
+      #   @yieldparam [String] locator               The locator string passed to the query
+      #   @yieldparam [Hash] options                 The options hash passed to the query
+      #   @yieldreturn [#to_s]                        An object that can produce a CSS selector
+      #
+      # @overload css()
+      # @return [#call]                             The block that will be called to generate the CSS selector
+      #
+      def css(*allowed_filters, &block)
+        expression(:css, allowed_filters, &block)
+      end
+
+      ##
+      #
+      # Automatic selector detection
+      #
+      # @yield [locator]                   This block takes the passed in locator string and returns whether or not it matches the selector
+      # @yieldparam [String], locator      The locator string used to determin if it matches the selector
+      # @yieldreturn [Boolean]             Whether this selector matches the locator string
+      # @return [#call]                    The block that will be used to detect selector match
+      #
+      def match(&block)
+        @match = block if block
+        @match
+      end
+
+      ##
+      #
+      # Set/get a descriptive label for the selector
+      #
+      # @overload label(label)
+      #   @param [String] label            A descriptive label for this selector - used in error messages
+      # @overload label()
+      # @return [String]                 The currently set label
+      #
+      def label(label = nil)
+        @label = label if label
+        @label
+      end
+
+      ##
+      #
+      # Description of the selector
+      #
+      # @!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
+
+      ##
+      #
+      #  Should this selector be used for the passed in locator
+      #
+      #  This is used by the automatic selector selection mechanism when no selector type is passed to a selector query
+      #
+      # @param [String] locator     The locator passed to the query
+      # @return [Boolean]           Whether or not to use this selector
+      #
+      def match?(locator)
+        @match&.call(locator)
+      end
+
+      ##
+      #
+      # Define a node filter for use with this selector
+      #
+      # @!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.
+      #
+      # 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
+
+      ##
+      #
+      # Define an expression filter for use with this selector
+      #
+      # @!method expression_filter(name, *types, matcher: nil, **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 locator_filter(*types, **options, &block)
+        types.each { |type| options[type] = true }
+        @locator_filter = Capybara::Selector::Filters::LocatorFilter.new(block, **options) if block
+        @locator_filter
+      end
+
+      def filter_set(name, filters_to_use = nil)
+        @filter_set.import(name, filters_to_use)
+      end
+
+      def_delegator :@filter_set, :describe
+
+      def describe_expression_filters(&block)
+        if block_given?
+          describe(:expression_filters, &block)
+        else
+          describe(:expression_filters) do |**options|
+            describe_all_expression_filters(**options)
+          end
+        end
+      end
+
+      def describe_all_expression_filters(**opts)
+        expression_filters.map do |ef_name, ef|
+          if ef.matcher?
+            handled_custom_options(ef, opts).map { |option, value| " with #{ef_name}[#{option} => #{value}]" }.join
+          elsif opts.key?(ef_name)
+            " with #{ef_name} #{opts[ef_name]}"
+          end
+        end.join
+      end
+
+      def describe_node_filters(&block)
+        describe(:node_filters, &block)
+      end
+
+      ##
+      #
+      # Set the default visibility mode that shouble be used if no visibile option is passed when using the selector.
+      # If not specified will default to the behavior indicated by Capybara.ignore_hidden_elements
+      #
+      # @param [Symbol] default_visibility  Only find elements with the specified visibility:
+      #                                              * :all - finds visible and invisible elements.
+      #                                              * :hidden - only finds invisible elements.
+      #                                              * :visible - only finds visible elements.
+      def visible(default_visibility = nil, &block)
+        @default_visibility = block || default_visibility
+      end
+
+      def default_visibility(fallback = Capybara.ignore_hidden_elements, options = {})
+        vis = if @default_visibility&.respond_to?(:call)
+          @default_visibility.call(options)
+        else
+          @default_visibility
+        end
+        vis.nil? ? fallback : vis
+      end
+
+      # @api private
+      def raw_locator?
+        !!@raw_locator
+      end
+
+      # @api private
+      def supports_exact?
+        @supports_exact
+      end
+
+      def default_format
+        return nil if @expressions.keys.empty?
+
+        if @expressions.size == 1
+          @expressions.keys.first
+        else
+          :xpath
+        end
+      end
+
+      # @api private
+      def locator_types
+        return nil unless @locator_type
+
+        Array(@locator_type)
+      end
+
+    private
+
+      def handled_custom_options(filter, options)
+        options.select do |option, _|
+          filter.handles_option?(option) && !::Capybara::Queries::SelectorQuery::VALID_KEYS.include?(option)
+        end
+      end
+
+      def parameter_names(block)
+        block.parameters.select { |(type, _name)| %i[key keyreq].include? type }.map { |(_type, name)| name }
+      end
+
+      def expression(type, allowed_filters, &block)
+        if block
+          @expressions[type] = block
+          allowed_filters = parameter_names(block) if allowed_filters.empty?
+          allowed_filters.flatten.each do |ef|
+            expression_filters[ef] = Capybara::Selector::Filters::IdentityExpressionFilter.new(ef)
+          end
+        end
+        @expressions[type]
+      end
+    end
+  end
+end

data/lib/capybara/selector/filter.rb

@@ -2,3 +2,4 @@
 
 require 'capybara/selector/filters/node_filter'
 require 'capybara/selector/filters/expression_filter'
+require 'capybara/selector/filters/locator_filter'

data/lib/capybara/selector/filter_set.rb

@@ -15,13 +15,15 @@ module Capybara
         instance_eval(&block)
       end
 
-      def node_filter(name, *types_and_options, &block)
-        add_filter(name, Filters::NodeFilter, *types_and_options, &block)
+      def node_filter(names, *types, **options, &block)
+        Array(names).each do |name|
+          add_filter(name, Filters::NodeFilter, *types, **options, &block)
+        end
       end
       alias_method :filter, :node_filter
 
-      def expression_filter(name, *types_and_options, &block)
-        add_filter(name, Filters::ExpressionFilter, *types_and_options, &block)
+      def expression_filter(name, *types, **options, &block)
+        add_filter(name, Filters::ExpressionFilter, *types, **options, &block)
       end
 
       def describe(what = nil, &block)
@@ -40,9 +42,9 @@ module Capybara
       def description(node_filters: true, expression_filters: true, **options)
         opts = options_with_defaults(options)
         description = +''
-        description += undeclared_descriptions.map { |desc| desc.call(opts).to_s }.join
-        description += expression_filter_descriptions.map { |desc| desc.call(opts).to_s }.join if expression_filters
-        description += node_filter_descriptions.map { |desc| desc.call(opts).to_s }.join if node_filters
+        description << undeclared_descriptions.map { |desc| desc.call(**opts).to_s }.join
+        description << expression_filter_descriptions.map { |desc| desc.call(**opts).to_s }.join if expression_filters
+        description << node_filter_descriptions.map { |desc| desc.call(**opts).to_s }.join if node_filters
         description
       end
 
@@ -52,15 +54,16 @@ module Capybara
       end
 
       def import(name, filters = nil)
-        f_set = self.class.all[name]
         filter_selector = filters.nil? ? ->(*) { true } : ->(filter_name, _) { filters.include? filter_name }
 
-        expression_filters.merge!(f_set.expression_filters.select(&filter_selector))
-        node_filters.merge!(f_set.node_filters.select(&filter_selector))
-
-        f_set.undeclared_descriptions.each { |desc| describe(&desc) }
-        f_set.expression_filter_descriptions.each { |desc| describe(:expression_filters, &desc) }
-        f_set.node_filter_descriptions.each { |desc| describe(:node_filters, &desc) }
+        self.class[name].tap do |f_set|
+          expression_filters.merge!(f_set.expression_filters.select(&filter_selector))
+          node_filters.merge!(f_set.node_filters.select(&filter_selector))
+          f_set.undeclared_descriptions.each { |desc| describe(&desc) }
+          f_set.expression_filter_descriptions.each { |desc| describe(:expression_filters, &desc) }
+          f_set.node_filter_descriptions.each { |desc| describe(:node_filters, &desc) }
+        end
+        self
       end
 
       class << self
@@ -68,6 +71,10 @@ module Capybara
           @filter_sets ||= {} # rubocop:disable Naming/MemoizedInstanceVariableName
         end
 
+        def [](name)
+          all.fetch(name.to_sym) { |set_name| raise ArgumentError, "Unknown filter set (:#{set_name})" }
+        end
+
         def add(name, &block)
           all[name.to_sym] = FilterSet.new(name.to_sym, &block)
         end
@@ -105,12 +112,12 @@ module Capybara
 
       def add_filter(name, filter_class, *types, matcher: nil, **options, &block)
         types.each { |type| options[type] = true }
-        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)
+        if matcher && options[:default]
+          raise 'ArgumentError', ':default option is not supported for filters with a :matcher option'
         end
+
+        filter = filter_class.new(name, matcher, block, **options)
+        (filter_class <= Filters::ExpressionFilter ? @expression_filters : @node_filters)[name] = filter
       end
     end
   end

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

@@ -24,13 +24,21 @@ module Capybara
           @options.key?(:skip_if) && value == @options[:skip_if]
         end
 
+        def format
+          @options[:format]
+        end
+
         def matcher?
           !@matcher.nil?
         end
 
+        def boolean?
+          !!@options[:boolean]
+        end
+
         def handles_option?(option_name)
           if matcher?
-            option_name =~ @matcher
+            @matcher.match? option_name
           else
             @name == option_name
           end
@@ -38,18 +46,29 @@ module Capybara
 
       private
 
-        def apply(subject, name, value, skip_value)
+        def apply(subject, name, value, skip_value, ctx)
           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)
+
+          unless valid_value?(value)
+            raise ArgumentError,
+                  "Invalid value #{value.inspect} passed to #{self.class.name.split('::').last} #{name}" \
+                  "#{" : #{name}" if @name.is_a?(Regexp)}"
+          end
+
           if @block.arity == 2
-            @block.call(subject, value)
+            filter_context(ctx).instance_exec(subject, value, &@block)
           else
-            @block.call(subject, name, value)
+            filter_context(ctx).instance_exec(subject, name, value, &@block)
           end
         end
 
+        def filter_context(context)
+          context || @block.binding.receiver
+        end
+
         def valid_value?(value)
           return true unless @options.key?(:valid_values)
+
           Array(@options[:valid_values]).any? { |valid| valid === value } # rubocop:disable Style/CaseEquality
         end
       end

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

@@ -6,8 +6,8 @@ module Capybara
   class Selector
     module Filters
       class ExpressionFilter < Base
-        def apply_filter(expr, name, value)
-          apply(expr, name, value, expr)
+        def apply_filter(expr, name, value, selector)
+          apply(expr, name, value, expr, selector)
         end
       end
 
@@ -15,7 +15,7 @@ module Capybara
         def initialize(name); super(name, nil, nil); end
         def default?; false; end
         def matcher?; false; end
-        def apply_filter(expr, _name, _value); expr; end
+        def apply_filter(expr, _name, _value, _ctx); expr; end
       end
     end
   end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'capybara/selector/filters/base'
+
+module Capybara
+  class Selector
+    module Filters
+      class LocatorFilter < NodeFilter
+        def initialize(block, **options)
+          super(nil, nil, block, **options)
+        end
+
+        def matches?(node, value, context = nil, exact:)
+          apply(node, value, true, context, exact: exact, format: context&.default_format)
+        rescue Capybara::ElementNotFound
+          false
+        end
+
+      private
+
+        def apply(subject, value, skip_value, ctx, **options)
+          return skip_value if skip?(value)
+
+          filter_context(ctx).instance_exec(subject, value, **options, &@block)
+        end
+      end
+    end
+  end
+end

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

@@ -6,8 +6,22 @@ module Capybara
   class Selector
     module Filters
       class NodeFilter < Base
-        def matches?(node, name, value)
-          apply(node, name, value, true)
+        def initialize(name, matcher, block, **options)
+          super
+          @block = if boolean?
+            proc do |node, value|
+              error_cnt = errors.size
+              block.call(node, value).tap do |res|
+                add_error("Expected #{name} #{value} but it wasn't") if !res && error_cnt == errors.size
+              end
+            end
+          else
+            block
+          end
+        end
+
+        def matches?(node, name, value, context = nil)
+          apply(node, name, value, true, context)
         rescue Capybara::ElementNotFound
           false
         end