123456789_123456789_123456789_123456789_123456789_

Module: Capybara::Node::Finders

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
Base, Document, Element, Simple
Defined in: lib/capybara/node/finders.rb

Instance Method Summary

Instance Method Details

#all([kind = {Capybara.default_selector]}, locator = nil, **options) ⇒ Capybara::Result #all([kind = {Capybara.default_selector]}, locator = nil, **options, &filter_block) {|element| ... } ⇒ Capybara::Result
Also known as: #find_all

Find all elements on the page matching the given selector and options.

Both XPath and CSS expressions are supported, but ::Capybara does not try to automatically distinguish between them. The following statements are equivalent:

page.all(:css, 'a#person_123')
page.all(:xpath, './/a[@id="person_123"]')

If the type of selector is left out, ::Capybara uses default_selector. It’s set to :css by default.

page.all("a#person_123")

Capybara.default_selector = :xpath
page.all('.//a[@id="person_123"]')

The set of found elements can further be restricted by specifying options. It’s possible to select elements by their text or visibility:

page.all('a', text: 'Home')
page.all('#menu li', visible: true)

By default Capybara’s waiting behavior will wait up to default_max_wait_time seconds for matching elements to be available and then return an empty result if none are available. It is possible to set expectations on the number of results located and ::Capybara will raise an exception if the number of elements located don’t satisfy the specified conditions. The expectations can be set using:

page.assert_selector('p#foo', count: 4)
page.assert_selector('p#foo', maximum: 10)
page.assert_selector('p#foo', minimum: 1)
page.assert_selector('p#foo', between: 1..10)

If the driver is capable of executing JavaScript, this method will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time this method will wait is controlled through default_max_wait_time.

Parameters:

  • kind (Symbol) —

    Optional selector type (:css, :xpath, :field, etc.). Defaults to default_selector.

  • locator (String) —

    The locator for the specified selector

  • options (Hash) —

    a customizable set of options

Returns:

Raises:

[ GitHub ] 

  


# File 'lib/capybara/node/finders.rb', line 257



def all(*args, allow_reload: false, **options, &optional_filter_block)
  minimum_specified = options_include_minimum?(options)
  options = { minimum: 1 }.merge(options) unless minimum_specified
  options[:session_options] = session_options
  query = Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
  result = nil
  begin
    synchronize(query.wait) do
      result = query.resolve_for(self)
      result.allow_reload! if allow_reload
      raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count?

      result
    end
  rescue Capybara::ExpectationNotMet
    raise if minimum_specified || (result.compare_count == 1)

    Result.new([], nil)
  end
end


  








  

    #ambiguous?(query, result)  ⇒ Boolean  (private)
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 318



def ambiguous?(query, result)
  %i[one smart].include?(query.match) && (result.size > 1)
end


  








  

    #ancestor(*args, **options, &optional_filter_block)  ⇒ Capybara::Node::Element 
  



  

    

Find an Element based on the given arguments that is also an ancestor of the element called on. #ancestor will raise an error if the element is not found.



#ancestor takes the same options as #find.



element.ancestor('#foo').find('.bar')
element.ancestor(:xpath, './/div[contains(., "bar")]')
element.ancestor('ul', text: 'Quox').click_link('Delete')



If the driver is capable of executing JavaScript, this method will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time this method will wait is controlled through default_max_wait_time.


  





  
Parameters:


    
  
  • 
    options
    (Hash)
—    
    

    a customizable set of options
    

    
  
    • 


    
Options Hash (**options):

    
    
        
  • 
          wait
          (false, true, Numeric)
            — 
    

    Maximum time to wait for matching element to appear. Defaults to default_max_wait_time.
    

            
    • 
    


Returns:



Raises:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 81



