Class: Capybara::Session

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `Minitest::Expectations`, `SessionMatchers`
Inherits:	Object
Defined in:	lib/capybara/session.rb, lib/capybara/minitest/spec.rb

Overview

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 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 Config::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.

Constant Summary

DOCUMENT_METHODS = Internal use only
# File 'lib/capybara/session.rb', line 58

%i[
  title assert_title assert_no_title has_title? has_no_title?
].freeze

DSL_METHODS =
# File 'lib/capybara/session.rb', line 74
```
NODE_METHODS + SESSION_METHODS + MODAL_METHODS
```

MODAL_METHODS =
# File 'lib/capybara/session.rb', line 71

%i[
  accept_alert accept_confirm dismiss_confirm accept_prompt dismiss_prompt
].freeze

NODE_METHODS =
# File 'lib/capybara/session.rb', line 41

%i[
  all first attach_file text check choose scroll_to scroll_by
  click double_click right_click
  click_link_or_button click_button click_link
  fill_in find find_all find_button find_by_id find_field find_link
  has_content? has_text? has_css? has_no_content? has_no_text?
  has_no_css? has_no_xpath? has_xpath? select uncheck
  has_element? has_no_element?
  has_link? has_no_link? has_button? has_no_button? has_field?
  has_no_field? has_checked_field? has_unchecked_field?
  has_no_table? has_table? unselect has_select? has_no_select?
  has_selector? has_no_selector? click_on has_no_checked_field?
  has_no_unchecked_field? query assert_selector assert_no_selector
  assert_all_of_selectors assert_none_of_selectors assert_any_of_selectors
  refute_selector assert_text assert_no_text
].freeze

SESSION_METHODS =
# File 'lib/capybara/session.rb', line 61

%i[
  body html source current_url current_host current_path
  execute_script evaluate_script evaluate_async_script visit refresh go_back go_forward send_keys
  within within_element within_fieldset within_table within_frame switch_to_frame
  current_window windows open_new_window switch_to_window within_window window_opened_by
  save_page save_and_open_page save_screenshot
  save_and_open_screenshot reset_session! response_headers
  status_code current_scope
  assert_current_path assert_no_current_path has_current_path? has_no_current_path?
].freeze + DOCUMENT_METHODS

Class Attribute Summary

.instance_created? ⇒ Boolean readonly

Class Method Summary

.new(mode, app = nil) ⇒ Session constructor

Instance Attribute Summary

#app readonly
#mode readonly
#server readonly
#synchronized rw

Instance Method Summary

#accept_alert(text, **options) { ... } ⇒ String

Execute the block, accepting a alert.
#accept_confirm(text, **options) { ... } ⇒ String

Execute the block, accepting a confirm.
#accept_prompt(text, **options) { ... } ⇒ String

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

Returns the element with focus.
#body

Alias for #html.
#cleanup!

Alias for #reset!.
#config
#configure {|config| ... }

Accepts a block to set the configuration options if threadsafe is true.
#current_host ⇒ String
#current_path ⇒ String
#current_scope
#current_url ⇒ String
#current_window ⇒ Capybara::Window
#dismiss_confirm(text, **options) { ... } ⇒ String

Execute the block, dismissing a confirm.
#dismiss_prompt(text, **options) { ... } ⇒ String

Execute the block, dismissing a prompt.
#document
#driver
#evaluate_async_script(script, *args) ⇒ Object

Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.
#evaluate_script(script, *args) ⇒ Object

Evaluate the given JavaScript and return the result.
#execute_script(script, *args)

Execute the given script, not returning a result.
#go_back

Move back a single entry in the browser’s history.
#go_forward

Move forward a single entry in the browser’s history.
#html ⇒ String (also: #body, #source)
#inspect
#open_new_window(kind = :tab) ⇒ Capybara::Window

Open a new window.
#quit

Disconnect from the current driver.
#raise_server_error!

Raise errors encountered in the server.
#refresh

Refresh the page.
#reset! (also: #cleanup!, #reset_session!)

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

Alias for #reset!.
#response_headers ⇒ Hash<String, String>

Returns a hash of response headers.
#save_and_open_page(path = nil)

Save a snapshot of the page and open it in a browser for inspection.
#save_and_open_screenshot(path = nil, **options)

