Class: Capybara::Selector::Definition

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable
Inherits:	Object
Defined in:	lib/capybara/selector/definition.rb

Class Method Summary

.new(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block) ⇒ Definition constructor

Instance Attribute Summary

#expressions readonly
#name readonly
#raw_locator? ⇒ Boolean readonly Internal use only Internal use only
#supports_exact? ⇒ Boolean readonly Internal use only Internal use only

Instance Method Summary

#css(*expression_filters) {|locator, options| ... } ⇒ #call

Define a selector by a CSS selector.
#custom_filters
#default_format
#default_visibility(fallback = Capybara.ignore_hidden_elements, options = {})
#describe_all_expression_filters(**opts)
#describe_expression_filters(&block)
#describe_node_filters(&block)
#description(options) ⇒ String
#expression_filter(name, *types, matcher: nil, **options, &block)
#expression_filters
#filter_set(name, filters_to_use = nil)
#label(label) ⇒ String

Set/get a descriptive label for the selector.
#locator_filter(*types, **options, &block)
#match {|locator| ... } ⇒ #call

Automatic selector detection.
#match?(locator) ⇒ Boolean

Should this selector be used for the passed in locator.
#node_filter(name, *types, options = {}, &block)
#node_filters
#visible(default_visibility = nil, &block)

Set the default visibility mode that should be used if no visible option is passed when using the selector.
#xpath(*expression_filters) {|locator, options| ... } ⇒ #call

Define a selector by an xpath expression.
#expression(type, allowed_filters, &block) private
#handled_custom_options(filter, options) private
#parameter_names(block) private
#locator_types Internal use only Internal use only

Constructor Details

.new(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block) ⇒ `Definition`

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 16


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

Instance Attribute Details

#expressions (readonly)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 12


attr_reader :name, :expressions

#name (readonly)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 12


attr_reader :name, :expressions

#raw_locator? ⇒ `Boolean` (readonly)

This method is for internal use only.

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 227


def raw_locator?
  !!@raw_locator
end

#supports_exact? ⇒ `Boolean` (readonly)

This method is for internal use only.

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 232


def supports_exact?
  @supports_exact
end

Instance Method Details

#css(*expression_filters) {|locator, options| ... } ⇒ #call #css ⇒ #call

Define a selector by a CSS selector

Returns:

