class Capybara::Session

The {Session} class represents a single user's interaction with the system. The {Session} can use any of the underlying drivers. A session can be initialized manually like this:

session = Capybara::Session.new(:culerity, MyRackApp)

The application given as the second argument is optional. When running Capybara against an external page, you might want to leave it out:

session = Capybara::Session.new(:culerity)
session.visit('http://www.google.com')

When {Capybara.configure threadsafe} is `true` the sessions options will be initially set to the current values of the global options and a configuration block can be passed to the session initializer. For available options see {Capybara::SessionConfig::OPTIONS}:

session = Capybara::Session.new(:driver, MyRackApp) do |config|
  config.app_host = "http://my_host.dev"
end

The {Session} provides a number of methods for controlling the navigation of the page, such as {#visit}, {#current_path}, and so on. It also delegates a number of methods to a {Capybara::Document}, representing the current HTML document. This allows interaction:

session.fill_in('q', with: 'Capybara')
session.click_button('Search')
expect(session).to have_content('Capybara')

When using `capybara/dsl`, the {Session} is initialized automatically for you.

Constants

DOCUMENT_METHODS

@api private

DSL_METHODS
NODE_METHODS
SESSION_METHODS

Attributes

app[R]
mode[R]
server[R]
synchronized[RW]

Public Class Methods

instance_created?() click to toggle source
# File lib/capybara/session.rb, line 835
def self.instance_created?
  @@instance_created
end
new(mode, app = nil) { |config| ... } click to toggle source
# File lib/capybara/session.rb, line 77
def initialize(mode, app = nil)
  if app && !app.respond_to?(:call)
    raise TypeError, 'The second parameter to Session::new should be a rack app if passed.'
  end

  @@instance_created = true # rubocop:disable Style/ClassVars
  @mode = mode
  @app = app
  if block_given?
    raise 'A configuration block is only accepted when Capybara.threadsafe == true' unless Capybara.threadsafe

    yield config
  end
  @server = if config.run_server && @app && driver.needs_server?
    server_options = { port: config.server_port, host: config.server_host, reportable_errors: config.server_errors }
    server_options[:extra_middleware] = [Capybara::Server::AnimationDisabler] if config.disable_animation
    Capybara::Server.new(@app, **server_options).boot
  end
  @touched = false
end

Public Instance Methods

accept_alert(text = nil, **options, &blk) click to toggle source

Execute the block, accepting a alert.

@!macro modal_params

Expects a block whose actions will trigger the display modal to appear.
@example
  $0 do
    click_link('link that triggers appearance of system modal')
  end
@overload $0(text, **options, &blk)
  @param text [String, Regexp]  Text or regex to match against the text in the modal. If not provided any modal is matched.
  @option options [Numeric] :wait  Maximum time to wait for the modal to appear after executing the block. Defaults to {Capybara.configure default_max_wait_time}.
  @yield Block whose actions will trigger the system modal
@overload $0(**options, &blk)
  @option options [Numeric] :wait  Maximum time to wait for the modal to appear after executing the block. Defaults to {Capybara.configure default_max_wait_time}.
  @yield Block whose actions will trigger the system modal
@return [String]  the message shown in the modal
@raise [Capybara::ModalNotFound]  if modal dialog hasn't been found
# File lib/capybara/session.rb, line 656
def accept_alert(text = nil, **options, &blk)
  accept_modal(:alert, text, options, &blk)
end
accept_confirm(text = nil, **options, &blk) click to toggle source

Execute the block, accepting a confirm.

@macro modal_params

# File lib/capybara/session.rb, line 666
def accept_confirm(text = nil, **options, &blk)
  accept_modal(:confirm, text, options, &blk)
end
accept_prompt(text = nil, **options, &blk) click to toggle source

Execute the block, accepting a prompt, optionally responding to the prompt.

@macro modal_params @option options [String] :with Response to provide to the prompt

# File lib/capybara/session.rb, line 687
def accept_prompt(text = nil, **options, &blk)
  accept_modal(:prompt, text, options, &blk)
end
active_element() click to toggle source

Returns the element with focus.

Not supported by Rack Test

# File lib/capybara/session.rb, line 320
def active_element
  Capybara::Queries::ActiveElementQuery.new.resolve_for(self)[0].tap(&:allow_reload!)
end
body()
Alias for: html
cleanup!()
Alias for: reset!
config() click to toggle source
# File lib/capybara/session.rb, line 839
def config
  @config ||= if Capybara.threadsafe
    Capybara.session_options.dup
  else
    Capybara::ReadOnlySessionConfig.new(Capybara.session_options)
  end
end
configure() { |config| ... } click to toggle source

Accepts a block to set the configuration options if {Capybara.configure threadsafe} is `true`. Note that some options only have an effect if set at initialization time, so look at the configuration block that can be passed to the initializer too.

# File lib/capybara/session.rb, line 829
def configure
  raise 'Session configuration is only supported when Capybara.threadsafe == true' unless Capybara.threadsafe

  yield config
end
current_host() click to toggle source

@return [String] Host of the current page

# File lib/capybara/session.rb, line 219
def current_host
  uri = URI.parse(current_url)
  "#{uri.scheme}://#{uri.host}" if uri.host
end
current_path() click to toggle source

@return [String] Path of the current page, without any domain information

# File lib/capybara/session.rb, line 204
def current_path
  # Addressable parsing is more lenient than URI
  uri = ::Addressable::URI.parse(current_url)

  # Addressable doesn't support opaque URIs - we want nil here
  return nil if uri&.scheme == 'about'

  path = uri&.path
  path unless path&.empty?
end
current_scope() click to toggle source
# File lib/capybara/session.rb, line 801
def current_scope
  scope = scopes.last
  [nil, :frame].include?(scope) ? document : scope
end
current_url() click to toggle source

@return [String] Fully qualified URL of the current page

# File lib/capybara/session.rb, line 228
def current_url
  driver.current_url
end
current_window() click to toggle source

@return [Capybara::Window] current window

# File lib/capybara/session.rb, line 457
def current_window
  Window.new(self, driver.current_window_handle)
end
dismiss_confirm(text = nil, **options, &blk) click to toggle source

Execute the block, dismissing a confirm.

@macro modal_params

# File lib/capybara/session.rb, line 676
def dismiss_confirm(text = nil, **options, &blk)
  dismiss_modal(:confirm, text, options, &blk)
end
dismiss_prompt(text = nil, **options, &blk) click to toggle source

Execute the block, dismissing a prompt.

@macro modal_params

# File lib/capybara/session.rb, line 697
def dismiss_prompt(text = nil, **options, &blk)
  dismiss_modal(:prompt, text, options, &blk)
end
document() click to toggle source
# File lib/capybara/session.rb, line 763
def document
  @document ||= Capybara::Node::Document.new(self, driver)
end
driver() click to toggle source
# File lib/capybara/session.rb, line 98
def driver
  @driver ||= begin
    unless Capybara.drivers[mode]
      other_drivers = Capybara.drivers.names.map(&:inspect)
      raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}"
    end
    driver = Capybara.drivers[mode].call(app)
    driver.session = self if driver.respond_to?(:session=)
    driver
  end