def ancestor(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  synced_resolve Capybara::Queries::AncestorQuery.new(*args, **options, &optional_filter_block)
end


  








  

    #find(*args, **options, &optional_filter_block)  ⇒ Capybara::Node::Element 
  



  

    

Find an Element based on the given arguments. #find will raise an error if the element is not found.



page.find('#foo').find('.bar')
page.find(:xpath, './/div[contains(., "bar")]')
page.find('li', text: 'Quox').click_link('Delete')



If the driver is capable of executing JavaScript, this method will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time this method will wait is controlled through default_max_wait_time.


  





  
Parameters:


    
  
  • 
    options
    (Hash)
—    
    

    a customizable set of options
    

    
  
    • 


    
Options Hash (**options):

    
    
        
  • 
          wait
          (false, true, Numeric)
            — 
    

    Maximum time to wait for matching element to appear. Defaults to default_max_wait_time.
    

            
    • 
        
  • 
          text
          (String, Regexp)
            — 
    

    Only find elements which contain this text or match this regexp
    

            
    • 
        
  • 
          exact_text
          (String, Regexp, String)
            — 
    

    When String the elements contained text must match exactly, when Boolean controls whether the ‘text` option must match exactly. Defaults to exact_text.
    

            
    • 
        
  • 
          normalize_ws
          (Boolean)
            — 
    

    Whether the ‘text`/`exact_text` options are compared against element text with whitespace normalized or as returned by the driver. Defaults to default_normalize_ws.
    

            
    • 
        
  • 
          visible
          (Boolean, Symbol)
            — 
    

    Only find elements with the specified visibility. Defaults to behavior indicated by ignore_hidden_elements.
    


    * true - only finds visible elements.
* false - finds invisible _and_ visible elements.
* :all - same as false; finds visible and invisible elements.
* :hidden - only finds invisible elements.
* :visible - same as true; only finds visible elements.
    

            
    • 
        
  • 
          obscured
          (Boolean)
            — 
    

    Only find elements with the specified obscured state:
    

    • 

      true - only find elements whose centerpoint is not in the viewport or is obscured by another non-descendant element.
      

    • 

      false - only find elements whose centerpoint is in the viewport and is not obscured by other non-descendant elements.
      

    

            
    • 
        
  • 
          id
          (String, Regexp)
            — 
    

    Only find elements with an id that matches the value passed
    

            
    • 
        
  • 
          class
          (String, Array<String>, Regexp)
            — 
    

    Only find elements with matching class/classes.
    

    • 

      Absence of a class can be checked by prefixing the class name with ‘!`
      

    • 

      If you need to check for existence of a class name that starts with ‘!` then prefix with !!
      


      class:['a', '!b', '!!!c'] # limit to elements with class 'a' and '!c' but not class 'b'
      

    

            
    • 
        
  • 
          style
          (String, Regexp, Hash)
            — 
    

    Only find elements with matching style. String and Regexp will be checked against text of the elements style attribute, while a Hash will be compared against the elements full style
    

            
    • 
        
  • 
          exact
          (Boolean)
            — 
    

    Control whether is expressions in the given ::XPath match exactly or partially. Defaults to exact.
    

            
    • 
        
  • 
          match
          (Symbol)
            — 
    

    The matching strategy to use. Defaults to match.
    

            
    • 
    


Returns:



Raises:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 51



def find(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  count_options = options.slice(*Capybara::Queries::BaseQuery::COUNT_KEYS)
  unless count_options.empty?
    Capybara::Helpers.warn(
      "'find' does not support count options (#{count_options}) ignoring. " \
      "Called from: #{Capybara::Helpers.filter_backtrace(caller)}"
    )
  end
  synced_resolve Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
end


  








  

    #find_all([kind = {Capybara.default_selector]}, locator = nil, **options)  
  



  

    

Alias for #all.


  



  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 277



alias_method :find_all, :all


  








  

    #find_button([locator], **options)  ⇒ Capybara::Node::Element   



  

    

Find a button on the page. This can be any <input> element of type submit, reset, image, button or it can be a <button> element. All buttons can be found by their id, name, test_id attribute, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute.


  





  
Returns:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 184



def find_button(locator = nil, **options, &optional_filter_block)
  find(:button, locator, **options, &optional_filter_block)
end


  








  

    #find_by_id(id, **options, &optional_filter_block)  ⇒ Capybara::Node::Element 
  



  

    

Find a element on the page, given its id.



If the driver is capable of executing JavaScript, this method will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time this method will wait is controlled through default_max_wait_time.


  





  
Parameters:


    
  
  • 
    id
    (String)
—    
    

    id of element
    

    
  
    • 
  
  • 
    options
    (Hash)
—    
    

    a customizable set of options
    

    
  
    • 


    
Options Hash (**options):

    
    
        
  • 
          wait
          (false, true, Numeric)
            — 
    

    Maximum time to wait for matching element to appear. Defaults to default_max_wait_time.
    

            
    • 
    


Returns:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 198



def find_by_id(id, **options, &optional_filter_block)
  find(:id, id, **options, &optional_filter_block)
end


  








  

    #find_field([locator], **options)  ⇒ Capybara::Node::Element   



  

    

Find a form field on the page. The field can be found by its name, id or label text.


  





  
Returns:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 135



def find_field(locator = nil, **options, &optional_filter_block)
  find(:field, locator, **options, &optional_filter_block)
end


  










  

    #first([kind], locator, options)  ⇒ Capybara::Node::Element   



  

    

Find the first element on the page matching the given selector and options. By default #first will wait up to default_max_wait_time seconds for matching elements to appear and then raise an error if no matching element is found, or nil if the provided count options allow for empty results.


  





  
Returns:



Raises:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 293



def first(*args, **options, &optional_filter_block)
  options = { minimum: 1 }.merge(options) unless options_include_minimum?(options)
  all(*args, **options, &optional_filter_block).first
end


  








  

    #options_include_minimum?(opts)  ⇒ Boolean  (private)
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 326



def options_include_minimum?(opts)
  %i[count minimum between].any? { |key| opts.key?(key) }
end


  








  

    #parent   (private)
  

  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 330



def parent
  first(:xpath, './parent::*', minimum: 0)
end


  








  

    #prefer_exact?(query)  ⇒ Boolean  (private)
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 322



def prefer_exact?(query)
  %i[smart prefer_exact].include?(query.match)
end


  








  

    #sibling(*args, **options, &optional_filter_block)  ⇒ Capybara::Node::Element 
  



  

    

Find an Element based on the given arguments that is also a sibling of the element called on. #sibling will raise an error if the element is not found.



#sibling takes the same options as #find.



element.sibling('#foo').find('.bar')
element.sibling(:xpath, './/div[contains(., "bar")]')
element.sibling('ul', text: 'Quox').click_link('Delete')



If the driver is capable of executing JavaScript, this method will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time this method will wait is controlled through default_max_wait_time.


  





  
Parameters:


    
  
  • 
    options
    (Hash)
—    
    

    a customizable set of options
    

    
  
    • 


    
Options Hash (**options):

    
    
        
  • 
          wait
          (false, true, Numeric)
            — 
    

    Maximum time to wait for matching element to appear. Defaults to default_max_wait_time.
    

            
    • 
    


Returns:



Raises:





  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 104



def sibling(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  synced_resolve Capybara::Queries::SiblingQuery.new(*args, **options, &optional_filter_block)
end


  








  

    #synced_resolve(query)   (private)
  

  [ GitHub ]


  

  


# File 'lib/capybara/node/finders.rb', line 300



def synced_resolve(query)
  synchronize(query.wait) do
    if prefer_exact?(query)
      result = query.resolve_for(self, true)
      result = query.resolve_for(self, false) if result.empty? && query.supports_exact? && !query.exact?
    else
      result = query.resolve_for(self)
    end

    if ambiguous?(query, result)
      raise Capybara::Ambiguous, "Ambiguous match, found #{result.size} elements matching #{query.applied_description}"
    end
    raise Capybara::ElementNotFound, "Unable to find #{query.applied_description}" if result.empty?

    result.first
  end.tap(&:allow_reload!)
end