Save a screenshot of the page and open it for inspection.
#save_page(path = nil) ⇒ String

Save a snapshot of the page.
#save_screenshot(path = nil, **options) ⇒ String

Save a screenshot of page.
#send_keys
#server_url
#source

Alias for #html.
#status_code ⇒ Integer

Returns the current HTTP status code as an integer.
#switch_to_frame(element)

Switch to the given frame.
#switch_to_window(&block) ⇒ Capybara::Window

Switch to the given window.
#using_wait_time(seconds, &block)

Yield a block using a specific maximum wait time.
#visit(visit_uri)

Navigate to the given URL.
#window_opened_by(**options, &block) ⇒ Capybara::Window

Get the window that has been opened by the passed block.
#windows ⇒ Array<Capybara::Window>

Get all opened windows.
#within(*find_args) (also: #within_element)

Executes the given block within the context of a node.
#within_element(*args, **kw_args)

Alias for #within.
#within_fieldset(locator, &block)

Execute the given block within the a specific fieldset given the id or legend of that fieldset.
#within_frame(element)

Execute the given block within the given iframe using given frame, frame name/id or index.
#within_table(locator, &block)

Execute the given block within the a specific table given the id or caption of that table.
#within_window(window) { do_something }) ⇒ Object

This method does the following:
#_find_frame(*args, **kw_args) private
#_switch_to_window(window = nil, **options, &window_locator) private
#_switch_to_window_by_locator private
#accept_modal(type, text_or_options, options, &blk) private
#adjust_server_port(uri) private
#default_fn(extension) private
#dismiss_modal(type, text_or_options, options, &blk) private
#driver_args(args) private
#element_script_result(arg) private
#modal_options(text = nil, **options) private
#open_file(path) private
#prepare_path(path, extension) private
#scopes private
#synchronize_windows(options, &block) private

`Minitest::Expectations` - Included

#must_have_all_of_selectors	See Node::Matchers#assert_all_of_selectors
#must_have_ancestor	See Node::Matchers#has_ancestor?
#must_have_any_of_selectors	See Node::Matchers#assert_any_of_selectors
#must_have_button	See Node::Matchers#has_button?
#must_have_checked_field	See Node::Matchers#has_checked_field?
#must_have_content	See Node::Matchers#has_content?
#must_have_css	See Node::Matchers#has_css?
#must_have_current_path	See SessionMatchers#has_current_path?
#must_have_element	See Node::Matchers#has_element?
#must_have_field	See Node::Matchers#has_field?
#must_have_link	See Node::Matchers#has_link?
#must_have_none_of_selectors	See Node::Matchers#assert_none_of_selectors
#must_have_select	See Node::Matchers#has_select?
#must_have_selector	See Node::Matchers#has_selector?
#must_have_sibling	See Node::Matchers#has_sibling?
#must_have_style,
#must_have_table	See Node::Matchers#has_table?
#must_have_text	See Node::Matchers#has_text?
#must_have_title	See Node::DocumentMatchers#has_title?
#must_have_unchecked_field	See Node::Matchers#has_unchecked_field?
#must_have_xpath	See Node::Matchers#has_xpath?
#must_match_style	See Node::Matchers#matches_style?
#wont_have_button	See Node::Matchers#has_no_button?
#wont_have_checked_field	See Node::Matchers#has_no_checked_field?
#wont_have_content	See Node::Matchers#has_no_content?
#wont_have_css	See Node::Matchers#has_no_css?
#wont_have_current_path	See SessionMatchers#has_no_current_path?
#wont_have_element	See Node::Matchers#has_no_element?
#wont_have_field	See Node::Matchers#has_no_field?
#wont_have_link	See Node::Matchers#has_no_link?
#wont_have_select	See Node::Matchers#has_no_select?
#wont_have_selector	See Node::Matchers#has_no_selector?
#wont_have_table	See Node::Matchers#has_no_table?
#wont_have_text	See Node::Matchers#has_no_text?
#wont_have_title	See Node::DocumentMatchers#has_no_title?
#wont_have_unchecked_field	See Node::Matchers#has_no_unchecked_field?
#wont_have_xpath	See Node::Matchers#has_no_xpath?

`SessionMatchers` - Included

