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.
%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
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
%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
NODE_METHODS + SESSION_METHODS + MODAL_METHODS
Returns the value of attribute app.
Returns the value of attribute mode.
Returns the value of attribute server.
Returns the value of attribute synchronized.
Execute the block, accepting a alert.
Execute the block, accepting a confirm.
Execute the block, accepting a prompt, optionally responding to the prompt.
Returns the element with focus.
Accepts a block to set the configuration options if threadsafe is true.
Host of the current page.
Path of the current page, without any domain information.
Fully qualified URL of the current page.
Current window.
Execute the block, dismissing a confirm.
Execute the block, dismissing a prompt.
Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.
Evaluate the given JavaScript and return the result.
Execute the given script, not returning a result.
Move back a single entry in the browser's history.
Move forward a single entry in the browser's history.
A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).
A new instance of Session.
Open a new window.
Disconnect from the current driver.
Raise errors encountered in the server.
Refresh the page.
Reset the session (i.e. remove cookies and navigate to blank page).
Returns a hash of response headers.
Save a snapshot of the page and open it in a browser for inspection.
Save a screenshot of the page and open it for inspection.
Save a snapshot of the page.
Save a screenshot of page.
Returns the current HTTP status code as an integer.
Switch to the given frame.
Switch to the given window.
Yield a block using a specific maximum wait time.
Navigate to the given URL.
Get the window that has been opened by the passed block.
Get all opened windows.
Executes the given block within the context of a node.
Execute the given block within the a specific fieldset given the id or legend of that fieldset.
Execute the given block within the given iframe using given frame, frame name/id or index.
Execute the given block within the a specific table given the id or caption of that table.
This method does the following:.
#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) ⇒ SessionReturns 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 @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
Returns the value of attribute app.
76 77 78
# File 'lib/capybara/session.rb', line 76 def app @app end#mode ⇒ Object
Returns the value of attribute mode.
76 77 78
# File 'lib/capybara/session.rb', line 76 def mode @mode end#server ⇒ Object
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 endClass Method Details .instance_created? ⇒ Boolean
825 826 827
# File 'lib/capybara/session.rb', line 825 def self.instance_created? @@instance_created endInstance 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.
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.
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.
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
#configure {|config| ... } ⇒ ObjectAccepts 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.
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.
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.
207 208 209 210 211 212 213 214 215 216
# File 'lib/capybara/session.rb', line 207
def current_path
uri = ::Addressable::URI.parse(current_url)
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.
231 232 233
# File 'lib/capybara/session.rb', line 231 def current_url driver.current_url end#current_window ⇒ Capybara::Window
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.
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.
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.
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.
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.
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).
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.
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
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 raise @server.error, cause: capy_error
ensure
@server.reset_error!
end
end #refresh ⇒ Object
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:
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:
prepend method130 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 @scopes = [nil]
end
@server&.wait_for_pending_requests
raise_server_error!
end
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium).
179 180 181
# File 'lib/capybara/session.rb', line 179 def driver. 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.
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.
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.
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.
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).
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.
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.
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('/') 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.
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
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
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.
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')
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.
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.
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.
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:
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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4