capybara 3.18.0 → 3.19.0

data/lib/capybara/selector/css.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'capybara/selector/selector'
+
 module Capybara
   class Selector
     class CSS

data/lib/capybara/selector/definition.rb

@@ -0,0 +1,276 @@
+# 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_keys(ef, opts.keys).map { |key| " with #{ef_name}[#{key} => #{opts[key]}]" }.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_keys(filter, keys)
+        keys.select do |key|
+          filter.handles_option?(key) && !::Capybara::Queries::SelectorQuery::VALID_KEYS.include?(key)
+        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/definition/button.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:button, locator_type: [String, Symbol]) do
+  xpath(:value, :title, :type, :name) do |locator, **options|
+    input_btn_xpath = XPath.descendant(:input)[XPath.attr(:type).one_of('submit', 'reset', 'image', 'button')]
+    btn_xpath = XPath.descendant(:button)
+    image_btn_xpath = XPath.descendant(:input)[XPath.attr(:type) == 'image']
+
+    unless locator.nil?
+      locator = locator.to_s
+      locator_matchers = XPath.attr(:id).equals(locator) |
+                         XPath.attr(:name).equals(locator) |
+                         XPath.attr(:value).is(locator) |
+                         XPath.attr(:title).is(locator)
+      locator_matchers |= XPath.attr(:'aria-label').is(locator) if enable_aria_label
+      locator_matchers |= XPath.attr(test_id) == locator if test_id
+
+      input_btn_xpath = input_btn_xpath[locator_matchers]
+
+      btn_xpath = btn_xpath[locator_matchers |
+                            XPath.string.n.is(locator) |
+                            XPath.descendant(:img)[XPath.attr(:alt).is(locator)]]
+
+      alt_matches = XPath.attr(:alt).is(locator)
+      alt_matches |= XPath.attr(:'aria-label').is(locator) if enable_aria_label
+      image_btn_xpath = image_btn_xpath[alt_matches]
+    end
+
+    %i[value title type name].inject(input_btn_xpath.union(btn_xpath).union(image_btn_xpath)) do |memo, ef|
+      memo[find_by_attr(ef, options[ef])]
+    end
+  end
+
+  node_filter(:disabled, :boolean, default: false, skip_if: :all) { |node, value| !(value ^ node.disabled?) }
+  expression_filter(:disabled) { |xpath, val| val ? xpath : xpath[~XPath.attr(:disabled)] }
+
+  describe_expression_filters do |disabled: nil, **options|
+    desc = +''
+    desc << ' that is not disabled' if disabled == false
+    desc << describe_all_expression_filters(options)
+  end
+
+  describe_node_filters do |disabled: nil, **|
+    ' that is disabled' if disabled == true
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:checkbox, locator_type: [String, Symbol]) do
+  xpath do |locator, allow_self: nil, **options|
+    xpath = XPath.axis(allow_self ? :"descendant-or-self" : :descendant, :input)[
+      XPath.attr(:type) == 'checkbox'
+    ]
+    locate_field(xpath, locator, options)
+  end
+
+  filter_set(:_field, %i[checked unchecked disabled name])
+
+  node_filter(:option) do |node, value|
+    val = node.value
+    (val == value.to_s).tap do |res|
+      add_error("Expected option value to be #{value.inspect} but it was #{val.inspect}") unless res
+    end
+  end
+
+  describe_node_filters do |option: nil, **|
+    " with value #{option.inspect}" if option
+  end
+end

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

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:datalist_input, locator_type: [String, Symbol]) do
+  label 'input box with datalist completion'
+
+  xpath do |locator, **options|
+    xpath = XPath.descendant(:input)[XPath.attr(:list)]
+    locate_field(xpath, locator, options)
+  end
+
+  filter_set(:_field, %i[disabled name placeholder])
+
+  node_filter(:options) do |node, options|
+    actual = node.find("//datalist[@id=#{node[:list]}]", visible: :all).all(:datalist_option, wait: false).map(&:value)
+    (options.sort == actual.sort).tap do |res|
+      add_error("Expected #{options.inspect} options found #{actual.inspect}") unless res
+    end
+  end
+
+  expression_filter(:with_options) do |expr, options|
+    options.inject(expr) do |xpath, option|
+      xpath[XPath.attr(:list) == XPath.anywhere(:datalist)[expression_for(:datalist_option, option)].attr(:id)]
+    end
+  end
+
+  describe_expression_filters do |with_options: nil, **|
+    desc = +''
+    desc << " with at least options #{with_options.inspect}" if with_options
+    desc
+  end
+
+  describe_node_filters do |options: nil, **|
+    " with options #{options.inspect}" if options
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:datalist_option, locator_type: [String, Symbol]) do
+  label 'datalist option'
+  visible(:all)
+
+  xpath do |locator|
+    xpath = XPath.descendant(:option)
+    xpath = xpath[XPath.string.n.is(locator.to_s) | (XPath.attr(:value) == locator.to_s)] unless locator.nil?
+    xpath
+  end
+
+  node_filter(:disabled, :boolean) { |node, value| !(value ^ node.disabled?) }
+  expression_filter(:disabled) { |xpath, val| val ? xpath : xpath[~XPath.attr(:disabled)] }
+
+  describe_expression_filters do |disabled: nil, **options|
+    desc = +''
+    desc << ' that is not disabled' if disabled == false
+    desc << describe_all_expression_filters(options)
+  end
+
+  describe_node_filters do |**options|
+    ' that is disabled' if options[:disabled]
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:element, locator_type: [String, Symbol]) do
+  xpath do |locator, **|
+    XPath.descendant.where(locator ? XPath.local_name == locator.to_s : nil)
+  end
+
+  expression_filter(:attributes, matcher: /.+/) do |xpath, name, val|
+    builder(xpath).add_attribute_conditions(name => val)
+  end
+
+  node_filter(:attributes, matcher: /.+/) do |node, name, val|
+    next true unless val.is_a?(Regexp)
+
+    (val.match? node[name]).tap do |res|
+      add_error("Expected #{name} to match #{val.inspect} but it was #{node[name]}") unless res
+    end
+  end
+
+  describe_expression_filters do |**options|
+    booleans, values = options.partition { |_k, v| [true, false].include? v }.map(&:to_h)
+    desc = describe_all_expression_filters(values)
+    desc + booleans.map do |k, v|
+      v ? " with #{k} attribute" : "without #{k} attribute"
+    end.join
+  end
+end