(#call) —

The block that will be called to generate the CSS selector

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 77


def css(*allowed_filters, &block)
  expression(:css, allowed_filters, &block)
end

#custom_filters

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 32


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

#default_format

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 236


def default_format
  return nil if @expressions.keys.empty?

  if @expressions.size == 1
    @expressions.keys.first
  else
    :xpath
  end
end

#default_visibility(fallback = Capybara.ignore_hidden_elements, options = {})

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 217


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

#describe_all_expression_filters(**opts)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 190


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

#describe_expression_filters(&block)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 180


def describe_expression_filters(&block)
  if block
    describe(:expression_filters, &block)
  else
    describe(:expression_filters) do |**options|
      describe_all_expression_filters(**options)
    end
  end
end

#describe_node_filters(&block)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 200


def describe_node_filters(&block)
  describe(:node_filters, &block)
end

#description(options) ⇒ `String`

Parameters:

options (Hash) —

The options of the query used to generate the description

Returns:

(String) —

Description of the selector when used with the options passed

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 116


def_delegator :@filter_set, :description

#expression(type, allowed_filters, &block) (private)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 268


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

#expression_filter(name, *types, matcher: nil, **options, &block)

Parameters:

name (Symbol, Regexp) —

The filter name
matcher (Regexp) —

(nil) A Regexp used to check whether a specific option is handled by this filter
types (Array<Symbol>) —

The types of the filter - currently valid types are [:boolean]
options (Hash) —

({}) Options of the filter

Options Hash (**options):

:valid_values (Array<>) —

Valid values for this filter
:default (Object) —

The default value of the filter (if any)
:skip_if (Object) —

Value of the filter that will cause it to be skipped
:matcher (Regexp) — default: 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.

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 166


def_delegators :@filter_set, :node_filter, :expression_filter, :filter

#expression_filters

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 41


def expression_filters
  @filter_set.expression_filters
end

#filter_set(name, filters_to_use = nil)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 174


def filter_set(name, filters_to_use = nil)
  @filter_set.import(name, filters_to_use)
end

#handled_custom_options(filter, options) (private)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 255


def handled_custom_options(filter, options)
  options.select do |option, _|
    filter.handles_option?(option) && !::Capybara::Queries::SelectorQuery::VALID_KEYS.include?(option)
  end
end

#label(label) ⇒ `String` #label ⇒ `String`

Set/get a descriptive label for the selector

Returns:

(String) —

The currently set label

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 104


def label(label = nil)
  @label = label if label
  @label
end

#locator_filter(*types, **options, &block)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 168


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

#locator_types

This method is for internal use only.

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 247


def locator_types
  return nil unless @locator_type

  Array(@locator_type)
end

#match {|locator| ... } ⇒ #call

Automatic selector detection

Yields:

(locator) —

This block takes the passed in locator string and returns whether or not it matches the selector

Yield Parameters:

, (String) —

locator The locator string used to determine if it matches the selector

Yield Returns:

(Boolean) —

Whether this selector matches the locator string

Returns:

(#call) —

The block that will be used to detect selector match

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 90


def match(&block)
  @match = block if block
  @match
end

#match?(locator) ⇒ `Boolean`

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

Parameters:

locator (String) —

The locator passed to the query

Returns:

(Boolean) —

Whether or not to use this selector

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 127


def match?(locator)
  @match&.call(locator)
end

#node_filter(name, *types, options = {}, &block)

Parameters:

name (Symbol, Regexp) —

The filter name
types (Array<Symbol>) —

The types of the filter - currently valid types are [:boolean]
options (Hash) (defaults to: {}) —

({}) Options of the filter

Options Hash (options):

:valid_values (Array<>) —

Valid values for this filter
:default (Object) —

The default value of the filter (if any)
:skip_if (Object) —

Value of the filter that will cause it to be skipped
:matcher (Regexp) — default: 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.

[ GitHub ]

#node_filters

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 37


def node_filters
  @filter_set.node_filters
end

#parameter_names(block) (private)

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 261


def parameter_names(block)
  key_types = %i[key keyreq]
  # user filter_map when we drop dupport for 2.6
  # block.parameters.select { |(type, _name)| key_types.include? type }.map { |(_, name)| name }
  block.parameters.filter_map { |(type, name)| name if key_types.include? type }
end

#visible(default_visibility = nil, &block)

Set the default visibility mode that should be used if no visible option is passed when using the selector. If not specified will default to the behavior indicated by Capybara.ignore_hidden_elements

Parameters:

default_visibility (Symbol) (defaults to: nil) —
Only find elements with the specified visibility:
- :all - finds visible and invisible elements.
- :hidden - only finds invisible elements.
- :visible - only finds visible elements.

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 213


def visible(default_visibility = nil, &block)
  @default_visibility = block || default_visibility
end

#xpath(*expression_filters) {|locator, options| ... } ⇒ #call #xpath ⇒ #call

Define a selector by an xpath expression

Returns:

(#call) —

The block that will be called to generate the ::XPath expression

[ GitHub ]

# File 'lib/capybara/selector/definition.rb', line 59


def xpath(*allowed_filters, &block)
  expression(:xpath, allowed_filters, &block)
end

Class: Capybara::Selector::Definition

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block) ⇒ Definition

Instance Attribute Details

#expressions (readonly)

#name (readonly)

#raw_locator? ⇒ Boolean (readonly)

#supports_exact? ⇒ Boolean (readonly)

Instance Method Details

#css(*expression_filters) {|locator, options| ... } ⇒ #call #css ⇒ #call

#custom_filters

#default_format

#default_visibility(fallback = Capybara.ignore_hidden_elements, options = {})

#describe_all_expression_filters(**opts)

#describe_expression_filters(&block)

#describe_node_filters(&block)

#description(options) ⇒ String

#expression(type, allowed_filters, &block) (private)

#expression_filter(name, *types, matcher: nil, **options, &block)

#expression_filters

#filter_set(name, filters_to_use = nil)

#handled_custom_options(filter, options) (private)

#label(label) ⇒ String #label ⇒ String

#locator_filter(*types, **options, &block)

#locator_types

#match {|locator| ... } ⇒ #call

#match?(locator) ⇒ Boolean

#node_filter(name, *types, options = {}, &block)

#node_filters

#parameter_names(block) (private)

#visible(default_visibility = nil, &block)

#xpath(*expression_filters) {|locator, options| ... } ⇒ #call #xpath ⇒ #call

.new(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block) ⇒ `Definition`

#raw_locator? ⇒ `Boolean` (readonly)

#supports_exact? ⇒ `Boolean` (readonly)

#description(options) ⇒ `String`

#label(label) ⇒ `String` #label ⇒ `String`

#match?(locator) ⇒ `Boolean`