Class: Capybara::Session

Inherits:
Object
  • Object
show all
Includes:
SessionMatchers
Defined in:
lib/capybara/session.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')

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 =
[
  :all, :first, :attach_file, :text, :check, :choose,
  :click_link_or_button, :click_button, :click_link, :field_labeled,
  :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
]
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.

[
  :title, :assert_title, :assert_no_title, :has_title?, :has_no_title?
]
SESSION_METHODS =
[
  :body, :html, :source, :current_url, :current_host, :current_path,
  :execute_script, :evaluate_script, :visit, :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?
] + DOCUMENT_METHODS
[
  :accept_alert, :accept_confirm, :dismiss_confirm, :accept_prompt,
  :dismiss_prompt
]
DSL_METHODS =
NODE_METHODS + SESSION_METHODS + MODAL_METHODS

Instance Attribute 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)


70
71
72
73
74
75
76
77
78
79
80
# File 'lib/capybara/session.rb', line 70

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)
  @mode = mode
  @app = app
  if Capybara.run_server and @app and driver.needs_server?
    @server = Capybara::Server.new(@app).boot
  else
    @server = nil
  end
  @touched = false
end

Instance Attribute Details

#appObject (readonly)

Returns the value of attribute app



67
68
69
# File 'lib/capybara/session.rb', line 67

def app
  @app
end

#modeObject (readonly)

Returns the value of attribute mode



67
68
69
# File 'lib/capybara/session.rb', line 67

def mode
  @mode
end

#serverObject (readonly)

Returns the value of attribute server



67
68
69
# File 'lib/capybara/session.rb', line 67

def server
  @server
end

#synchronizedObject

Returns the value of attribute synchronized



68
69
70
# File 'lib/capybara/session.rb', line 68

def synchronized
  @synchronized
end

Instance Method Details

#accept_alert(text, options = {}, &blk) ⇒ String #accept_alert(options = {}, &blk) ⇒ String

Execute the block, accepting a alert.

Overloads:

  • #accept_alert(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp)

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

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

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

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

Returns:

  • (String)

    the message shown in the modal

Raises:



643
644
645
# File 'lib/capybara/session.rb', line 643

def accept_alert(text_or_options=nil, options={}, &blk)
  accept_modal(:alert, text_or_options, options, &blk)
end

#accept_confirm(text, options = {}, &blk) ⇒ String #accept_confirm(options = {}, &blk) ⇒ String

Execute the block, accepting a confirm.

Overloads:

  • #accept_confirm(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp)

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

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

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

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

Returns:

  • (String)

    the message shown in the modal

Raises:



653
654
655
# File 'lib/capybara/session.rb', line 653

def accept_confirm(text_or_options=nil, options={}, &blk)
  accept_modal(:confirm, text_or_options, options, &blk)
end

#accept_prompt(text, options = {}, &blk) ⇒ String #accept_prompt(options = {}, &blk) ⇒ String

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

Overloads:

  • #accept_prompt(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp)

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

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

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

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

  • :with (String)

    Response to provide to the prompt

Returns:

  • (String)

    the message shown in the modal

Raises:



674
675
676
# File 'lib/capybara/session.rb', line 674

def accept_prompt(text_or_options=nil, options={}, &blk)
  accept_modal(:prompt, text_or_options, options, &blk)
end

#current_hostString

Returns Host of the current page

Returns:

  • (String)

    Host of the current page



192
193
194
195
# File 'lib/capybara/session.rb', line 192

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

#current_pathString

Returns Path of the current page, without any domain information

Returns:

  • (String)

    Path of the current page, without any domain information



175
176
177
178
179
180
181
182
183
184
185
186
# File 'lib/capybara/session.rb', line 175

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 and not path.empty?
end

#current_scopeObject



783
784
785
786
787
# File 'lib/capybara/session.rb', line 783

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

#current_urlString

Returns Fully qualified URL of the current page

Returns:

  • (String)

    Fully qualified URL of the current page



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

def current_url
  driver.current_url
end

#current_windowCapybara::Window

Returns current window

Returns:



421
422
423
# File 'lib/capybara/session.rb', line 421

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

#dismiss_confirm(text, options = {}, &blk) ⇒ String #dismiss_confirm(options = {}, &blk) ⇒ String

Execute the block, dismissing a confirm.

Overloads:

  • #dismiss_confirm(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp)

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

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

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

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

Returns:

  • (String)

    the message shown in the modal

Raises:



663
664
665
# File 'lib/capybara/session.rb', line 663

def dismiss_confirm(text_or_options=nil, options={}, &blk)
  dismiss_modal(:confirm, text_or_options, options, &blk)
end

#dismiss_prompt(text, options = {}, &blk) ⇒ String #dismiss_prompt(options = {}, &blk) ⇒ String