#assert_current_path	Asserts that the page has the given path.
#assert_no_current_path	Asserts that the page doesn’t have the given path.
#has_current_path?	Checks if the page has the given path.
#has_no_current_path?	Checks if the page doesn’t have the given path.
#_verify_current_path, #make_predicate

Constructor Details

.new(mode, app = nil) ⇒ `Session`

[ GitHub ]

# File 'lib/capybara/session.rb', line 79


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

Class Attribute Details

.instance_created? ⇒ `Boolean` (readonly)

[ GitHub ]

# File 'lib/capybara/session.rb', line 825


def self.instance_created?
  @@instance_created
end

Instance Attribute Details

#app (readonly)

[ GitHub ]

# File 'lib/capybara/session.rb', line 76


attr_reader :mode, :app, :server

#mode (readonly)

[ GitHub ]

# File 'lib/capybara/session.rb', line 76


attr_reader :mode, :app, :server

#server (readonly)

[ GitHub ]

# File 'lib/capybara/session.rb', line 76


attr_reader :mode, :app, :server

#synchronized (rw)

[ GitHub ]

# File 'lib/capybara/session.rb', line 77


attr_accessor :synchronized

Instance Method Details

#_find_frame(*args, **kw_args) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 902


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) (private)

Raises:

(Capybara::ScopeError)

[ GitHub ]

# File 'lib/capybara/session.rb', line 918


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 (private)

Raises:

(Capybara::WindowError)

[ GitHub ]

# File 'lib/capybara/session.rb', line 938


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_alert(text, options) { ... } ⇒ `String` #accept_alert(options) { ... } ⇒ `String`

Execute the block, accepting a alert.

Expects a block whose actions will trigger the display modal to appear.

Examples:

accept_alert do
  click_link('link that triggers appearance of system modal')
end

Returns:

(String) —

the message shown in the modal

Raises:

(Capybara::ModalNotFound) —

if modal dialog hasn’t been found

[ GitHub ]

# File 'lib/capybara/session.rb', line 659


def accept_alert(text = nil, **options, &blk)
  accept_modal(:alert, text, options, &blk)
end

#accept_confirm(text, options) { ... } ⇒ `String` #accept_confirm(options) { ... } ⇒ `String`

Execute the block, accepting a confirm.

Expects a block whose actions will trigger the display modal to appear.

Examples:

accept_confirm do
  click_link('link that triggers appearance of system modal')
end

Returns:

(String) —

the message shown in the modal

Raises:

(Capybara::ModalNotFound) —

if modal dialog hasn’t been found

[ GitHub ]

# File 'lib/capybara/session.rb', line 669


def accept_confirm(text = nil, **options, &blk)
  accept_modal(:confirm, text, options, &blk)
end

#accept_modal(type, text_or_options, options, &blk) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 849


def accept_modal(type, text_or_options, options, &blk)
  driver.accept_modal(type, **modal_options(text_or_options, **options), &blk)
end

#accept_prompt(text, options) { ... } ⇒ `String` #accept_prompt(options) { ... } ⇒ `String`

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

Expects a block whose actions will trigger the display modal to appear.

Examples:

accept_prompt do
  click_link('link that triggers appearance of system modal')
end

Parameters:

options (Hash) —

a customizable set of options

Options Hash (**options):

:with (String) —

Response to provide to the prompt

Returns:

(String) —

the message shown in the modal

Raises:

(Capybara::ModalNotFound) —

if modal dialog hasn’t been found

[ GitHub ]

# File 'lib/capybara/session.rb', line 690


def accept_prompt(text = nil, **options, &blk)
  accept_modal(:prompt, text, options, &blk)
end

#active_element

Returns the element with focus.

Not supported by Rack Test

[ GitHub ]

# File 'lib/capybara/session.rb', line 323


def active_element
  Capybara::Queries::ActiveElementQuery.new.resolve_for(self)[0].tap(&:allow_reload!)
end

#adjust_server_port(uri) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 898


def adjust_server_port(uri)
  uri.port ||= @server.port if @server && config.always_include_port
end

#body

Alias for #html.

[ GitHub ]

# File 'lib/capybara/session.rb', line 200


alias_method :body, :html

#cleanup!

Alias for #reset!.

