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 Capybara.threadsafe == 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

Session provides a number of methods for controlling the navigation of the page, such as visit, +current_path, and so on. It also delegate 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

NODE_METHODS =
%i[
  all first attach_file text check choose
  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? resolve has_xpath? select uncheck
  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
  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 visit refresh go_back go_forward
  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 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

Raises:

  • (TypeError)


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
# File 'lib/capybara/session.rb', line 77

def initialize(mode, app = nil)
  raise TypeError, "The second parameter to Session::new should be a rack app if passed." if app && !app.respond_to?(:call)
  @@instance_created = true
  @mode = mode
  @app = app
  if block_given?
    raise "A configuration block is only accepted when Capybara.threadsafe == true" unless Capybara.threadsafe
    yield config if block_given?
  end
  @server = if config.run_server and @app and driver.needs_server?
    Capybara::Server.new(@app, config.server_port, config.server_host, config.server_errors).boot
  else
    nil
  end
  @touched = false
end

Instance Attribute Details

#appObject (readonly)

Returns the value of attribute app



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

def app
  @app
end

#modeObject (readonly)

Returns the value of attribute mode



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

def mode
  @mode
end

#serverObject (readonly)

Returns the value of attribute server



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

def server
  @server
end

#synchronizedObject

Returns the value of attribute synchronized



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

def synchronized
  @synchronized
end

Class Method Details

.instance_created?Boolean



795
796
797
# File 'lib/capybara/session.rb', line 795

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

Raises:



627
628
629
# File 'lib/capybara/session.rb', line 627

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

Raises:



637
638
639
# File 'lib/capybara/session.rb', line 637

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

Options Hash (**options):

  • :with (String)

    Response to provide to the prompt

Raises:



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

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

#configObject



799
800
801
802
803
804
805
# File 'lib/capybara/session.rb', line 799

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 Capybara.threadsafe == 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:



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

def configure
  raise "Session configuration is only supported when Capybara.threadsafe == true" unless Capybara.threadsafe
  yield config
end

#current_hostString



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

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

#current_pathString



189
190
191
192
193
194
195
196
197
198
199
200
# File 'lib/capybara/session.rb', line 189

def current_path
  # Addressable parsing is more lenient than URI
  uri = ::Addressable::URI.parse(current_url)

  # If current_url ends up being nil, won't be able to call .path on a NilClass.
  return nil if uri.nil?

  # Addressable doesn't support opaque URIs - we want nil here
  return nil if uri.scheme == "about"
  path = uri.path
  path if path && !path.empty?
end

#current_scopeObject



761
762
763
764
765
# File 'lib/capybara/session.rb', line 761

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

#current_urlString



215
216
217
# File 'lib/capybara/session.rb', line 215

def current_url
  driver.current_url
end

#current_windowCapybara::Window



435
436
437
# File 'lib/capybara/session.rb', line 435

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

Raises:



647
648
649
# File 'lib/capybara/session.rb', line 647

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

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

    Options Hash (options):

    • :wait (Numeric) — default: Capybara.default_max_wait_time

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

    Yields:

    • Block whose actions will trigger the system modal

Raises:



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

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

#documentObject



740
741
742
# File 'lib/capybara/session.rb', line 740

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

#driverObject



94
95
96
97
98
99
100
101
102
103
104
# File 'lib/capybara/session.rb', line 94

def driver
  @driver ||= begin
    unless Capybara.drivers.key?(mode)
      other_drivers = Capybara.drivers.keys.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.



601
602
603
604
605
# File 'lib/capybara/session.rb', line 601

def evaluate_async_script(script, *args)
  @touched = true
  result = driver.evaluate_async_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ? arg.base : arg })
  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.



588
589
590
591
592
# File 'lib/capybara/session.rb', line 588

def evaluate_script(script, *args)
  @touched = true
  result = driver.evaluate_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ? arg.base : arg })
  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.



574
575
576
577
# File 'lib/capybara/session.rb', line 574

def execute_script(script, *args)
  @touched = true
  driver.execute_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ? arg.base : arg })
end

#go_backObject

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



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

def go_back
  driver.go_back
end

#go_forwardObject

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



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

def go_forward
  driver.go_forward
end

#htmlString Also known as: body, source



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

def html
  driver.html
end

#inspectObject



757
758
759
# File 'lib/capybara/session.rb', line 757

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

#open_new_windowCapybara::Window

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



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

def open_new_window
  window_opened_by do
    driver.open_new_window
  end
end

#raise_server_error!Object

Raise errors encountered in the server



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
# File 'lib/capybara/session.rb', line 139

def raise_server_error!
  if @server and @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
end

#refreshObject

Refresh the page



280
281
282
283
# File 'lib/capybara/session.rb', line 280

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


124
125
126
127
128
129
130
131
# File 'lib/capybara/session.rb', line 124

def reset!
  if @touched
    driver.reset!
    @touched = false
  end
  @server.wait_for_pending_requests if @server
  raise_server_error!
end

#response_headersHash{String => String}

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



161
162
163
# File 'lib/capybara/session.rb', line 161

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 `Capybara.save_path`

and file will be given randomly generated filename. If invoked with a relative path
the path will be relative to `Capybara.save_path`


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

