capybara 3.13.2 → 3.40.0

data/lib/capybara/rspec/matchers/spatial_sugar.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Capybara
+  module RSpecMatchers
+    module SpatialSugar
+      def above(el)
+        options[:above] = el
+        self
+      end
+
+      def below(el)
+        options[:below] = el
+        self
+      end
+
+      def left_of(el)
+        options[:left_of] = el
+        self
+      end
+
+      def right_of(el)
+        options[:right_of] = el
+        self
+      end
+
+      def near(el)
+        options[:near] = el
+        self
+      end
+
+    private
+
+      def options
+        # (@args.last.is_a?(Hash) ? @args : @args.push({})).last
+        @kw_args
+      end
+    end
+  end
+end

data/lib/capybara/rspec/matchers.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'capybara/rspec/matchers/have_selector'
+require 'capybara/rspec/matchers/have_ancestor'
+require 'capybara/rspec/matchers/have_sibling'
 require 'capybara/rspec/matchers/match_selector'
 require 'capybara/rspec/matchers/have_current_path'
 require 'capybara/rspec/matchers/match_style'
@@ -10,153 +12,194 @@ require 'capybara/rspec/matchers/become_closed'
 
 module Capybara
   module RSpecMatchers
-    # RSpec matcher for whether the element(s) matching a given selector exist
-    # See {Capybara::Node::Matcher#assert_selector}
-    def have_selector(*args, &optional_filter_block)
-      Matchers::HaveSelector.new(*args, &optional_filter_block)
+    # RSpec matcher for whether the element(s) matching a given selector exist.
+    #
+    # @see Capybara::Node::Matchers#assert_selector
+    def have_selector(...)
+      Matchers::HaveSelector.new(...)
     end
 
-    # RSpec matcher for whether the element(s) matching a group of selectors exist
-    # See {Capybara::Node::Matcher#assert_all_of_selectors}
-    def have_all_of_selectors(*args, &optional_filter_block)
-      Matchers::HaveAllSelectors.new(*args, &optional_filter_block)
+    # RSpec matcher for whether the element(s) matching a group of selectors exist.
+    #
+    # @see Capybara::Node::Matchers#assert_all_of_selectors
+    def have_all_of_selectors(...)
+      Matchers::HaveAllSelectors.new(...)
     end
 
-    # RSpec matcher for whether no element(s) matching a group of selectors exist
-    # See {Capybara::Node::Matcher#assert_none_of_selectors}
-    def have_none_of_selectors(*args, &optional_filter_block)
-      Matchers::HaveNoSelectors.new(*args, &optional_filter_block)
+    # RSpec matcher for whether no element(s) matching a group of selectors exist.
+    #
+    # @see Capybara::Node::Matchers#assert_none_of_selectors
+    def have_none_of_selectors(...)
+      Matchers::HaveNoSelectors.new(...)
     end
 
-    # RSpec matcher for whether the element(s) matching any of a group of selectors exist
-    # See {Capybara::Node::Matcher#assert_any_of_selectors}
-    def have_any_of_selectors(*args, &optional_filter_block)
-      Matchers::HaveAnySelectors.new(*args, &optional_filter_block)
+    # RSpec matcher for whether the element(s) matching any of a group of selectors exist.
+    #
+    # @see Capybara::Node::Matchers#assert_any_of_selectors
+    def have_any_of_selectors(...)
+      Matchers::HaveAnySelectors.new(...)
     end
 
-    # RSpec matcher for whether the current element matches a given selector
-    # See {Capybara::Node::Matchers#assert_matches_selector}
-    def match_selector(*args, &optional_filter_block)
-      Matchers::MatchSelector.new(*args, &optional_filter_block)
+    # RSpec matcher for whether the current element matches a given selector.
+    #
+    # @see Capybara::Node::Matchers#assert_matches_selector
+    def match_selector(...)
+      Matchers::MatchSelector.new(...)
     end
 
     %i[css xpath].each do |selector|
       define_method "have_#{selector}" do |expr, **options, &optional_filter_block|
-        Matchers::HaveSelector.new(selector, expr, options, &optional_filter_block)
+        Matchers::HaveSelector.new(selector, expr, **options, &optional_filter_block)
       end
 
       define_method "match_#{selector}" do |expr, **options, &optional_filter_block|