[ GitHub ]

# File 'lib/capybara/session.rb', line 140


alias_method :cleanup!, :reset!

#config

[ GitHub ]

# File 'lib/capybara/session.rb', line 829


def config
  @config ||= if Capybara.threadsafe
    Capybara.session_options.dup
  else
    Capybara::ReadOnlySessionConfig.new(Capybara.session_options)
  end
end

#configure {|config| ... }

Accepts a block to set the configuration options if 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.

Yields:

(config)

[ GitHub ]

# File 'lib/capybara/session.rb', line 819


def configure
  raise 'Session configuration is only supported when Capybara.threadsafe == true' unless Capybara.threadsafe

  yield config
end

#current_host ⇒ `String`

Returns:

(String) —

Host of the current page

[ GitHub ]

# File 'lib/capybara/session.rb', line 222


def current_host
  uri = URI.parse(current_url)
  "#{uri.scheme}://#{uri.host}" if uri.host
end

#current_path ⇒ `String`

Returns:

(String) —

Path of the current page, without any domain information

[ GitHub ]

# File 'lib/capybara/session.rb', line 207


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

[ GitHub ]

# File 'lib/capybara/session.rb', line 791


def current_scope
  scope = scopes.last
  [nil, :frame].include?(scope) ? document : scope
end

#current_url ⇒ `String`

Returns:

(String) —

Fully qualified URL of the current page

[ GitHub ]

# File 'lib/capybara/session.rb', line 231


def current_url
  driver.current_url
end

#current_window ⇒ Capybara::Window

Returns:

(Capybara::Window) —

current window

[ GitHub ]

# File 'lib/capybara/session.rb', line 460


def current_window
  Window.new(self, driver.current_window_handle)
end

#default_fn(extension) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 876


def default_fn(extension)
  timestamp = Time.new.strftime('%Y%m%d%H%M%S')
  "capybara-#{timestamp}#{rand(10**10)}.#{extension}"
end

#dismiss_confirm(text, options) { ... } ⇒ `String` #dismiss_confirm(options) { ... } ⇒ `String`

Execute the block, dismissing a confirm.

Expects a block whose actions will trigger the display modal to appear.

Examples:

dismiss_confirm do
  click_link('link that triggers appearance of system modal')
end

Returns:

(String) —

the message shown in the modal

Raises:

(Capybara::ModalNotFound) —

if modal dialog hasn’t been found

[ GitHub ]

# File 'lib/capybara/session.rb', line 679


def dismiss_confirm(text = nil, **options, &blk)
  dismiss_modal(:confirm, text, options, &blk)
end

#dismiss_modal(type, text_or_options, options, &blk) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 853


def dismiss_modal(type, text_or_options, options, &blk)
  driver.dismiss_modal(type, **modal_options(text_or_options, **options), &blk)
end

#dismiss_prompt(text, options) { ... } ⇒ `String` #dismiss_prompt(options) { ... } ⇒ `String`

Execute the block, dismissing a prompt.

Expects a block whose actions will trigger the display modal to appear.

Examples:

dismiss_prompt do
  click_link('link that triggers appearance of system modal')
end

Returns:

(String) —

the message shown in the modal

Raises:

(Capybara::ModalNotFound) —

if modal dialog hasn’t been found

[ GitHub ]

# File 'lib/capybara/session.rb', line 700


def dismiss_prompt(text = nil, **options, &blk)
  dismiss_modal(:prompt, text, options, &blk)
end

#document

[ GitHub ]

# File 'lib/capybara/session.rb', line 766


def document
  @document ||= Capybara::Node::Document.new(self, driver)
end

#driver

[ GitHub ]

# File 'lib/capybara/session.rb', line 100


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

#driver_args(args) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 845


def driver_args(args)
  args.map { |arg| arg.is_a?(Capybara::Node::Element) ? arg.base : arg }
end

#element_script_result(arg) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 885


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

#evaluate_async_script(script, *args) ⇒ `Object`

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

Parameters:

script (String) —

A string of JavaScript to evaluate
args —

Optional arguments that will be passed to the script

Returns:

(Object) —

The result of the evaluated JavaScript (may be driver specific)

[ GitHub ]

# File 'lib/capybara/session.rb', line 633


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

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.