Execute the block, dismissing a prompt.

Overloads:

  • #dismiss_prompt(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp)

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

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

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

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

Returns:

  • (String)

    the message shown in the modal

Raises:



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

def dismiss_prompt(text_or_options=nil, options={}, &blk)
  dismiss_modal(:prompt, text_or_options, options, &blk)
end

#documentObject



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

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

#driverObject



82
83
84
85
86
87
88
89
90
# File 'lib/capybara/session.rb', line 82

def driver
  @driver ||= begin
    unless Capybara.drivers.has_key?(mode)
      other_drivers = Capybara.drivers.keys.map { |key| key.inspect }
      raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}"
    end
    Capybara.drivers[mode].call(app)
  end
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

Returns:

  • (Object)

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



620
621
622
623
624
625
626
627
628
629
# File 'lib/capybara/session.rb', line 620

def evaluate_script(script, *args)
  @touched = true
  result = if args.empty?
    driver.evaluate_script(script)
  else
    raise Capybara::NotSupportedByDriverError, "The current driver does not support evaluate_script arguments" if driver.method(:evaluate_script).arity == 1
    driver.evaluate_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ?  arg.base : arg} )
  end
  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



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

def execute_script(script, *args)
  @touched = true
  if args.empty?
    driver.execute_script(script)
  else
    raise Capybara::NotSupportedByDriverError, "The current driver does not support execute_script arguments" if driver.method(:execute_script).arity == 1
    driver.execute_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ?  arg.base : arg} )
  end
end

#go_backObject

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



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

def go_back
  driver.go_back
end

#go_forwardObject

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



269
270
271
# File 'lib/capybara/session.rb', line 269

def go_forward
  driver.go_forward
end

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



165
166
167
# File 'lib/capybara/session.rb', line 165

def html
  driver.html
end

#inspectObject



779
780
781
# File 'lib/capybara/session.rb', line 779

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.

Returns:



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

def open_new_window
  window_opened_by do
    driver.open_new_window
  end
end

#raise_server_error!Object

Raise errors encountered in the server



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
# File 'lib/capybara/session.rb', line 125

def raise_server_error!
  if @server and @server.error
    # Force an explanation for the error being raised as the exception cause
    begin
      if Capybara.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

#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


110
111
112
113
114
115
116
117
# File 'lib/capybara/session.rb', line 110

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)

Returns:

  • (Hash{String => String})

    A hash of response headers.



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

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`, which is different from
the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
relative to Dir.pwd

Parameters:

  • path (String) (defaults to: nil)

    the path to where it should be saved



720
721
722
723
# File 'lib/capybara/session.rb', line 720

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`, which is different from
the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
relative to Dir.pwd

Parameters:

  • path (String) (defaults to: nil)

    the path to where it should be saved

  • options (Hash) (defaults to: {})

    a customizable set of options



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

def save_and_open_screenshot(path = nil, options = {})
  path = save_screenshot(path, options)
  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`, which is different from
the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
relative to Dir.pwd

Parameters:

  • path (String) (defaults to: nil)

    the path to where it should be saved

Returns:

  • (String)

    the path to which the file was saved



702
703
704
705
706
# File 'lib/capybara/session.rb', line 702

def save_page(path = nil)
  path = prepare_path(path, 'html')
  File.write(path, Capybara::Helpers.inject_asset_host(body), 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`, which is different from
the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
relative to Dir.pwd

Parameters:

  • path (String) (defaults to: nil)

    the path to where it should be saved

  • options (Hash) (defaults to: {})

    a customizable set of options

Returns:

  • (String)

    the path to which the file was saved



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

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)

Returns:

  • (Integer)

    Current HTTP status code



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

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(element) ⇒ Object

    Parameters:

  • #switch_to_frame(: parent) ⇒ Object

    Switch to the parent element

  • #switch_to_frame(: top) ⇒ Object

    Switch to the top level document



358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
# File 'lib/capybara/session.rb', line 358

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

    Parameters:

    Raises:

Returns:

Raises:

  • (Capybara::ScopeError)

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

  • (ArgumentError)

    if both or neither arguments were provided



467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
# File 'lib/capybara/session.rb', line 467