-        Matchers::MatchSelector.new(selector, expr, options, &optional_filter_block)
+        Matchers::MatchSelector.new(selector, expr, **options, &optional_filter_block)
       end
     end
 
     # @!method have_xpath(xpath, **options, &optional_filter_block)
-    #   RSpec matcher for whether elements(s) matching a given xpath selector exist
-    #   See {Capybara::Node::Matchers#has_xpath?}
+    #   RSpec matcher for whether elements(s) matching a given xpath selector exist.
+    #
+    #   @see Capybara::Node::Matchers#has_xpath?
 
     # @!method have_css(css, **options, &optional_filter_block)
     #   RSpec matcher for whether elements(s) matching a given css selector exist
-    #   See {Capybara::Node::Matchers#has_css?}
+    #
+    #   @see Capybara::Node::Matchers#has_css?
 
     # @!method match_xpath(xpath, **options, &optional_filter_block)
-    #   RSpec matcher for whether the current element matches a given xpath selector
-    #   See {Capybara::Node::Matchers#matches_xpath?}
+    #   RSpec matcher for whether the current element matches a given xpath selector.
+    #
+    #   @see Capybara::Node::Matchers#matches_xpath?
 
     # @!method match_css(css, **options, &optional_filter_block)
-    #   RSpec matcher for whether the current element matches a given css selector
-    #   See {Capybara::Node::Matchers#matches_css?}
+    #   RSpec matcher for whether the current element matches a given css selector.
+    #
+    #   @see Capybara::Node::Matchers#matches_css?
 
-    %i[link button field select table].each do |selector|
+    %i[link button field select table element].each do |selector|
       define_method "have_#{selector}" do |locator = nil, **options, &optional_filter_block|
-        Matchers::HaveSelector.new(selector, locator, options, &optional_filter_block)
+        Matchers::HaveSelector.new(selector, locator, **options, &optional_filter_block)
       end
     end
 
+    # @!method have_element(locator = nil, **options, &optional_filter_block)
+    #   RSpec matcher for elements.
+    #
+    #   @see Capybara::Node::Matchers#has_element?
+
     # @!method have_link(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for links
-    #   See {Capybara::Node::Matchers#has_link?}
+    #   RSpec matcher for links.
+    #
+    #   @see Capybara::Node::Matchers#has_link?
 
     # @!method have_button(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for buttons
-    #   See {Capybara::Node::Matchers#has_button?}
+    #   RSpec matcher for buttons.
+    #
+    #   @see Capybara::Node::Matchers#has_button?
 
     # @!method have_field(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for links
-    #   See {Capybara::Node::Matchers#has_field?}
+    #   RSpec matcher for form fields.
+    #
+    #   @see Capybara::Node::Matchers#has_field?
 
     # @!method have_select(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for select elements
-    #   See {Capybara::Node::Matchers#has_select?}
+    #   RSpec matcher for select elements.
+    #
+    #   @see Capybara::Node::Matchers#has_select?
 
     # @!method have_table(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for table elements
-    #   See {Capybara::Node::Matchers#has_table?}
+    #   RSpec matcher for table elements.
+    #
+    #   @see Capybara::Node::Matchers#has_table?
 
     %i[checked unchecked].each do |state|
       define_method "have_#{state}_field" do |locator = nil, **options, &optional_filter_block|
-        Matchers::HaveSelector.new(:field, locator, options.merge(state => true), &optional_filter_block)
+        Matchers::HaveSelector.new(:field, locator, **options.merge(state => true), &optional_filter_block)
       end
     end
 
     # @!method have_checked_field(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for checked fields
-    #   See {Capybara::Node::Matchers#has_checked_field?}
+    #   RSpec matcher for checked fields.
+    #
+    #   @see Capybara::Node::Matchers#has_checked_field?
 
     # @!method have_unchecked_field(locator = nil, **options, &optional_filter_block)
-    #   RSpec matcher for unchecked fields
-    #   See {Capybara::Node::Matchers#has_unchecked_field?}
+    #   RSpec matcher for unchecked fields.
+    #
+    #   @see Capybara::Node::Matchers#has_unchecked_field?
 