Parameters:

script (String) —

A string of JavaScript to evaluate
args —

Optional arguments that will be passed to the script

Returns:

(Object) —

The result of the evaluated JavaScript (may be driver specific)

[ GitHub ]

# File 'lib/capybara/session.rb', line 619


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)

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.

Parameters:

script (String) —

A string of JavaScript to execute
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

[ GitHub ]

# File 'lib/capybara/session.rb', line 604


def execute_script(script, *args)
  @touched = true
  driver.execute_script(script, *driver_args(args))
end

#go_back

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

[ GitHub ]

# File 'lib/capybara/session.rb', line 297


def go_back
  driver.go_back
end

#go_forward

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

[ GitHub ]

# File 'lib/capybara/session.rb', line 305


def go_forward
  driver.go_forward
end

#html ⇒ `String` Also known as: #body, #source

Returns:

(String) —

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

[ GitHub ]

# File 'lib/capybara/session.rb', line 197


def html
  driver.html || ''
end

#inspect

[ GitHub ]

# File 'lib/capybara/session.rb', line 787


def inspect
  %(#<Capybara::Session>)
end

#modal_options(text = nil, **options) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 857


def modal_options(text = nil, **options)
  options[:text] ||= text unless text.nil?
  options[:wait] ||= config.default_max_wait_time
  options
end

#open_file(path) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 863


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

#open_new_window(kind = :tab) ⇒ Capybara::Window

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

Returns:

(Capybara::Window) —

window that has been opened

[ GitHub ]

# File 'lib/capybara/session.rb', line 484


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

#prepare_path(path, extension) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 870


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

#quit

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

[ GitHub ]

# File 'lib/capybara/session.rb', line 147


def quit
  @driver.quit if @driver.respond_to? :quit
  @document = @driver = nil
  @touched = false
  @server&.reset_error!
end

#raise_server_error!

Raise errors encountered in the server.

[ GitHub ]

# File 'lib/capybara/session.rb', line 158


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 => capy_error # rubocop:disable Naming/RescuedExceptionsVariableName
    raise @server.error, cause: capy_error
  ensure
    @server.reset_error!
  end
end

#refresh

Refresh the page.

[ GitHub ]

# File 'lib/capybara/session.rb', line 288


def refresh
  raise_server_error!
  driver.refresh
end

#reset! Also known as: #cleanup!, #reset_session!

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

[ GitHub ]

# File 'lib/capybara/session.rb', line 130


def reset!
  if @touched
    driver.reset!
    @touched = false
    switch_to_frame(:top) rescue nil # rubocop:disable Style/RescueModifier
    @scopes = [nil]
  end
  @server&.wait_for_pending_requests
  raise_server_error!
end

#reset_session!

Alias for #reset!.

[ GitHub ]

# File 'lib/capybara/session.rb', line 141


alias_method :reset_session!, :reset!

#response_headers ⇒ `Hash`<`String`, `String`>

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

Returns:

(Hash<String, String>) —

A hash of response headers.

[ GitHub ]

# File 'lib/capybara/session.rb', line 179


def response_headers
  driver.response_headers
end

#save_and_open_page(path = nil)

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

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

Parameters:

path (String) (defaults to: nil) —

the path to where it should be saved

[ GitHub ]

# File 'lib/capybara/session.rb', line 732


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)

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

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

Parameters:

path (String) (defaults to: nil) —

the path to where it should be saved
options (Hash) —

a customizable set of options

[ GitHub ]

# File 'lib/capybara/session.rb', line 762


def save_and_open_screenshot(path = nil, **options)
  save_screenshot(path, **options).tap { |s_path| open_file(s_path) }
end

#save_page(path = nil) ⇒ `String`

Save a snapshot of the page. If asset_host is set it will inject base tag pointing to asset_host.

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

Parameters:

path (String) (defaults to: nil) —

the path to where it should be saved

Returns:

(String) —

the path to which the file was saved

[ GitHub ]

# File 'lib/capybara/session.rb', line 716


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) ⇒ `String`

Save a screenshot of page.

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

Parameters:

path (String) (defaults to: nil) —

the path to where it should be saved
options (Hash) —

a customizable set of options

Returns:

(String) —

the path to which the file was saved