def switch_to_window(window = nil, options= {})
  options, window = window, nil if window.is_a? Hash

  block_given = block_given?
  if window && block_given
    raise ArgumentError, "`switch_to_window` can take either a block or a window, not both"
  elsif !window && !block_given
    raise ArgumentError, "`switch_to_window`: either window or block should be provided"
  elsif scopes.size > 1
    raise Capybara::ScopeError, "`switch_to_window` is not supposed to be invoked from "\
                                "`within`'s, `within_frame`'s' or `within_window`'s' block."
  end

  if window
    driver.switch_to_window(window.handle)
    window
  else
    wait_time = Capybara::Queries::BaseQuery.wait(options)
    document.synchronize(wait_time, errors: [Capybara::WindowError]) do
      original_window_handle = driver.current_window_handle
      begin
        driver.window_handles.each do |handle|
          driver.switch_to_window handle
          if yield
            return Window.new(self, handle)
          end
        end
      rescue => e
        driver.switch_to_window(original_window_handle)
        raise e
      else
        driver.switch_to_window(original_window_handle)
        raise Capybara::WindowError, "Could not find a window matching block/lambda"
      end
    end
  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`.

Parameters:

  • visit_uri (#to_s)

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



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
# File 'lib/capybara/session.rb', line 231

def visit(visit_uri)
  raise_server_error!
  @touched = true

  visit_uri = URI.parse(visit_uri.to_s)

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

  # TODO - this is only for compatability with previous 2.x behavior that concatenated
  # Capybara.app_host and a "relative" path - Consider removing in 3.0
  # @abotalov brought up a good point about this behavior potentially being useful to people
  # deploying to a subdirectory and/or single page apps where only the url fragment changes
  if visit_uri.scheme.nil? && uri_base
    visit_uri.path = uri_base.path + visit_uri.path
  end

  visit_uri = uri_base.merge(visit_uri) unless uri_base.nil?

  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

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

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

    maximum wait time

Returns:

Raises:

  • (Capybara::WindowError)

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



577
578
579
580
581
582
583
584
585
586
587
588
589
590
# File 'lib/capybara/session.rb', line 577

def window_opened_by(options = {}, &block)
  old_handles = driver.window_handles
  block.call

  wait_time = Capybara::Queries::BaseQuery.wait(options)
  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.

Returns:



432
433
434
435
436
# File 'lib/capybara/session.rb', line 432

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

Overloads:

  • #within(*find_args) ⇒ Object

    Parameters:

    • kind (Symbol)

      Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector

    • locator (String)

      The selector

    • options (Hash)

      a customizable set of options

  • #within(a_node) ⇒ Object

    Parameters:

Raises:



308
309
310
311
312
313
314
315
316
# File 'lib/capybara/session.rb', line 308

def within(*args)
  new_scope = if args.first.is_a?(Capybara::Node::Base) then args.first else find(*args) end
  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.

Parameters:

  • locator (String)

    Id or legend of the fieldset



325
326
327
328
329
# File 'lib/capybara/session.rb', line 325

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.

Overloads:

  • #within_frame(element) ⇒ Object

    Parameters:

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

    Parameters:

    • kind (Symobl)

      Optional selector type (:css, :xpath, :field, 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)



391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
# File 'lib/capybara/session.rb', line 391

def within_frame(*args)
  frame = _find_frame(*args)

  begin
    switch_to_frame(frame)
    begin
      yield
    ensure
      switch_to_frame(:parent)
    end
  rescue Capybara::NotSupportedByDriverError
    # Support older driver frame API for now
    if driver.respond_to?(:within_frame)
      begin
        scopes.push(:frame)
        driver.within_frame(frame) do
          yield
        end
      ensure
        scopes.pop
      end
    else
      raise
    end
  end
end

#within_table(locator) ⇒ 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



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

def within_table(locator)
  within :table, locator do
    yield
  end
end

#within_window(window) ⇒ Object #within_window(proc_or_lambda) ⇒ Object #within_window(string) ⇒ 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

    Parameters:

    • window (Capybara::Window)

      instance of `Capybara::Window` class that will be switched to

    Raises:

    • (driver#no_such_window_error)

      if unexistent (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)

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

    Raises:

  • #within_window(string) ⇒ Object
    Deprecated.

    Pass window or lambda instead

    Parameters:

    • handle, (String)

      name, url or title of the window

Returns:

  • value returned by the block

Raises:

  • (Capybara::ScopeError)

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



530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
# File 'lib/capybara/session.rb', line 530

def within_window(window_or_handle)
  if window_or_handle.instance_of?(Capybara::Window)
    original = current_window
    switch_to_window(window_or_handle) unless original == window_or_handle
    scopes << nil
    begin
      yield
    ensure
      @scopes.pop
      switch_to_window(original) unless original == window_or_handle
    end
  elsif window_or_handle.is_a?(Proc)
    original = current_window
    switch_to_window { window_or_handle.call }
    scopes << nil
    begin
      yield
    ensure
      @scopes.pop
      switch_to_window(original)
    end
  else
    offending_line = caller.first
    file_line = offending_line.match(/^(.+?):(\d+)/)[0]
    warn "DEPRECATION WARNING: Passing string argument to #within_window is deprecated. "\
         "Pass window object or lambda. (called from #{file_line})"
    begin
      scopes << nil
      driver.within_window(window_or_handle) { yield }
    ensure
      @scopes.pop
    end
  end
end