-    # RSpec matcher for text content
-    # See {Capybara::SessionMatchers#assert_text}
-    def have_text(*args)
-      Matchers::HaveText.new(*args)
+    # RSpec matcher for text content.
+    #
+    # @see Capybara::Node::Matchers#assert_text
+    def have_text(text_or_type, *args, **options)
+      Matchers::HaveText.new(text_or_type, *args, **options)
     end
     alias_method :have_content, :have_text
 
     def have_title(title, **options)
-      Matchers::HaveTitle.new(title, options)
+      Matchers::HaveTitle.new(title, **options)
     end
 
-    # RSpec matcher for the current path
-    # See {Capybara::SessionMatchers#assert_current_path}
-    def have_current_path(path, **options)
-      Matchers::HaveCurrentPath.new(path, options)
+    # RSpec matcher for the current path.
+    #
+    # @see Capybara::SessionMatchers#assert_current_path
+    def have_current_path(path, **options, &optional_filter_block)
+      Matchers::HaveCurrentPath.new(path, **options, &optional_filter_block)
     end
 
-    # RSpec matcher for element style
-    # See {Capybara::Node::Matchers#matches_style?}
-    def match_style(styles, **options)
-      Matchers::MatchStyle.new(styles, options)
+    # RSpec matcher for element style.
+    #
+    # @see Capybara::Node::Matchers#matches_style?
+    def match_style(styles = nil, **options)
+      styles, options = options, {} if styles.nil?
+      Matchers::MatchStyle.new(styles, **options)
     end
 
     ##
     # @deprecated
     #
-    def have_style(styles, **options)
-      warn 'DEPRECATED: have_style is deprecated, please use match_style'
+    def have_style(styles = nil, **options)
+      Capybara::Helpers.warn "DEPRECATED: have_style is deprecated, please use match_style : #{Capybara::Helpers.filter_backtrace(caller)}"
       match_style(styles, **options)
     end
 
     %w[selector css xpath text title current_path link button
-       field checked_field unchecked_field select table].each do |matcher_type|
-      define_method "have_no_#{matcher_type}" do |*args, &optional_filter_block|
-        Matchers::NegatedMatcher.new(send("have_#{matcher_type}", *args, &optional_filter_block))
+       field checked_field unchecked_field select table
+       sibling ancestor element].each do |matcher_type|
+      define_method "have_no_#{matcher_type}" do |*args, **kw_args, &optional_filter_block|
+        Matchers::NegatedMatcher.new(send("have_#{matcher_type}", *args, **kw_args, &optional_filter_block))
       end
     end
     alias_method :have_no_content, :have_no_text
 
     %w[selector css xpath].each do |matcher_type|
-      define_method "not_match_#{matcher_type}" do |*args, &optional_filter_block|
-        Matchers::NegatedMatcher.new(send("match_#{matcher_type}", *args, &optional_filter_block))
+      define_method "not_match_#{matcher_type}" do |*args, **kw_args, &optional_filter_block|
+        Matchers::NegatedMatcher.new(send("match_#{matcher_type}", *args, **kw_args, &optional_filter_block))
       end
     end
 
+    # RSpec matcher for whether sibling element(s) matching a given selector exist.
+    #
+    # @see Capybara::Node::Matchers#assert_sibling
+    def have_sibling(...)
+      Matchers::HaveSibling.new(...)
+    end
+
+    # RSpec matcher for whether ancestor element(s) matching a given selector exist.
+    #
+    # @see Capybara::Node::Matchers#assert_ancestor
+    def have_ancestor(...)
+      Matchers::HaveAncestor.new(...)
+    end
+
     ##
     # Wait for window to become closed.
+    #
     # @example
     #   expect(window).to become_closed(wait: 0.8)
-    # @param options [Hash] optional param
-    # @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum wait time
+    #
+    # @option options [Numeric] :wait   Maximum wait time. Defaults to {Capybara.configure default_max_wait_time}
     def become_closed(**options)
       Matchers::BecomeClosed.new(options)
     end

data/lib/capybara/rspec.rb

@@ -9,6 +9,8 @@ require 'capybara/rspec/matcher_proxies'
 RSpec.configure do |config|
   config.include Capybara::DSL, type: :feature
   config.include Capybara::RSpecMatchers, type: :feature
