Class: Capybara::Selector::Definition

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/capybara/selector/definition.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, locator_type: nil, raw_locator: false, supports_exact: nil, &block) ⇒ Definition

Returns a new instance of Definition.



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/capybara/selector/definition.rb', line 15

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 ⇒ Object (readonly)

Returns the value of attribute expressions.



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

def expressions
  @expressions
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



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

def name
  @name
end

Instance Method Details

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

Define a selector by a CSS selector

Overloads:

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

    Parameters:

    • expression_filters (Array<Symbol>) —

      ([]) Names of filters that can be implemented via this CSS selector

    Yields:

    • (locator, options) —

      The block to use to generate the CSS selector

    Yield Parameters:

    • locator (String) —

      The locator string passed to the query

    • options (Hash) —

      The options hash passed to the query

    Yield Returns:

    • (#to_s) —

      An object that can produce a CSS selector

Returns:

  • (#call) —

    The block that will be called to generate the CSS selector



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

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

#custom_filters ⇒ Object 



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

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 ⇒ Object 



235
236
237
238
239
240
241
242
243
 
# File 'lib/capybara/selector/definition.rb', line 235

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 = {}) ⇒ Object 



216
217
218
219
220
221
222
223
 
# File 'lib/capybara/selector/definition.rb', line 216

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) ⇒ Object 



189
190
191
192
193
194
195
196
197
 
# File 'lib/capybara/selector/definition.rb', line 189

def describe_all_expression_filters(**opts)
  expression_filters.map do |ef_name, ef|
    if ef.matcher?
      handled_custom_keys(ef, opts.keys).map { |key| " with #{ef_name}[#{key} => #{opts[key]}]" }.join
    elsif opts.key?(ef_name)
      " with #{ef_name} #{opts[ef_name]}"
    end
  end.join
end

#describe_expression_filters(&block) ⇒ Object 



179
180
181
182
183
184
185
186
187
 
# File 'lib/capybara/selector/definition.rb', line 179

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

#describe_node_filters(&block) ⇒ Object 



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

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

#description(options) ⇒ String

Returns Description of the selector when used with the options passed.

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



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

def_delegator :@filter_set, :description

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

Parameters:

  • name (Symbol, Regexp) —

    The filter name

  • matcher (Regexp) (defaults to: nil) —

    (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.



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

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

#expression_filters ⇒ Object 



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

def expression_filters
  @filter_set.expression_filters
end

#filter_set(name, filters_to_use = nil) ⇒ Object 



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

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

#label(label) ⇒ String #label ⇒ String

Set/get a descriptive label for the selector

Overloads:

  • #label(label) ⇒ String

    Parameters:

    • label (String) —

      A descriptive label for this selector - used in error messages

Returns:

  • (String) —

    The currently set label



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

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

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



167
168
169
170
171
 
# File 'lib/capybara/selector/definition.rb', line 167

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 ⇒ 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. 



246
247
248
249
250
 
# File 'lib/capybara/selector/definition.rb', line 246

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



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

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



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

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

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

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.




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

#node_filters ⇒ Object 



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

def node_filters
  @filter_set.node_filters
end

#raw_locator? ⇒ Boolean

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.

Returns:

  • (Boolean) 


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

def raw_locator?
  !!@raw_locator
end

#supports_exact? ⇒ Boolean

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.

Returns:

  • (Boolean) 


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

def supports_exact?
  @supports_exact
end

#visible(default_visibility = nil, &block) ⇒ Object

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

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.


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

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

Overloads:

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

    Parameters:

    • expression_filters (Array<Symbol>) —

      ([]) Names of filters that are implemented via this expression, if not specified the names of any keyword parameters in the block will be used

    Yields:

    • (locator, options) —

      The block to use to generate the XPath expression

    Yield Parameters:

    • locator (String) —

      The locator string passed to the query

    • options (Hash) —

      The options hash passed to the query

    Yield Returns:

    • (#to_xpath, #to_s) —

      An object that can produce an xpath expression

Returns:

  • (#call) —

    The block that will be called to generate the XPath expression



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

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