def save_and_open_page(path = nil)
  path = save_page(path)
  open_file(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 `Capybara.save_path`

and file will be given randomly generated filename. If invoked with a relative path
the path will be relative to `Capybara.save_path`


733
734
735
736
737
738
# File 'lib/capybara/session.rb', line 733

def save_and_open_screenshot(path = nil, **options)
  # rubocop:disable Lint/Debugger
  path = save_screenshot(path, options)
  # rubocop:enable Lint/Debugger
  open_file(path)
end

#save_page(path = nil) ⇒ String

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

pointing to `asset_host`.

If invoked without arguments it will save file to `Capybara.save_path`

and file will be given randomly generated filename. If invoked with a relative path
the path will be relative to `Capybara.save_path`


684
685
686
687
688
# File 'lib/capybara/session.rb', line 684

def save_page(path = nil)
  path = prepare_path(path, 'html')
  File.write(path, Capybara::Helpers.inject_asset_host(body, config.asset_host), mode: 'wb')
  path
end

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

Save a screenshot of page.

If invoked without arguments it will save file to `Capybara.save_path`

and file will be given randomly generated filename. If invoked with a relative path
the path will be relative to `Capybara.save_path`


716
717
718
719
720
# File 'lib/capybara/session.rb', line 716

def save_screenshot(path = nil, **options)
  path = prepare_path(path, 'png')
  driver.save_screenshot(path, options)
  path
end

#status_codeInteger

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



171
172
173
# File 'lib/capybara/session.rb', line 171

def status_code
  driver.status_code
end

#switch_to_frame(element) ⇒ Object #switch_to_frame(: parent) ⇒ Object #switch_to_frame(: top) ⇒ 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. Capybara::Session#within_frame is preferred over this method and should be used when possible. May not be supported by all drivers.

Overloads:

  • #switch_to_frame(: parent) ⇒ Object

    Switch to the parent element

  • #switch_to_frame(: top) ⇒ Object

    Switch to the top level document



386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
# File 'lib/capybara/session.rb', line 386

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)
    if idx
      if scopes.slice(idx..-1).any? { |scope| ![:frame, nil].include?(scope) }
        raise Capybara::ScopeError, "`switch_to_frame(:top)` cannot be called from inside a descendant frame's "\
                                    "`within` block."
      end
      scopes.slice!(idx..-1)
      driver.switch_to_frame(:top)
    end
  end
end

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

Returns window that has been switched to

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

    Raises:

Raises:

  • (Capybara::ScopeError)

    if this method is invoked inside `within` or `within_frame` methods

  • (ArgumentError)

    if both or neither arguments were provided



481
482
483
484
485
486
487
488
489
490
491
# File 'lib/capybara/session.rb', line 481

def switch_to_window(window = nil, **options, &window_locator)
  block_given = block_given?
  raise ArgumentError, "`switch_to_window` can take either a block or a window, not both" if window && block_given
  raise ArgumentError, "`switch_to_window`: either window or block should be provided" if !window && !block_given
  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) ⇒ Object

Yield a block using a specific wait time



771
772
773
774
775
776
777
778
779
780
781
782
783
# File 'lib/capybara/session.rb', line 771

def using_wait_time(seconds)
  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) { yield }
  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 Capybara.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.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`.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
# File 'lib/capybara/session.rb', line 245

def visit(visit_uri)
  raise_server_error!
  @touched = true

  visit_uri = ::Addressable::URI.parse(visit_uri.to_s)

  uri_base = if @server
    ::Addressable::URI.parse(config.app_host || "http://#{@server.host}:#{@server.port}")
  else
    config.app_host && ::Addressable::URI.parse(config.app_host)
  end

  if uri_base && [nil, 'http', 'https'].include?(visit_uri.scheme)
    if visit_uri.relative?
      uri_base.port ||= @server.port if @server && config.always_include_port

      visit_uri_parts = visit_uri.to_hash.delete_if { |_k, v| v.nil? }

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

      visit_uri = uri_base.merge(visit_uri_parts)
    elsif @server && config.always_include_port
      visit_uri.port ||= @server.port
    end
  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

Options Hash (**options):

  • :wait (Numeric) — default: Capybara.default_max_wait_time

    maximum wait time

Raises:

  • (Capybara::WindowError)

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



550
551
552
553
554
555
556
557
558
559
560
561
562
563
# File 'lib/capybara/session.rb', line 550

def window_opened_by(**options)
  old_handles = driver.window_handles
  yield

  wait_time = Capybara::Queries::BaseQuery.wait(options, config.default_max_wait_time)
  document.synchronize(wait_time, errors: [Capybara::WindowError]) 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

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



446
447
448
449
450
# File 'lib/capybara/session.rb', line 446

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



336
337
338
339
340
341
342
343
344
# File 'lib/capybara/session.rb', line 336

def within(*args)
  new_scope = args.first.is_a?(Capybara::Node::Base) ? args.first : find(*args)
  begin
    scopes.push(new_scope)
    yield
  ensure
    scopes.pop
  end
end

#within_fieldset(locator) ⇒ Object

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



353
354
355
356
357
# File 'lib/capybara/session.rb', line 353

def within_fieldset(locator)
  within :fieldset, locator do
    yield
  end
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.



423
424
425
426
427
428
429
430
# File 'lib/capybara/session.rb', line 423

def within_frame(*args)
  switch_to_frame(_find_frame(*args))
  begin
    yield
  ensure
    switch_to_frame(:parent)
  end
end

#within_table(locator) ⇒ Object

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



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

def within_table(locator)
  within :table, locator do
    yield
  end
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 exception will happen at second step)

Overloads:

  • #within_window(window) ⇒ Object

    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' }

    Raises:

Raises:



514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
# File 'lib/capybara/session.rb', line 514

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
    ensure
      _switch_to_window(original) unless original == window_or_proc
    end
  ensure
    scopes.pop
  end
end