[ GitHub ]

# File 'lib/capybara/session.rb', line 747


def save_screenshot(path = nil, **options)
  prepare_path(path, 'png').tap { |p_path| driver.save_screenshot(p_path, **options) }
end

#scopes (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 881


def scopes
  @scopes ||= [nil]
end

#send_keys

[ GitHub ]

# File 'lib/capybara/session.rb', line 313


def send_keys(...)
  driver.send_keys(...)
end

#server_url

[ GitHub ]

# File 'lib/capybara/session.rb', line 837


def server_url
  @server&.base_url
end

#source

Alias for #html.

[ GitHub ]

# File 'lib/capybara/session.rb', line 201


alias_method :source, :html

#status_code ⇒ `Integer`

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

Returns:

(Integer) —

Current HTTP status code

[ GitHub ]

# File 'lib/capybara/session.rb', line 189


def status_code
  driver.status_code
end

#switch_to_frame(element) #switch_to_frame(location)

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.

[ GitHub ]

# File 'lib/capybara/session.rb', line 408


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(&block) ⇒ Capybara::Window #switch_to_window(window) ⇒ Capybara::Window

Switch to the given window.

Returns:

(Capybara::Window) —

window that has been switched to

Raises:

(Capybara::ScopeError) —

if this method is invoked inside #within or #within_frame methods
(ArgumentError) —

if both or neither arguments were provided

[ GitHub ]

# File 'lib/capybara/session.rb', line 512


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

#synchronize_windows(options, &block) (private)

[ GitHub ]

# File 'lib/capybara/session.rb', line 946


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

#using_wait_time(seconds, &block)

Yield a block using a specific maximum wait time.

[ GitHub ]

# File 'lib/capybara/session.rb', line 800


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)

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 app_host will make the remote server the default. For example:

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

If 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 http://google.com:4567/test.

Parameters:

visit_uri (#to_s) —

The URL to navigate to. The parameter will be cast to a String.

[ GitHub ]

# File 'lib/capybara/session.rb', line 261


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, &block) ⇒ Capybara::Window

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 as order of windows isn’t defined in some drivers.

[ GitHub ]

# File 'lib/capybara/session.rb', line 581


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 ⇒ `Array`<Capybara::Window>

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.

Returns:

(Array<Capybara::Window>) —

an array of all windows

[ GitHub ]

# File 'lib/capybara/session.rb', line 471


def windows
  driver.window_handles.map do |handle|
    Window.new(self, handle)
  end
end

#within(*find_args) #within(a_node)
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')

Raises:

(Capybara::ElementNotFound) —

If the scope can’t be found before time expires

[ GitHub ]

# 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

#within_element(*args, **kw_args)

Alias for #within.

[ GitHub ]

# File 'lib/capybara/session.rb', line 371


alias_method :within_element, :within

#within_fieldset(locator, &block)

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

Parameters:

locator (String) —

Id or legend of the fieldset

[ GitHub ]

# File 'lib/capybara/session.rb', line 379


def within_fieldset(locator, &block)
  within(:fieldset, locator, &block)
end

#within_frame(element) #within_frame([kind = :frame], locator, options) #within_frame**(index)

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

[ GitHub ]

# File 'lib/capybara/session.rb', line 448


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)

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

Parameters:

locator (String) —

Id or caption of the table

[ GitHub ]

# File 'lib/capybara/session.rb', line 389


def within_table(locator, &block)
  within(:table, locator, &block)
end

#within_window(window) { do_something }) ⇒ `Object` #within_window(proc_or_lambda) { do_something }) ⇒ `Object`

This method does the following:

Switches to the given window (it can be located by window instance/lambda/string).
Executes the given block (within window located at previous step).
Switches back (this step will be invoked even if an exception occurs at the second step).

Returns:

value returned by the block

Raises:

(Capybara::ScopeError) —

if this method is invoked inside #within_frame method

[ GitHub ]

# File 'lib/capybara/session.rb', line 545


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

Class: Capybara::Session

Overview

Constant Summary

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Minitest::Expectations - Included

SessionMatchers - Included

Constructor Details

.new(mode, app = nil) ⇒ Session

Class Attribute Details

.instance_created? ⇒ Boolean (readonly)

