Class: Capybara::Selector

Inherits:

SimpleDelegator

Object
SimpleDelegator
Capybara::Selector

show all

Defined in:: lib/capybara/selector.rb,
lib/capybara/selector/css.rb,
lib/capybara/selector/selector.rb,
lib/capybara/selector/definition.rb,
lib/capybara/selector/filter_set.rb,
lib/capybara/selector/filters/base.rb,
lib/capybara/selector/filters/node_filter.rb,
lib/capybara/selector/regexp_disassembler.rb,
lib/capybara/selector/builders/css_builder.rb,
lib/capybara/selector/builders/xpath_builder.rb,
lib/capybara/selector/filters/locator_filter.rb,
lib/capybara/selector/filters/expression_filter.rb

Overview

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, Regexp, XPath::Expression) - Matches the class(es) provided
:style (String, Regexp, Hash) - Match on elements style

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, test_id attribute, name, or placeholder
- Filters:
  - :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) - 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
:fieldset - Select fieldset elements
- Locator: Matches id, 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, 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, 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) - 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, test_id attribute, name, or placeholder
- Filters:
  - :name (String) - Matches the name attribute
  - :placeholder (String) - 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
:radio_button - Find radio buttons
- Locator: Match id, test_id attribute, name, or associated label text
- Filters:
  - :name (String) - 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, test_id attribute, name, or associated label text
- Filters:
  - :name (String) - 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
:select - Find select elements
- Locator: Match id, test_id attribute, name, placeholder, or associated label text
- Filters:
  - :name (String) - Matches the name attribute
  - :placeholder (String) - Matches the placeholder attribute
  - :disabled (Boolean, :all) - Match disabled field? (Default: false)
  - :multiple (Boolean) - Match fields that accept multiple values
  - :options (Array) - Exact match options
  - :with_options (Array) - Partial match options
  - :selected (String, Array) - Match the selection(s)
  - :with_selected (String, Array) - 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, test_id attribute, name, or placeholder
- Filters:
  - :name (String) - Matches the name attribute
  - :placeholder (String) - Matches the placeholder attribute
  - :disabled (Boolean, :all) - Match disabled field? (Default: false)
  - :options (Array) - Exact match options
  - :with_options (Array) - 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, test_id attribute, name, or associated label text
- Filters:
  - :name (String) - 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, 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, test_id, or caption text of table
- Filters:
  - :caption (String) - Match text of associated caption
  - :with_rows (Array>, Array>) - Partial match <td> data - visibility of <td> elements is not considered
  - :rows (Array>) - Match all <td>s - visibility of <td> elements is not considered
  - :with_cols (Array>, Array>) - Partial match <td> data - visibility of <td> elements is not considered
  - :cols (Array>) - Match all <td>s - visibility of <td> elements is not considered
:table_row - Find table row
- Locator: Array, Hash table row <td> contents - visibility of <td> elements is not considered
:frame - Find frame/iframe elements
- Locator: Match id 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

Defined Under Namespace

Modules: Filters Classes: CSS, CSSBuilder, Definition, FilterSet, RegexpDisassembler, XPathBuilder

Instance Attribute Summary collapse

#errors ⇒ Object readonly
Returns the value of attribute errors.

Class Method Summary collapse

Instance Method Summary collapse

#add_error(error_msg) ⇒ Object
#builder(expr = nil) ⇒ Object private
#call(locator, **options) ⇒ Object
#enable_aria_label ⇒ Object
#expression_for(name, locator, config: @config, format: current_format, **options) ⇒ Object
#format ⇒ Object (also: #current_format)
#initialize(definition, config:, format:) ⇒ Selector constructor
A new instance of Selector.
#test_id ⇒ Object
#with_filter_errors(errors) ⇒ Object private

Constructor Details

#initialize(definition, config:, format:) ⇒ `Selector`

Returns a new instance of Selector.

# 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

Instance Attribute Details

#errors ⇒ `Object` (readonly)

Returns the value of attribute errors.



31
32
33

# File 'lib/capybara/selector/selector.rb', line 31

def errors
  @errors
end

Class Method Details

.[](name) ⇒ `Object`



10
11
12

# 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

.add(name, **options, &block) ⇒ `Object`



14
15
16

# 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

.all ⇒ `Object`



6
7
8

# File 'lib/capybara/selector/selector.rb', line 6

def all
  @definitions ||= {} # rubocop:disable Naming/MemoizedInstanceVariableName
end

.for(locator) ⇒ `Object`



26
27
28

# File 'lib/capybara/selector/selector.rb', line 26

def for(locator)
  all.values.find { |sel| sel.match?(locator) }
end

.remove(name) ⇒ `Object`



22
23
24

# File 'lib/capybara/selector/selector.rb', line 22

def remove(name)
  all.delete(name.to_sym)
end

.update(name, &block) ⇒ `Object`



18
19
20

# File 'lib/capybara/selector/selector.rb', line 18

def update(name, &block)
  self[name].instance_eval(&block)
end

Instance Method Details

#add_error(error_msg) ⇒ `Object`



67
68
69

# File 'lib/capybara/selector/selector.rb', line 67

def add_error(error_msg)
  errors << error_msg
end

#builder(expr = nil) ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

# File 'lib/capybara/selector/selector.rb', line 85

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

#call(locator, **options) ⇒ `Object`

# File 'lib/capybara/selector/selector.rb', line 55

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
  warn "Locator #{locator.class}:#{locator.inspect} for selector #{name.inspect} must #{locator_description}. This will raise an error in a future version of Capybara." unless locator_valid?(locator)
end

#enable_aria_label ⇒ `Object`



47
48
49

# File 'lib/capybara/selector/selector.rb', line 47

def enable_aria_label
  @config[:enable_aria_label]
end

#expression_for(name, locator, config: @config, format: current_format, **options) ⇒ `Object`



71
72
73

# File 'lib/capybara/selector/selector.rb', line 71

def expression_for(name, locator, config: @config, format: current_format, **options)
  Selector.new(name, config: config, format: format).call(locator, **options)
end

#format ⇒ `Object` Also known as: current_format



42
43
44

# File 'lib/capybara/selector/selector.rb', line 42

def format
  @format || @definition.default_format
end

#test_id ⇒ `Object`



51
52
53

# File 'lib/capybara/selector/selector.rb', line 51

def test_id
  @config[:test_id]
end

#with_filter_errors(errors) ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

# File 'lib/capybara/selector/selector.rb', line 76

def with_filter_errors(errors)
  old_errors = @errors
  @errors = errors
  yield
ensure
  @errors = old_errors
end

Class: Capybara::Selector

Overview

Built-in Selectors

Defined Under Namespace

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(definition, config:, format:) ⇒ Selector

Instance Attribute Details

#errors ⇒ Object (readonly)

Class Method Details

.[](name) ⇒ Object

.add(name, **options, &block) ⇒ Object

.all ⇒ Object

.for(locator) ⇒ Object

.remove(name) ⇒ Object

.update(name, &block) ⇒ Object

Instance Method Details

#add_error(error_msg) ⇒ Object

#builder(expr = nil) ⇒ Object

#call(locator, **options) ⇒ Object

#enable_aria_label ⇒ Object

#expression_for(name, locator, config: @config, format: current_format, **options) ⇒ Object

#format ⇒ Object Also known as: current_format

#test_id ⇒ Object

#with_filter_errors(errors) ⇒ Object