Method: Capybara::Session#within

Defined in:
lib/capybara/session.rb

#within(*find_args) ⇒ Object #within(a_node) ⇒ Object Also known as: within_element

Executes the given block within the context of a node. #within takes the same options as #find, as well as a block. For the duration of the block, any command to Capybara will be handled as though it were scoped to the given element.

within(:xpath, './/div[@id="delivery-address"]') do
  fill_in('Street', with: '12 Main Street')
end

Just as with #find, if multiple elements match the selector given to #within, an error will be raised, and just as with #find, this behaviour can be controlled through the :match and :exact options.

It is possible to omit the first parameter, in that case, the selector is assumed to be of the type set in default_selector.

within('div#delivery-address') do
  fill_in('Street', with: '12 Main Street')
end

Note that a lot of uses of #within can be replaced more succinctly with chaining:

find('div#delivery-address').fill_in('Street', with: '12 Main Street')

Overloads:

  • #within(*find_args) ⇒ Object

    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

  • #within(a_node) ⇒ Object

    Parameters:

Raises:



362
363
364
365
366
367
368
369
370
 
# File 'lib/capybara/session.rb', line 362

def within(*args, **kw_args)
  new_scope = args.first.respond_to?(:to_capybara_node) ? args.first.to_capybara_node : find(*args, **kw_args)
  begin
    scopes.push(new_scope)
    yield new_scope if block_given?
  ensure
    scopes.pop
  end
end