class Capybara::Selector
All Selectors below support the listed selector specific filters in addition to the following system-wide filters
* :id (String, Regexp, XPath::Expression) - Matches the id attribute * :class (String, Array<String | Regexp>, Regexp, XPath::Expression) - Matches the class(es) provided * :style (String, Regexp, Hash<String, String>) - Match on elements style * :above (Element) - Match elements above the passed element on the page * :below (Element) - Match elements below the passed element on the page * :left_of (Element) - Match elements left of the passed element on the page * :right_of (Element) - Match elements right of the passed element on the page * :near (Element) - Match elements near (within 50px) the passed element on the page * :focused (Boolean) - Match elements with focus (requires driver support)
### 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: (String, Regexp, XPath::Expression) 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, {Capybara.configure
test_id
} attribute, name, placeholder, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :placeholder (String, Regexp) - Matches the placeholder attribute * :type (String) - Matches the type attribute of the field or element type for 'textarea' and 'select' * :readonly (Boolean) - Match on the element being readonly * :with (String, Regexp) - Matches the current value of the field * :checked (Boolean) - Match checked fields? * :unchecked (Boolean) - Match unchecked fields? * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :multiple (Boolean) - Match fields that accept multiple values * :valid (Boolean) - Match fields that are valid/invalid according to HTML5 form validation * :validation_message (String, Regexp) - Matches the elements current validationMessage
-
-
:fieldset - Select fieldset elements
-
Locator: Matches id, {Capybara.configure
test_id
}, or contents of wrapped legend -
Filters:
* :legend (String) - Matches contents of wrapped legend * :disabled (Boolean) - Match disabled fieldset?
-
-
:link - Find links (‘<a>` elements with an href attribute)
-
Locator: Matches the id, {Capybara.configure
test_id
}, or title attributes, or the string content of the link, or the alt attribute of a contained img element. By default this selector requires a link to have an href attribute. -
Filters:
* :title (String) - Matches the title attribute * :alt (String) - Matches the alt attribute of a contained img element * :href (String, Regexp, nil, false) - Matches the normalized href of the link, if nil will find `<a>` elements with no href attribute, if false ignores href presence
-
-
:button - Find buttons ( input [of type submit, reset, image, button] or button elements )
-
Locator: Matches the id, {Capybara.configure
test_id
} attribute, name, 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:
* :name (String, Regexp) - Matches the name attribute * :title (String) - Matches the title attribute * :value (String) - Matches the value of an input button * :type (String) - Matches the type attribute * :disabled (Boolean, :all) - Match disabled buttons (Default: false)
-
-
:link_or_button - Find links or buttons
-
Locator: See :link and :button selectors
-
Filters:
* :disabled (Boolean, :all) - Match disabled buttons? (Default: false)
-
-
:fillable_field - Find text fillable fields ( textarea, input [not of type submit, image, radio, checkbox, hidden, file] )
-
Locator: Matches against the id, {Capybara.configure
test_id
} attribute, name, placeholder, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :placeholder (String, Regexp) - Matches the placeholder attribute * :with (String, Regexp) - Matches the current value of the field * :type (String) - Matches the type attribute of the field or element type for 'textarea' * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :multiple (Boolean) - Match fields that accept multiple values * :valid (Boolean) - Match fields that are valid/invalid according to HTML5 form validation * :validation_message (String, Regexp) - Matches the elements current validationMessage
-
-
:radio_button - Find radio buttons
-
Locator: Match id, {Capybara.configure
test_id
} attribute, name, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :checked (Boolean) - Match checked fields? * :unchecked (Boolean) - Match unchecked fields? * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :option (String, Regexp) - Match the current value * :with - Alias of :option
-
-
:checkbox - Find checkboxes
-
Locator: Match id, {Capybara.configure
test_id
} attribute, name, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :checked (Boolean) - Match checked fields? * :unchecked (Boolean) - Match unchecked fields? * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :with (String, Regexp) - Match the current value * :option - Alias of :with
-
-
:select - Find select elements
-
Locator: Match id, {Capybara.configure
test_id
} attribute, name, placeholder, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :placeholder (String, Placeholder) - Matches the placeholder attribute * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :multiple (Boolean) - Match fields that accept multiple values * :options (Array<String>) - Exact match options * :enabled_options (Array<String>) - Exact match enabled options * :disabled_options (Array<String>) - Exact match disabled 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 - Find input field with datalist completion
-
Locator: Matches against the id, {Capybara.configure
test_id
} attribute, name, placeholder, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :placeholder (String, Regexp) - Matches the placeholder attribute * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :options (Array<String>) - Exact match options * :with_options (Array<String>) - Partial match options
-
-
:datalist_option - Find datalist option
-
Locator: Match text or value of option
-
Filters:
* :disabled (Boolean) - Match disabled option
-
-
:file_field - Find file input elements
-
Locator: Match id, {Capybara.configure
test_id
} attribute, name, or associated label text -
Filters:
* :name (String, Regexp) - Matches the name attribute * :disabled (Boolean, :all) - Match disabled field? (Default: false) * :multiple (Boolean) - Match field that accepts multiple values
-
-
:label - Find label elements
-
Locator: Match id, {Capybara.configure
test_id
}, or text contents -
Filters:
* :for (Element, String, Regexp) - The element or id of the element associated with the label
-
-
:table - Find table elements
-
Locator: id, {Capybara.configure
test_id
}, or caption text of table -
Filters:
* :caption (String) - Match text of associated caption * :with_rows (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered * :rows (Array<Array<String>>) - Match all `<td>`s - visibility of `<td>` elements is not considered * :with_cols (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered * :cols (Array<Array<String>>) - Match all `<td>`s - visibility of `<td>` elements is not considered
-
-
:table_row - Find table row
-
Locator: Array<String>, Hash<String, String> table row ‘<td>` contents - visibility of `<td>` elements is not considered
-
-
:frame - Find frame/iframe elements
-
Locator: Match id, {Capybara.configure
test_id
} attribute, or name -
Filters:
* :name (String) - Match name attribute
-
-
:element
-
Locator: Type of element (‘div’, ‘a’, etc) - if not specified defaults to ‘*’
-
Filters:
* :\<any> (String, Regexp) - Match on any specified element attribute
-
Attributes
Public Class Methods
Source
# File lib/capybara/selector/selector.rb, line 10 def [](name) all.fetch(name.to_sym) { |sel_type| raise ArgumentError, "Unknown selector type (:#{sel_type})" } end
Source
# File lib/capybara/selector/selector.rb, line 14 def add(name, **options, &block) all[name.to_sym] = Definition.new(name.to_sym, **options, &block) end
Source
# File lib/capybara/selector/selector.rb, line 6 def all @definitions ||= {} # rubocop:disable Naming/MemoizedInstanceVariableName end
Source
# File lib/capybara/selector/selector.rb, line 26 def for(locator) all.values.find { |sel| sel.match?(locator) } end
Source
# File lib/capybara/selector/selector.rb, line 33 def initialize(definition, config:, format:) definition = self.class[definition] unless definition.is_a? Definition super(definition) @definition = definition @config = config @format = format @errors = [] end
Source
# File lib/capybara/selector/selector.rb, line 22 def remove(name) all.delete(name.to_sym) end
Source
# File lib/capybara/selector/selector.rb, line 18 def update(name, &block) self[name].instance_eval(&block) end
Public Instance Methods
Source
# File lib/capybara/selector/selector.rb, line 77 def add_error(error_msg) errors << error_msg end
Source
# File lib/capybara/selector/selector.rb, line 95 def builder(expr = nil) case format when :css Capybara::Selector::CSSBuilder when :xpath Capybara::Selector::XPathBuilder else raise NotImplementedError, "No builder exists for selector of type #{default_format}" end.new(expr) end
@api private
Source
# File lib/capybara/selector/selector.rb, line 59 def call(locator, **options) if format raise ArgumentError, "Selector #{@name} does not support #{format}" unless expressions.key?(format) instance_exec(locator, **options, &expressions[format]) else warn 'Selector has no format' end ensure unless locator_valid?(locator) Capybara::Helpers.warn( "Locator #{locator.class}:#{locator.inspect} for selector #{name.inspect} must #{locator_description}. " \ 'This will raise an error in a future version of Capybara. ' \ "Called from: #{Capybara::Helpers.filter_backtrace(caller)}" ) end end
Source
# File lib/capybara/selector/selector.rb, line 47 def enable_aria_label @config[:enable_aria_label] end
Source
# File lib/capybara/selector/selector.rb, line 51 def enable_aria_role @config[:enable_aria_role] end
Source
# File lib/capybara/selector/selector.rb, line 81 def expression_for(name, locator, config: @config, format: current_format, **options) Selector.new(name, config: config, format: format).call(locator, **options) end
Source
# File lib/capybara/selector/selector.rb, line 42 def format @format || @definition.default_format end
Source
# File lib/capybara/selector/selector.rb, line 55 def test_id @config[:test_id] end
Source
# File lib/capybara/selector/selector.rb, line 86 def with_filter_errors(errors) old_errors = @errors @errors = errors yield ensure @errors = old_errors end
@api private
Private Instance Methods
Source
# File lib/capybara/selector/selector.rb, line 146 def find_by_attr(attribute, value) finder_name = "find_by_#{attribute}_attr" if respond_to?(finder_name, true) send(finder_name, value) else value ? XPath.attr(attribute) == value : nil end end
Source
# File lib/capybara/selector/selector.rb, line 155 def find_by_class_attr(classes) Array(classes).map { |klass| XPath.attr(:class).contains_word(klass) }.reduce(:&) end
Source
# File lib/capybara/selector/selector.rb, line 126 def locate_field(xpath, locator, **_options) return xpath if locator.nil? locate_xpath = xpath # Need to save original xpath for the label wrap 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 attr_matchers |= XPath.attr(test_id) == locator if test_id locate_xpath = locate_xpath[attr_matchers] locate_xpath + locate_label(locator).descendant(xpath) end
Source
# File lib/capybara/selector/selector.rb, line 142 def locate_label(locator) XPath.descendant(:label)[XPath.string.n.is(locator)] end
Source
# File lib/capybara/selector/selector.rb, line 108 def locator_description locator_types.group_by { |lt| lt.is_a? Symbol }.map do |symbol, types_or_methods| if symbol "respond to #{types_or_methods.join(' or ')}" else "be an instance of #{types_or_methods.join(' or ')}" end end.join(' or ') end
Source
# File lib/capybara/selector/selector.rb, line 118 def locator_valid?(locator) return true unless locator && locator_types locator_types&.any? do |type_or_method| type_or_method.is_a?(Symbol) ? locator.respond_to?(type_or_method) : type_or_method === locator # rubocop:disable Style/CaseEquality end end