Instance Attribute Details

#app (readonly)

#mode (readonly)

#server (readonly)

#synchronized (rw)

Instance Method Details

#_find_frame(*args, **kw_args) (private)

#_switch_to_window(window = nil, **options, &window_locator) (private)

#_switch_to_window_by_locator (private)

#accept_alert(text, **options) { ... } ⇒ String #accept_alert(**options) { ... } ⇒ String

#accept_confirm(text, **options) { ... } ⇒ String #accept_confirm(**options) { ... } ⇒ String

#accept_modal(type, text_or_options, options, &blk) (private)

#accept_prompt(text, **options) { ... } ⇒ String #accept_prompt(**options) { ... } ⇒ String

#active_element

#adjust_server_port(uri) (private)

#body

#cleanup!

#config

#configure {|config| ... }

#current_host ⇒ String

#current_path ⇒ String

#current_scope

#current_url ⇒ String

#current_window ⇒ Capybara::Window

#default_fn(extension) (private)

#dismiss_confirm(text, **options) { ... } ⇒ String #dismiss_confirm(**options) { ... } ⇒ String

#dismiss_modal(type, text_or_options, options, &blk) (private)

#dismiss_prompt(text, **options) { ... } ⇒ String #dismiss_prompt(**options) { ... } ⇒ String

#document

#driver

#driver_args(args) (private)

#element_script_result(arg) (private)

#evaluate_async_script(script, *args) ⇒ Object

#evaluate_script(script, *args) ⇒ Object

#execute_script(script, *args)

#go_back

#go_forward

#html ⇒ String Also known as: #body, #source

#inspect

#modal_options(text = nil, **options) (private)

#open_file(path) (private)

#open_new_window(kind = :tab) ⇒ Capybara::Window

#prepare_path(path, extension) (private)

#quit

#raise_server_error!

#refresh

#reset! Also known as: #cleanup!, #reset_session!

#reset_session!

#response_headers ⇒ Hash<String, String>

#save_and_open_page(path = nil)

#save_and_open_screenshot(path = nil, **options)

#save_page(path = nil) ⇒ String

#save_screenshot(path = nil, **options) ⇒ String

#scopes (private)

#send_keys

#server_url

#source

#status_code ⇒ Integer

#switch_to_frame(element) #switch_to_frame(location)

#switch_to_window(&block) ⇒ Capybara::Window #switch_to_window(window) ⇒ Capybara::Window

#synchronize_windows(options, &block) (private)

#using_wait_time(seconds, &block)

#visit(visit_uri)

#window_opened_by(**options, &block) ⇒ Capybara::Window

#windows ⇒ Array<Capybara::Window>

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

#within_element(*args, **kw_args)

`Minitest::Expectations` - Included

`SessionMatchers` - Included

.new(mode, app = nil) ⇒ `Session`

.instance_created? ⇒ `Boolean` (readonly)

#accept_alert(text, options) { ... } ⇒ `String` #accept_alert(options) { ... } ⇒ `String`

#accept_confirm(text, options) { ... } ⇒ `String` #accept_confirm(options) { ... } ⇒ `String`

#accept_prompt(text, options) { ... } ⇒ `String` #accept_prompt(options) { ... } ⇒ `String`

#current_host ⇒ `String`

#current_path ⇒ `String`

#current_url ⇒ `String`

#dismiss_confirm(text, options) { ... } ⇒ `String` #dismiss_confirm(options) { ... } ⇒ `String`

#dismiss_prompt(text, options) { ... } ⇒ `String` #dismiss_prompt(options) { ... } ⇒ `String`

#evaluate_async_script(script, *args) ⇒ `Object`

#evaluate_script(script, *args) ⇒ `Object`

#html ⇒ `String` Also known as: #body, #source

#response_headers ⇒ `Hash`<`String`, `String`>

#save_page(path = nil) ⇒ `String`

#save_screenshot(path = nil, **options) ⇒ `String`

#status_code ⇒ `Integer`

#windows ⇒ `Array`<Capybara::Window>

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

#within_frame(element) #within_frame([kind = :frame], locator, options) #within_frame**(index)

#within_window(window) { do_something }) ⇒ `Object` #within_window(proc_or_lambda) { do_something }) ⇒ `Object`