Class: Capybara::Session

Inherits:
Object
  • Object
show all
Includes:
Minitest::Expectations, SessionMatchers
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 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 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 collapse

NODE_METHODS = 
%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
DOCUMENT_METHODS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

%i[
  title assert_title assert_no_title has_title? has_no_title?
].freeze
SESSION_METHODS = 
%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
%i[
  accept_alert accept_confirm dismiss_confirm accept_prompt dismiss_prompt
].freeze
DSL_METHODS = 
NODE_METHODS + SESSION_METHODS + MODAL_METHODS

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Minitest::Expectations

#must_have_all_of_selectors, #must_have_ancestor, #must_have_any_of_selectors, #must_have_button, #must_have_checked_field, #must_have_content, #must_have_css, #must_have_current_path, #must_have_element, #must_have_field, #must_have_link, #must_have_none_of_selectors, #must_have_select, #must_have_selector, #must_have_sibling, #must_have_style, #must_have_table, #must_have_text, #must_have_title, #must_have_unchecked_field, #must_have_xpath, #must_match_style, #wont_have_button, #wont_have_checked_field, #wont_have_content, #wont_have_css, #wont_have_current_path, #wont_have_element, #wont_have_field, #wont_have_link, #wont_have_select, #wont_have_selector, #wont_have_table, #wont_have_text, #wont_have_title, #wont_have_unchecked_field, #wont_have_xpath

Methods included from SessionMatchers

#assert_current_path, #assert_no_current_path, #has_current_path?, #has_no_current_path?

Constructor Details

#initialize(mode, app = nil) ⇒ Session

Returns a new instance of Session.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# 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

Instance Attribute Details

#app ⇒ Object (readonly)

Returns the value of attribute app.



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

def app
  @app
end

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



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

def mode
  @mode
end

#server ⇒ Object (readonly)

Returns the value of attribute server.



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

def server
  @server
end

#synchronized ⇒ Object

Returns the value of attribute synchronized.



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

def synchronized
  @synchronized
end

Class Method Details

.instance_created? ⇒ Boolean

Returns:

  • (Boolean) 


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

def self.instance_created?
  @@instance_created
end

Instance Method Details

#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

Overloads:

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

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched.

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

  • #accept_alert(**options) { ... } ⇒ String

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

Returns:

  • (String) —

    the message shown in the modal

Raises:



659
660
661
 
# 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

Overloads:

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

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched.

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

  • #accept_confirm(**options) { ... } ⇒ String

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

Returns:

  • (String) —

    the message shown in the modal

Raises:



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

