Class: Capybara::Selector

Inherits:
Object
  • Object
show all
Defined in:
lib/capybara/selector/css.rb,
lib/capybara/selector/selector.rb,
lib/capybara/selector/filter_set.rb,
lib/capybara/selector/filters/base.rb,
lib/capybara/selector/filters/node_filter.rb,
lib/capybara/selector/filters/expression_filter.rb

Defined Under Namespace

Modules: Filters Classes: CSS, FilterSet

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, &block) ⇒ Selector

Returns a new instance of Selector



44
45
46
47
48
49
50
51
52
53
54
55
56
# File 'lib/capybara/selector/selector.rb', line 44

def initialize(name, &block)
  @name = name
  @filter_set = FilterSet.add(name) {}
  @match = nil
  @label = nil
  @failure_message = nil
  @description = nil
  @format = nil
  @expression = nil
  @expression_filters = {}
  @default_visibility = nil
  instance_eval(&block)
end

Instance Attribute Details

#formatObject (readonly)

Returns the value of attribute format



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

def format
  @format
end

#nameObject (readonly)

Returns the value of attribute name



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

def name
  @name
end

Class Method Details

.add(name, &block) ⇒ Object



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

def add(name, &block)
  all[name.to_sym] = Capybara::Selector.new(name.to_sym, &block)
end

.allObject



27
28
29
# File 'lib/capybara/selector/selector.rb', line 27

def all
  @selectors ||= {}
end

.remove(name) ⇒ Object



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

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

.update(name, &block) ⇒ Object



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

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

Instance Method Details

#call(locator, **options) ⇒ Object



153
154
155
156
157
158
159
160
# File 'lib/capybara/selector/selector.rb', line 153

def call(locator, **options)
  if format
    # @expression.call(locator, options.select {|k,v| @expression_filters.include?(k)})
    @expression.call(locator, options)
  else
    warn "Selector has no format"
  end
end

#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



106
107
108
109
110
111
112
# File 'lib/capybara/selector/selector.rb', line 106

def css(*expression_filters, &block)
  if block
    @format, @expression = :css, block
    expression_filters.flatten.each { |ef| custom_filters[ef] = nil }
  end
  format == :css ? @expression : nil
end

#custom_filtersObject



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

def custom_filters
  @filter_set.filters
end

#default_visibility(fallback = Capybara.ignore_hidden_elements) ⇒ Object



221
222
223
224
225
226
227
# File 'lib/capybara/selector/selector.rb', line 221

def default_visibility(fallback = Capybara.ignore_hidden_elements)
  if @default_visibility.nil?
    fallback
  else
    @default_visibility
  end
end

#describe(&block) ⇒ Object



204
205
206
# File 'lib/capybara/selector/selector.rb', line 204

def describe(&block)
  @filter_set.describe(&block)
end

#description(**options) ⇒ String

Description of the selector

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



149
150
151
# File 'lib/capybara/selector/selector.rb', line 149

def description(**options)
  @filter_set.description(options)
end

#expression_filter(name, *types_and_options, &block) ⇒ Object



191
192
193
# File 'lib/capybara/selector/selector.rb', line 191

def expression_filter(name, *types_and_options, &block)
  add_filter(name, Filters::ExpressionFilter, *types_and_options, &block)
end

#expression_filtersObject



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

def expression_filters
  @filter_set.expression_filters
end

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

Define a non-expression filter for use with this selector

Parameters:

  • name (Symbol)

    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



187
188
189
# File 'lib/capybara/selector/selector.rb', line 187

def filter(name, *types_and_options, &block)
  add_filter(name, Filters::NodeFilter, *types_and_options, &block)
end

#filter_set(name, filters_to_use = nil) ⇒ Object



195
196
197
198
199
200
201
202
# File 'lib/capybara/selector/selector.rb', line 195

def filter_set(name, filters_to_use = nil)
  f_set = FilterSet.all[name]
  f_set.filters.each do |n, filter|
    custom_filters[n] = filter if filters_to_use.nil? || filters_to_use.include?(n)
  end

  f_set.descriptions.each { |desc| @filter_set.describe(&desc) }
end

#label(label) ⇒ String #labelString

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



137
138
139
140
# File 'lib/capybara/selector/selector.rb', line 137

def label(label = nil)
  @label = label if label
  @label
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



123
124
125
126
# File 'lib/capybara/selector/selector.rb', line 123

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



171
172
173
# File 'lib/capybara/selector/selector.rb', line 171

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

#node_filtersObject



62
63
64
# File 'lib/capybara/selector/selector.rb', line 62

def node_filters
  @filter_set.node_filters
end

#visible(default_visibility) ⇒ 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)

    Only find elements with the specified visibility:

    • :all - finds visible and invisible elements.

    • :hidden - only finds invisible elements.

    • :visible - only finds visible elements.



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

def visible(default_visibility)
  @default_visibility = 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 can be implemented via this expression

    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



84
85
86
87
88
89
90
# File 'lib/capybara/selector/selector.rb', line 84

def xpath(*expression_filters, &block)
  if block
    @format, @expression = :xpath, block
    expression_filters.flatten.each { |ef| custom_filters[ef] = Filters::IdentityExpressionFilter.new }
  end
  format == :xpath ? @expression : nil
end