end
evaluate_async_script(script, *args) click to toggle source

Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.

@param [String] script A string of JavaScript to evaluate @param args Optional arguments that will be passed to the script @return [Object] The result of the evaluated JavaScript (may be driver specific)

# File lib/capybara/session.rb, line 630
def evaluate_async_script(script, *args)
  @touched = true
  result = driver.evaluate_async_script(script, *driver_args(args))
  element_script_result(result)
end
evaluate_script(script, *args) click to toggle source

Evaluate the given JavaScript and return the result. Be careful when using this with scripts that return complex objects, such as jQuery statements. {#execute_script} might be a better alternative.

@param [String] script A string of JavaScript to evaluate @param args Optional arguments that will be passed to the script @return [Object] The result of the evaluated JavaScript (may be driver specific)

# File lib/capybara/session.rb, line 616
def evaluate_script(script, *args)
  @touched = true
  result = driver.evaluate_script(script.strip, *driver_args(args))
  element_script_result(result)
end
execute_script(script, *args) click to toggle source

Execute the given script, not returning a result. This is useful for scripts that return complex objects, such as jQuery statements. {#execute_script} should be used over {#evaluate_script} whenever possible.

@param [String] script A string of JavaScript to execute @param args Optional arguments that will be passed to the script. Driver support for this is optional and types of objects supported may differ between drivers

# File lib/capybara/session.rb, line 601
def execute_script(script, *args)
  @touched = true
  driver.execute_script(script, *driver_args(args))
end
go_back() click to toggle source

Move back a single entry in the browser's history.

# File lib/capybara/session.rb, line 294
def go_back
  driver.go_back
end
go_forward() click to toggle source

Move forward a single entry in the browser's history.

# File lib/capybara/session.rb, line 302
def go_forward
  driver.go_forward
end
html() click to toggle source

@return [String] A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).

# File lib/capybara/session.rb, line 194
def html
  driver.html || ''
end
Also aliased as: body, source
inspect() click to toggle source
# File lib/capybara/session.rb, line 797
def inspect
  %(#<Capybara::Session>)
end
open_new_window(kind = :tab) click to toggle source

Open a new window. The current window doesn't change as the result of this call. It should be switched to explicitly.

@return [Capybara::Window] window that has been opened

# File lib/capybara/session.rb, line 481
def open_new_window(kind = :tab)
  window_opened_by do
    if driver.method(:open_new_window).arity.zero?
      driver.open_new_window
    else
      driver.open_new_window(kind)
    end
  end
end
quit() click to toggle source

Disconnect from the current driver. A new driver will be instantiated on the next interaction.

# File lib/capybara/session.rb, line 143
def quit
  @driver.quit if @driver.respond_to? :quit
  @document = @driver = nil
  @touched = false
  @server&.reset_error!
end
raise_server_error!() click to toggle source

Raise errors encountered in the server.

# File lib/capybara/session.rb, line 154
def raise_server_error!
  return unless @server&.error

  # Force an explanation for the error being raised as the exception cause
  begin
    if config.raise_server_errors
      raise CapybaraError, 'Your application server raised an error - It has been raised in your test code because Capybara.raise_server_errors == true'
    end
  rescue CapybaraError
    # needed to get the cause set correctly in JRuby -- otherwise we could just do raise @server.error
    raise @server.error, @server.error.message, @server.error.backtrace
  ensure
    @server.reset_error!
  end
end
refresh() click to toggle source

Refresh the page.

# File lib/capybara/session.rb, line 285
def refresh
  raise_server_error!
  driver.refresh
end
reset!() click to toggle source

Reset the session (i.e. remove cookies and navigate to blank page).

This method does not:

  • accept modal dialogs if they are present (Selenium driver now does, others may not)

  • clear browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc.

  • modify state of the driver/underlying browser in any other way

as doing so will result in performance downsides and it's not needed to do everything from the list above for most apps.

If you want to do anything from the list above on a general basis you can:

  • write RSpec/Cucumber/etc. after hook

  • monkeypatch this method

  • use Ruby's `prepend` method

# File lib/capybara/session.rb, line 128
def reset!
  if @touched
    driver.reset!
    @touched = false
  end
  @server&.wait_for_pending_requests
  raise_server_error!
end
Also aliased as: cleanup!, reset_session!
reset_session!()
Alias for: reset!
response_headers() click to toggle source

Returns a hash of response headers. Not supported by all drivers (e.g. Selenium).

@return [Hash<String, String>] A hash of response headers.

# File lib/capybara/session.rb, line 176
def response_headers
  driver.response_headers
end
save_and_open_page(path = nil) click to toggle source

Save a snapshot of the page and open it in a browser for inspection.

If invoked without arguments it will save file to {Capybara.configure save_path} and file will be given randomly generated filename. If invoked with a relative path the path will be relative to {Capybara.configure save_path}.

@param [String] path the path to where it should be saved

# File lib/capybara/session.rb, line 729
def save_and_open_page(path = nil)
  save_page(path).tap { |s_path| open_file(s_path) }
end
save_and_open_screenshot(path = nil, **options) click to toggle source

Save a screenshot of the page and open it for inspection.

If invoked without arguments it will save file to {Capybara.configure save_path} and file will be given randomly generated filename. If invoked with a relative path the path will be relative to {Capybara.configure save_path}.

@param [String] path the path to where it should be saved @param [Hash] options a customizable set of options

# File lib/capybara/session.rb, line 759
def save_and_open_screenshot(path = nil, **options)
  save_screenshot(path, **options).tap { |s_path| open_file(s_path) }
end
save_page(path = nil) click to toggle source

Save a snapshot of the page. If {Capybara.configure asset_host} is set it will inject `base` tag pointing to {Capybara.configure asset_host}.

If invoked without arguments it will save file to {Capybara.configure save_path} and file will be given randomly generated filename. If invoked with a relative path the path will be relative to {Capybara.configure save_path}.

@param [String] path the path to where it should be saved @return [String] the path to which the file was saved

# File lib/capybara/session.rb, line 713
def save_page(path = nil)
  prepare_path(path, 'html').tap do |p_path|
    File.write(p_path, Capybara::Helpers.inject_asset_host(body, host: config.asset_host), mode: 'wb')
  end
end
save_screenshot(path = nil, **options) click to toggle source

Save a screenshot of page.

If invoked without arguments it will save file to {Capybara.configure save_path} and file will be given randomly generated filename. If invoked with a relative path the path will be relative to {Capybara.configure save_path}.

@param [String] path the path to where it should be saved @param [Hash] options a customizable set of options @return [String] the path to which the file was saved

# File lib/capybara/session.rb, line 744
def save_screenshot(path = nil, **options)
  prepare_path(path, 'png').tap { |p_path| driver.save_screenshot(p_path, **options) }
end
send_keys(*args, **kw_args) click to toggle source

@!method send_keys

@see Capybara::Node::Element#send_keys
# File lib/capybara/session.rb, line 310
def send_keys(*args, **kw_args)
  driver.send_keys(*args, **kw_args)
end
server_url() click to toggle source
# File lib/capybara/session.rb, line 847
def server_url
  @server&.base_url
end
source()
Alias for: html
status_code() click to toggle source

Returns the current HTTP status code as an integer. Not supported by all drivers (e.g. Selenium).

@return [Integer] Current HTTP status code

# File lib/capybara/session.rb, line 186
def status_code
  driver.status_code
end
switch_to_frame(frame) click to toggle source

Switch to the given frame.

If you use this method you are responsible for making sure you switch back to the parent frame when done in the frame changed to. {#within_frame} is preferred over this method and should be used when possible. May not be supported by all drivers.

@overload switch_to_frame(element)

@param [Capybara::Node::Element] element    iframe/frame element to switch to

@overload switch_to_frame(location)

@param [Symbol] location relative location of the frame to switch to
                         * :parent - the parent frame
                         * :top - the top level document
# File lib/capybara/session.rb, line 405
def switch_to_frame(frame)
  case frame
  when Capybara::Node::Element
    driver.switch_to_frame(frame)
    scopes.push(:frame)
  when :parent
    if scopes.last != :frame
      raise Capybara::ScopeError, "`switch_to_frame(:parent)` cannot be called from inside a descendant frame's "\
                                  '`within` block.'
    end
    scopes.pop
    driver.switch_to_frame(:parent)
  when :top
    idx = scopes.index(:frame)
    top_level_scopes = [:frame, nil]
    if idx
      if scopes.slice(idx..).any? { |scope| !top_level_scopes.include?(scope) }
        raise Capybara::ScopeError, "`switch_to_frame(:top)` cannot be called from inside a descendant frame's "\
                                    '`within` block.'
      end
      scopes.slice!(idx..)
      driver.switch_to_frame(:top)
    end
  else
    raise ArgumentError, 'You must provide a frame element, :parent, or :top when calling switch_to_frame'
  end
end
switch_to_window(window = nil, **options, &window_locator) click to toggle source

Switch to the given window.

@overload switch_to_window(&block)

Switches to the first window for which given block returns a value other than false or nil.
If window that matches block can't be found, the window will be switched back and {Capybara::WindowError} will be raised.
@example
  window = switch_to_window { title == 'Page title' }
@raise [Capybara::WindowError]     if no window matches given block

@overload switch_to_window(window)

@param window [Capybara::Window]   window that should be switched to
@raise [Capybara::Driver::Base#no_such_window_error] if nonexistent (e.g. closed) window was passed

@return [Capybara::Window] window that has been switched to @raise [Capybara::ScopeError] if this method is invoked inside {#within} or

{#within_frame} methods

@raise [ArgumentError] if both or neither arguments were provided

# File lib/capybara/session.rb, line 509
def switch_to_window(window = nil, **options, &window_locator)
  raise ArgumentError, '`switch_to_window` can take either a block or a window, not both' if window && window_locator
  raise ArgumentError, '`switch_to_window`: either window or block should be provided' if !window && !window_locator

  unless scopes.last.nil?
    raise Capybara::ScopeError, '`switch_to_window` is not supposed to be invoked from '\
                                '`within` or `within_frame` blocks.'
  end

  _switch_to_window(window, **options, &window_locator)
end
using_wait_time(seconds) { || ... } click to toggle source

Yield a block using a specific maximum wait time.

# File lib/capybara/session.rb, line 810
def using_wait_time(seconds, &block)
  if Capybara.threadsafe
    begin
      previous_wait_time = config.default_max_wait_time
      config.default_max_wait_time = seconds
      yield
    ensure
      config.default_max_wait_time = previous_wait_time
    end
  else
    Capybara.using_wait_time(seconds, &block)
  end
end
visit(visit_uri) click to toggle source

Navigate to the given URL. The URL can either be a relative URL or an absolute URL The behaviour of either depends on the driver.

session.visit('/foo')
session.visit('http://google.com')

For drivers which can run against an external application, such as the selenium driver giving an absolute URL will navigate to that page. This allows testing applications running on remote servers. For these drivers, setting {Capybara.configure app_host} will make the remote server the default. For example:

Capybara.app_host = 'http://google.com'
session.visit('/') # visits the google homepage

If {Capybara.configure always_include_port} is set to `true` and this session is running against a rack application, then the port that the rack application is running on will automatically be inserted into the URL. Supposing the app is running on port `4567`, doing something like:

visit("http://google.com/test")

Will actually navigate to `google.com:4567/test`.

@param [#to_s] visit_uri The URL to navigate to. The parameter will be cast to a String.

# File lib/capybara/session.rb, line 258
def visit(visit_uri)
  raise_server_error!
  @touched = true

  visit_uri = ::Addressable::URI.parse(visit_uri.to_s)
  base_uri = ::Addressable::URI.parse(config.app_host || server_url)

  if base_uri && [nil, 'http', 'https'].include?(visit_uri.scheme)
    if visit_uri.relative?
      visit_uri_parts = visit_uri.to_hash.compact

      # Useful to people deploying to a subdirectory
      # and/or single page apps where only the url fragment changes
      visit_uri_parts[:path] = base_uri.path + visit_uri.path

      visit_uri = base_uri.merge(visit_uri_parts)
    end
    adjust_server_port(visit_uri)
  end

  driver.visit(visit_uri.to_s)
end
window_opened_by(**options) { || ... } click to toggle source

Get the window that has been opened by the passed block. It will wait for it to be opened (in the same way as other Capybara methods wait). It's better to use this method than `windows.last` {dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html#h_note_10 as order of windows isn't defined in some drivers}.

@overload window_opened_by(**options, &block)

@param options [Hash]
@option options [Numeric] :wait  maximum wait time. Defaults to {Capybara.configure default_max_wait_time}
@return [Capybara::Window]       the window that has been opened within a block
@raise [Capybara::WindowError]   if block passed to window hasn't opened window
  or opened more than one window
# File lib/capybara/session.rb, line 578
def window_opened_by(**options)
  old_handles = driver.window_handles
  yield

  synchronize_windows(options) do
    opened_handles = (driver.window_handles - old_handles)
    if opened_handles.size != 1
      raise Capybara::WindowError, 'block passed to #window_opened_by '\
                                   "opened #{opened_handles.size} windows instead of 1"
    end
    Window.new(self, opened_handles.first)
  end
end
windows() click to toggle source

Get all opened windows. The order of windows in returned array is not defined. The driver may sort windows by their creation time but it's not required.

@return [Array<Capybara::Window>] an array of all windows

# File lib/capybara/session.rb, line 468
def windows
  driver.window_handles.map do |handle|
    Window.new(self, handle)
  end
end
within(*args, **kw_args) { || ... } click to toggle source

Executes the given block within the context of a node. {#within} takes the same options as {Capybara::Node::Finders#find 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 {Capybara.configure 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')

@overload within(*find_args)

@param (see Capybara::Node::Finders#all)

@overload within(a_node)

@param [Capybara::Node::Base] a_node   The node in whose scope the block should be evaluated

@raise [Capybara::ElementNotFound] If the scope can't be found before time expires

# File lib/capybara/session.rb, line 359
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 if block_given?
  ensure
    scopes.pop
  end
end
Also aliased as: within_element
within_element(*args, **kw_args)
Alias for: within
within_fieldset(locator, &block) click to toggle source

Execute the given block within the a specific fieldset given the id or legend of that fieldset.

@param [String] locator Id or legend of the fieldset

# File lib/capybara/session.rb, line 376
def within_fieldset(locator, &block)
  within(:fieldset, locator, &block)
end
within_frame(*args, **kw_args) { || ... } click to toggle source

Execute the given block within the given iframe using given frame, frame name/id or index. May not be supported by all drivers.

@overload within_frame(element)

@param [Capybara::Node::Element]  frame element

@overload within_frame([kind = :frame], locator, **options)

@param [Symbol] kind      Optional selector type (:frame, :css, :xpath, etc.) - Defaults to :frame
@param [String] locator   The locator for the given selector kind.  For :frame this is the name/id of a frame/iframe element

@overload within_frame(index)

@param [Integer] index         index of a frame (0 based)
# File lib/capybara/session.rb, line 445
def within_frame(*args, **kw_args)
  switch_to_frame(_find_frame(*args, **kw_args))
  begin
    yield if block_given?
  ensure
    switch_to_frame(:parent)
  end
end
within_table(locator, &block) click to toggle source

Execute the given block within the a specific table given the id or caption of that table.

@param [String] locator Id or caption of the table

# File lib/capybara/session.rb, line 386
def within_table(locator, &block)
  within(:table, locator, &block)
end
within_window(window_or_proc) { || ... } click to toggle source

This method does the following:

  1. Switches to the given window (it can be located by window instance/lambda/string).

  2. Executes the given block (within window located at previous step).

  3. Switches back (this step will be invoked even if an exception occurs at the second step).

@overload within_window(window) { do_something }

@param window [Capybara::Window]       instance of {Capybara::Window} class
  that will be switched to
@raise [driver#no_such_window_error] if nonexistent (e.g. closed) window was passed

@overload within_window(proc_or_lambda) { do_something }

@param lambda [Proc]                  First window for which lambda
  returns a value other than false or nil will be switched to.
@example
  within_window(->{ page.title == 'Page title' }) { click_button 'Submit' }
@raise [Capybara::WindowError]         if no window matching lambda was found

@raise [Capybara::ScopeError] if this method is invoked inside {#within_frame} method @return value returned by the block

# File lib/capybara/session.rb, line 542
def within_window(window_or_proc)
  original = current_window
  scopes << nil
  begin
    case window_or_proc
    when Capybara::Window
      _switch_to_window(window_or_proc) unless original == window_or_proc
    when Proc
      _switch_to_window { window_or_proc.call }
    else
      raise ArgumentError, '`#within_window` requires a `Capybara::Window` instance or a lambda'
    end

    begin
      yield if block_given?
    ensure
      _switch_to_window(original) unless original == window_or_proc
    end
  ensure
    scopes.pop
  end
end

Private Instance Methods

_find_frame(*args, **kw_args) click to toggle source
# File lib/capybara/session.rb, line 912
def _find_frame(*args, **kw_args)
  case args[0]
  when Capybara::Node::Element
    args[0]
  when String, nil
    find(:frame, *args, **kw_args)
  when Symbol
    find(*args, **kw_args)
  when Integer
    idx = args[0]
    all(:frame, minimum: idx + 1)[idx]
  else
    raise TypeError
  end
end
_switch_to_window(window = nil, **options, &window_locator) click to toggle source
# File lib/capybara/session.rb, line 928
def _switch_to_window(window = nil, **options, &window_locator)
  raise Capybara::ScopeError, 'Window cannot be switched inside a `within_frame` block' if scopes.include?(:frame)
  raise Capybara::ScopeError, 'Window cannot be switched inside a `within` block' unless scopes.last.nil?

  if window
    driver.switch_to_window(window.handle)
    window
  else
    synchronize_windows(options) do
      original_window_handle = driver.current_window_handle
      begin
        _switch_to_window_by_locator(&window_locator)
      rescue StandardError
        driver.switch_to_window(original_window_handle)
        raise
      end
    end
  end
end
_switch_to_window_by_locator() { || ... } click to toggle source
# File lib/capybara/session.rb, line 948
def _switch_to_window_by_locator
  driver.window_handles.each do |handle|
    driver.switch_to_window handle
    return Window.new(self, handle) if yield
  end
  raise Capybara::WindowError, 'Could not find a window matching block/lambda'
end
accept_modal(type, text_or_options, options, &blk) click to toggle source
# File lib/capybara/session.rb, line 859
def accept_modal(type, text_or_options, options, &blk)
  driver.accept_modal(type, **modal_options(text_or_options, **options), &blk)
end
adjust_server_port(uri) click to toggle source
# File lib/capybara/session.rb, line 908
def adjust_server_port(uri)
  uri.port ||= @server.port if @server && config.always_include_port
end
default_fn(extension) click to toggle source
# File lib/capybara/session.rb, line 886
def default_fn(extension)
  timestamp = Time.new.strftime('%Y%m%d%H%M%S')
  "capybara-#{timestamp}#{rand(10**10)}.#{extension}"
end
dismiss_modal(type, text_or_options, options, &blk) click to toggle source
# File lib/capybara/session.rb, line 863
def dismiss_modal(type, text_or_options, options, &blk)
  driver.dismiss_modal(type, **modal_options(text_or_options, **options), &blk)
end
driver_args(args) click to toggle source
# File lib/capybara/session.rb, line 855
def driver_args(args)
  args.map { |arg| arg.is_a?(Capybara::Node::Element) ? arg.base : arg }
end
element_script_result(arg) click to toggle source
# File lib/capybara/session.rb, line 895
def element_script_result(arg)
  case arg
  when Array
    arg.map { |subarg| element_script_result(subarg) }
  when Hash
    arg.transform_values! { |value| element_script_result(value) }
  when Capybara::Driver::Node
    Capybara::Node::Element.new(self, arg, nil, nil)
  else
    arg
  end
end
modal_options(text = nil, **options) click to toggle source
open_file(path) click to toggle source
# File lib/capybara/session.rb, line 873
def open_file(path)
  require 'launchy'
  Launchy.open(path)
rescue LoadError
  warn "File saved to #{path}.\nPlease install the launchy gem to open the file automatically."
end
prepare_path(path, extension) click to toggle source
# File lib/capybara/session.rb, line 880
def prepare_path(path, extension)
  File.expand_path(path || default_fn(extension), config.save_path).tap do |p_path|
    FileUtils.mkdir_p(File.dirname(p_path))
  end
end
scopes() click to toggle source
# File lib/capybara/session.rb, line 891
def scopes
  @scopes ||= [nil]
end
synchronize_windows(options, &block) click to toggle source
# File lib/capybara/session.rb, line 956
def synchronize_windows(options, &block)
  wait_time = Capybara::Queries::BaseQuery.wait(options, config.default_max_wait_time)
  document.synchronize(wait_time, errors: [Capybara::WindowError], &block)
end