def accept_confirm(text = nil, **options, &blk)
  accept_modal(:confirm, text, 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

Overloads:

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

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched.

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

  • #accept_prompt(**options) { ... } ⇒ String

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

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:



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

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

#active_element ⇒ Object

Returns the element with focus.

Not supported by Rack Test



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

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

#config ⇒ Object 



829
830
831
832
833
834
835
 
# 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| ... } ⇒ Object

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:



819
820
821
822
823
 
# 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 Host of the current page.

Returns:

  • (String) —

    Host of the current page



222
223
224
225
 
# 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 Path of the current page, without any domain information.

Returns:

  • (String) —

    Path of the current page, without any domain information



207
208
209
210
211
212
213
214
215
216
 
# 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 ⇒ Object 



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

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

#current_url ⇒ String

Returns Fully qualified URL of the current page.

Returns:

  • (String) —

    Fully qualified URL of the current page



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

def current_url
  driver.current_url
end

#current_window ⇒ Capybara::Window

Returns current window.

Returns:



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

def current_window
  Window.new(self, driver.current_window_handle)
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

Overloads:

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

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched.

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

  • #dismiss_confirm(**options) { ... } ⇒ String

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

Returns:

  • (String) —

    the message shown in the modal

Raises:



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

def dismiss_confirm(text = nil, **options, &blk)
  dismiss_modal(:confirm, text, 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

Overloads:

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

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched.

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

  • #dismiss_prompt(**options) { ... } ⇒ String

    Options Hash (**options):

    • :wait (Numeric) —

      Maximum time to wait for the modal to appear after executing the block. Defaults to default_max_wait_time.

    Yields:

    • Block whose actions will trigger the system modal

Returns:

  • (String) —

    the message shown in the modal

Raises:



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

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

#document ⇒ Object 



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

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

#driver ⇒ Object 



100
101
102
103
104
105
106
107
108
109
110
 
# 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

#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)



633
634
635
636
637
 
# 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)



619
620
621
622
623
 
# 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) ⇒ Object

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



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

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

#go_back ⇒ Object

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



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

def go_back
  driver.go_back
end

#go_forward ⇒ Object

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



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

def go_forward
  driver.go_forward
end

#html ⇒ String Also known as: body, source

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

Returns:

  • (String) —

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



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

def html
  driver.html || ''
end

#inspect ⇒ Object 



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

def inspect
  %(#<Capybara::Session>)
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:



484
485
486
487
488
489
490
491
492
 
# 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

#quit ⇒ Object

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



147
148
149
150
151
152
 
# 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! ⇒ Object

Raise errors encountered in the server.



158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# 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 ⇒ Object

Refresh the page.



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

def refresh
  raise_server_error!
  driver.refresh
end

#reset! ⇒ Object 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


130
131
132
133
134
135
136
137
138
139
 
# 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

#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.



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

def response_headers
  driver.response_headers
end

#save_and_open_page(path = nil) ⇒ Object

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



732
733
734
 
# 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) ⇒ Object

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



762
763
764
 
# 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



716
717
718
719
720
 
# 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



747
748
749
 
# 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

#send_keys ⇒ Object 



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

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

#server_url ⇒ Object 



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

def server_url
  @server&.base_url
end

#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



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

def status_code
  driver.status_code
end

#switch_to_frame(element) ⇒ Object #switch_to_frame(location) ⇒ Object

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.

Overloads:

  • #switch_to_frame(element) ⇒ Object

    Parameters:

  • #switch_to_frame(location) ⇒ Object

    Parameters:

    • location (Symbol) —

      relative location of the frame to switch to

      • :parent - the parent frame
      • :top - the top level document


408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# 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.

Overloads:

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

    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 WindowError will be raised.

    Examples:

    window = switch_to_window { title == 'Page title' }

    Raises:

  • #switch_to_window(window) ⇒ Capybara::Window

    Parameters:

    Raises:

Returns:

Raises:



512
513
514
515
516
517
518
519
520
521
522
 
# 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

#using_wait_time(seconds, &block) ⇒ Object

Yield a block using a specific maximum wait time.



800
801
802
803
804
805
806
807
808
809
810
811
812
 
# 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) ⇒ Object

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.



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# 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.

Returns the window that has been opened within a block.

Parameters:

  • options (Hash)

Options Hash (**options):

Returns:

Raises:

  • (Capybara::WindowError) —

    if block passed to window hasn't opened window or opened more than one window



581
582
583
584
585
586
587
588
589
590
591
592
593
 
# 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:



471
472
473
474
475
 
# File 'lib/capybara/session.rb', line 471

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

#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

#within_fieldset(locator, &block) ⇒ Object

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



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

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

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

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

Overloads:

  • #within_frame(element) ⇒ Object

    Parameters:

  • #within_frame([kind = :frame], locator, **options) ⇒ Object

    Parameters:

    • kind (Symbol) —

      Optional selector type (:frame, :css, :xpath, etc.) - Defaults to :frame

    • locator (String) —

      The locator for the given selector kind. For :frame this is the name/id of a frame/iframe element

  • #within_frame(index) ⇒ Object

    Parameters:

    • index (Integer) —

      index of a frame (0 based)



448
449
450
451
452
453
454
455
 
# 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) ⇒ Object

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



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

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

#within_window(window) ⇒ Object #within_window(proc_or_lambda) ⇒ Object

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).

Overloads:

  • #within_window(window) ⇒ Object

    Parameters:

    Raises:

    • (driver#no_such_window_error) —

      if nonexistent (e.g. closed) window was passed

  • #within_window(proc_or_lambda) ⇒ Object

    Examples:

    within_window(->{ page.title == 'Page title' }) { click_button 'Submit' }

    Parameters:

    • lambda (Proc) —

      First window for which lambda returns a value other than false or nil will be switched to.

    Raises:

Returns:

  • value returned by the block

Raises:



545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
 
# 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