class Capybara::Selector::Definition

Attributes

expressions[R]
name[R]

Public Class Methods

new(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block) click to toggle source
# 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

Public Instance Methods

@filter_set() click to toggle source

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
# File lib/capybara/selector/definition.rb, line 116
def_delegator :@filter_set, :description
css(*allowed_filters, &block) click to toggle source

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

# File lib/capybara/selector/definition.rb, line 77
def css(*allowed_filters, &block)
  expression(:css, allowed_filters, &block)
end
custom_filters() click to toggle source
# 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() click to toggle source
# 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 = {}) click to toggle source
# 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) click to toggle source
# 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) click to toggle source
# 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) click to toggle source
# File lib/capybara/selector/definition.rb, line 200
def describe_node_filters(&block)
  describe(:node_filters, &block)
end
expression_filters() click to toggle source
# File lib/capybara/selector/definition.rb, line 41
def expression_filters
  @filter_set.expression_filters
end
filter_set(name, filters_to_use = nil) click to toggle source
# File lib/capybara/selector/definition.rb, line 174
def filter_set(name, filters_to_use = nil)
  @filter_set.import(name, filters_to_use)
end
label(label = nil) click to toggle source

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

# File lib/capybara/selector/definition.rb, line 104
def label(label = nil)
  @label = label if label
  @label
end
locator_filter(*types, **options, &block) click to toggle source
# 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() click to toggle source

@api private

# File lib/capybara/selector/definition.rb, line 247
def locator_types
  return nil unless @locator_type

  Array(@locator_type)
end
match(&block) click to toggle source

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 determine 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

# File lib/capybara/selector/definition.rb, line 90
def match(&block)
  @match = block if block
  @match
end
match?(locator) click to toggle source
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

# File lib/capybara/selector/definition.rb, line 127
def match?(locator)
  @match&.call(locator)
end
node_filters() click to toggle source
# File lib/capybara/selector/definition.rb, line 37
def node_filters
  @filter_set.node_filters
end
raw_locator?() click to toggle source

@api private

# File lib/capybara/selector/definition.rb, line 227
def raw_locator?
  !!@raw_locator
end
supports_exact?() click to toggle source

@api private

# File lib/capybara/selector/definition.rb, line 232
def supports_exact?
  @supports_exact
end
visible(default_visibility = nil, &block) click to toggle source

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.
# File lib/capybara/selector/definition.rb, line 213
def visible(default_visibility = nil, &block)
  @default_visibility = block || default_visibility
end
xpath(*allowed_filters, &block) click to toggle source

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

# File lib/capybara/selector/definition.rb, line 59
def xpath(*allowed_filters, &block)
  expression(:xpath, allowed_filters, &block)
end

Private Instance Methods

expression(type, allowed_filters, &block) click to toggle source
# File lib/capybara/selector/definition.rb, line 266
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
handled_custom_options(filter, options) click to toggle source
# 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
parameter_names(block) click to toggle source
# File lib/capybara/selector/definition.rb, line 261
def parameter_names(block)
  key_types = %i[key keyreq]
  block.parameters.select { |(type, _name)| key_types.include? type }.map { |(_type, name)| name }
end