+  config.include Capybara::DSL, type: :system
+  config.include Capybara::RSpecMatchers, type: :system
   config.include Capybara::RSpecMatchers, type: :view
 
   # The before and after blocks must run instantaneously, because Capybara

data/lib/capybara/selector/builders/css_builder.rb

@@ -17,11 +17,7 @@ module Capybara
           conditions = if name == :class
             class_conditions(value)
           elsif value.is_a? Regexp
-            Selector::RegexpDisassembler.new(value).alternated_substrings.map do |strs|
-              strs.map do |str|
-                "[#{name}*='#{str}'#{' i' if value.casefold?}]"
-              end.join
-            end
+            regexp_conditions(name, value)
           else
             [attribute_conditions(name => value)]
           end
@@ -36,6 +32,14 @@ module Capybara
 
     private
 
+      def regexp_conditions(name, value)
+        Selector::RegexpDisassembler.new(value).alternated_substrings.map do |strs|
+          strs.map do |str|
+            "[#{name}*='#{str}'#{' i' if value.casefold?}]"
+          end.join
+        end
+      end
+
       def attribute_conditions(attributes)
         attributes.map do |attribute, value|
           case value
@@ -70,9 +74,9 @@ module Capybara
             end.join
           end
         else
-          cls = Array(classes).group_by { |cl| cl.start_with?('!') && !cl.start_with?('!!!') }
+          cls = Array(classes).reject { |c| c.is_a? Regexp }.group_by { |cl| cl.match?(/^!(?!!!)/) }
           [(cls[false].to_a.map { |cl| ".#{Capybara::Selector::CSS.escape(cl.sub(/^!!/, ''))}" } +
-          cls[true].to_a.map { |cl| ":not(.#{Capybara::Selector::CSS.escape(cl.slice(1..-1))})" }).join]
+          cls[true].to_a.map { |cl| ":not(.#{Capybara::Selector::CSS.escape(cl.slice(1..))})" }).join]
         end
       end
     end

data/lib/capybara/selector/builders/xpath_builder.rb

@@ -15,6 +15,8 @@ module Capybara
       def add_attribute_conditions(**conditions)
         @expression = conditions.inject(expression) do |xp, (name, value)|
           conditions = name == :class ? class_conditions(value) : attribute_conditions(name => value)
+          return xp if conditions.nil?
+
           if xp.is_a? XPath::Expression
             xp[conditions]
           else
@@ -47,9 +49,9 @@ module Capybara
         when XPath::Expression, Regexp
           attribute_conditions(class: classes)
         else
-          Array(classes).map do |klass|
-            if klass.start_with?('!') && !klass.start_with?('!!!')
-              !XPath.attr(:class).contains_word(klass.slice(1..-1))
+          Array(classes).reject { |c| c.is_a? Regexp }.map do |klass|
+            if klass.match?(/^!(?!!!)/)
+              !XPath.attr(:class).contains_word(klass.slice(1..))
             else
               XPath.attr(:class).contains_word(klass.sub(/^!!/, ''))
             end

data/lib/capybara/selector/css.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
+require 'capybara/selector/selector'
+
 module Capybara
   class Selector
     class CSS
       def self.escape(str)
         value = str.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.slice!(0...1) if value.match?(/^[-_]/)
+        out << (value[0].match?(NMSTART) ? value.slice!(0...1) : escape_char(value.slice!(0...1)))
         out << value.gsub(/[^a-zA-Z0-9_-]/) { |char| escape_char char }
         out
       end
 
       def self.escape_char(char)
-        char =~ %r{[ -/:-~]} ? "\\#{char}" : format('\\%06x', char.ord)
+        char.match?(%r{[ -/:-~]}) ? "\\#{char}" : format('\\%06<hex>x', hex: char.ord)
       end
 
       def self.split(css)
@@ -21,11 +23,11 @@ module Capybara
       end
 
       S = '\u{80}-\u{D7FF}\u{E000}-\u{FFFD}\u{10000}-\u{10FFFF}'
-      H = /[0-9a-fA-F]/.freeze
-      UNICODE  = /\\#{H}{1,6}[ \t\r\n\f]?/.freeze
-      NONASCII = /[#{S}]/.freeze
-      ESCAPE   = /#{UNICODE}|\\[ -~#{S}]/.freeze
-      NMSTART = /[_a-zA-Z]|#{NONASCII}|#{ESCAPE}/.freeze
+      H = /[0-9a-fA-F]/
+      UNICODE  = /\\#{H}{1,6}[ \t\r\n\f]?/
+      NONASCII = /[#{S}]/
+      ESCAPE   = /#{UNICODE}|\\[ -~#{S}]/
+      NMSTART = /[_a-zA-Z]|#{NONASCII}|#{ESCAPE}/
 
       class Splitter
         def split(css)
@@ -41,7 +43,7 @@ module Capybara
               when '"', "'"
                 selector << parse_string(char, str)
               when '\\'
-                selector << char + str.getc
+                selector << (char + str.getc)
               when ','
                 selectors << selector.strip
                 selector.clear

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

@@ -0,0 +1,68 @@
+# 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)
+    aria_btn_xpath = XPath.descendant[XPath.attr(:role).equals('button')]
+    image_btn_xpath = XPath.descendant(:input)[XPath.attr(:type) == 'image']
+
+    unless locator.nil?
+      locator = locator.to_s
+      locator_matchers = combine_locators(locator, config: self)
+      btn_matchers = locator_matchers |
+                     XPath.string.n.is(locator) |
+                     XPath.descendant(:img)[XPath.attr(:alt).is(locator)]
+
+      label_contains_xpath = locate_label(locator).descendant[labellable_elements]
+      input_btn_xpath = input_btn_xpath[locator_matchers]
+      btn_xpath = btn_xpath[btn_matchers]
+      aria_btn_xpath = aria_btn_xpath[btn_matchers]
+
+      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
+
+    btn_xpaths = [input_btn_xpath, btn_xpath, image_btn_xpath, label_contains_xpath].compact
+    btn_xpaths << aria_btn_xpath if enable_aria_role
+
+    %i[value title type].inject(btn_xpaths.inject(&:union)) do |memo, ef|
+      memo.where(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)] }
+
+  node_filter(:name) { |node, value| !value.is_a?(Regexp) || value.match?(node[:name]) }
+  expression_filter(:name) do |xpath, val|
+    builder(xpath).add_attribute_conditions(name: val)
+  end
+
+  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
+
+  def combine_locators(locator, config:)
+    [
+      XPath.attr(:id).equals(locator),
+      XPath.attr(:name).equals(locator),
+      XPath.attr(:value).is(locator),
+      XPath.attr(:title).is(locator),
+      (XPath.attr(:id) == XPath.anywhere(:label)[XPath.string.n.is(locator)].attr(:for)),
+      (XPath.attr(:'aria-label').is(locator) if config.enable_aria_label),
+      (XPath.attr(config.test_id) == locator if config.test_id)
+    ].compact.inject(&:|)
+  end
+
+  def labellable_elements
+    (XPath.self(:input) & XPath.attr(:type).one_of('submit', 'reset', 'image', 'button')) | XPath.self(:button)
+  end
+end

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

@@ -0,0 +1,26 @@
+# 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(%i[option with]) do |node, value|
+    val = node.value
+    (value.is_a?(Regexp) ? value.match?(val) : val == value.to_s).tap do |res|
+      add_error("Expected value to be #{value.inspect} but it was #{val.inspect}") unless res
+    end
+  end
+
+  describe_node_filters do |option: nil, with: nil, **|
+    desc = +''
+    desc << " with value #{option.inspect}" if option
+    desc << " with value #{with.inspect}" if with
+    desc
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+Capybara.add_selector(:css, locator_type: [String, Symbol], raw_locator: true) do
+  css do |css|
+    if css.is_a? Symbol
+      Capybara::Helpers.warn "DEPRECATED: Passing a symbol (#{css.inspect}) as the CSS locator is deprecated - please pass a string instead : #{Capybara::Helpers.filter_backtrace(caller)}"
+    end
+    css
+  end
+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.where(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,28 @@
+# 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|
+    boolean_values = [true, false]
+    booleans, values = options.partition { |_k, v| boolean_values.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