Class: Capybara::Session
- Inherits:
-
Object
- Object
- Capybara::Session
- 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.('Search')
expect(session).to have_content('Capybara')
When using capybara/dsl, the Session is initialized automatically for you.
Constant Summary collapse
- 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, :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_fieldset, :within_table, :within_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
- MODAL_METHODS =
[ :accept_alert, :accept_confirm, :dismiss_confirm, :accept_prompt, :dismiss_prompt ]
- DSL_METHODS =
NODE_METHODS + SESSION_METHODS + MODAL_METHODS
Instance Attribute Summary collapse
-
#app ⇒ Object
readonly
Returns the value of attribute app.
-
#mode ⇒ Object
readonly
Returns the value of attribute mode.
-
#server ⇒ Object
readonly
Returns the value of attribute server.
-
#synchronized ⇒ Object
Returns the value of attribute synchronized.
Instance Method Summary collapse
-
#accept_alert(text_or_options = nil, options = {}, &blk) ⇒ String
Execute the block, accepting a alert.
-
#accept_confirm(text_or_options = nil, options = {}, &blk) ⇒ String
Execute the block, accepting a confirm.
-
#accept_prompt(text_or_options = nil, options = {}, &blk) ⇒ String
Execute the block, accepting a prompt, optionally responding to the prompt.
-
#current_host ⇒ String
Host of the current page.
-
#current_path ⇒ String
Path of the current page, without any domain information.
- #current_scope ⇒ Object
-
#current_url ⇒ String
Fully qualified URL of the current page.
-
#current_window ⇒ Capybara::Window
Current window.
-
#dismiss_confirm(text_or_options = nil, options = {}, &blk) ⇒ String
Execute the block, dismissing a confirm.
-
#dismiss_prompt(text_or_options = nil, options = {}, &blk) ⇒ String
Execute the block, dismissing a prompt.
- #document ⇒ Object
- #driver ⇒ Object
-
#evaluate_script(script) ⇒ Object
Evaluate the given JavaScript and return the result.
-
#execute_script(script) ⇒ Object
Execute the given script, not returning a result.
-
#go_back ⇒ Object
Move back a single entry in the browser’s history.
-
#go_forward ⇒ Object
Move forward a single entry in the browser’s history.
-
#html ⇒ String
(also: #body, #source)
A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).
-
#initialize(mode, app = nil) ⇒ Session
constructor
A new instance of Session.
- #inspect ⇒ Object
-
#open_new_window ⇒ Capybara::Window
Open new window.
-
#raise_server_error! ⇒ Object
Raise errors encountered in the server.
-
#reset! ⇒ Object
(also: #cleanup!, #reset_session!)
Reset the session (i.e. remove cookies and navigate to blank page).
-
#response_headers ⇒ Hash{String => String}
Returns a hash of response headers.
-
#save_and_open_page(path = nil) ⇒ Object
Save a snapshot of the page and open it in a browser for inspection.
-
#save_and_open_screenshot(path = nil, options = {}) ⇒ Object
Save a screenshot of the page and open it for inspection.
-
#save_page(path = nil) ⇒ String
Save a snapshot of the page.
-
#save_screenshot(path = nil, options = {}) ⇒ String
Save a screenshot of page.
-
#status_code ⇒ Integer
Returns the current HTTP status code as an Integer.
-
#switch_to_window(window = nil, options = {}) ⇒ Capybara::Window
Window that has been switched to.
-
#visit(visit_uri) ⇒ Object
Navigate to the given URL.
-
#window_opened_by(options = {}, &block) ⇒ Capybara::Window
Get the window that has been opened by the passed block.
-
#windows ⇒ Array<Capybara::Window>
Get all opened windows.
-
#within(*args) ⇒ Object
Executes the given block within the context of a node.
-
#within_fieldset(locator) ⇒ Object
Execute the given block within the a specific fieldset given the id or legend of that fieldset.
-
#within_frame(frame_handle) ⇒ Object
Execute the given block within the given iframe using given frame name or index.
-
#within_table(locator) ⇒ Object
Execute the given block within the a specific table given the id or caption of that table.
-
#within_window(window_or_handle) ⇒ Object
This method does the following:.
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.
68 69 70 71 72 73 74 75 76 77 |
# File 'lib/capybara/session.rb', line 68 def initialize(mode, app=nil) @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
#app ⇒ Object (readonly)
Returns the value of attribute app.
65 66 67 |
# File 'lib/capybara/session.rb', line 65 def app @app end |
#mode ⇒ Object (readonly)
Returns the value of attribute mode.
65 66 67 |
# File 'lib/capybara/session.rb', line 65 def mode @mode end |
#server ⇒ Object (readonly)
Returns the value of attribute server.
65 66 67 |
# File 'lib/capybara/session.rb', line 65 def server @server end |
#synchronized ⇒ Object
Returns the value of attribute synchronized.
66 67 68 |
# File 'lib/capybara/session.rb', line 66 def synchronized @synchronized end |
Instance Method Details
#accept_alert(text, options = {}, &blk) ⇒ String #accept_alert(options = {}, &blk) ⇒ String
Execute the block, accepting a alert.
553 554 555 556 557 558 559 |
# File 'lib/capybara/session.rb', line 553 def accept_alert(=nil, ={}, &blk) , = nil, if .is_a?(Hash) [:text] ||= unless .nil? [:wait] ||= Capybara.default_max_wait_time driver.accept_modal(:alert, , &blk) end |
#accept_confirm(text, options = {}, &blk) ⇒ String #accept_confirm(options = {}, &blk) ⇒ String
Execute the block, accepting a confirm.
567 568 569 570 571 572 573 |
# File 'lib/capybara/session.rb', line 567 def accept_confirm(=nil, ={}, &blk) , = nil, if .is_a?(Hash) [:text] ||= unless .nil? [:wait] ||= Capybara.default_max_wait_time driver.accept_modal(:confirm, , &blk) end |
#accept_prompt(text, options = {}, &blk) ⇒ String #accept_prompt(options = {}, &blk) ⇒ String
Execute the block, accepting a prompt, optionally responding to the prompt.
596 597 598 599 600 601 602 |
# File 'lib/capybara/session.rb', line 596 def accept_prompt(=nil, ={}, &blk) , = nil, if .is_a?(Hash) [:text] ||= unless .nil? [:wait] ||= Capybara.default_max_wait_time driver.accept_modal(:prompt, , &blk) end |
#current_host ⇒ String
Returns Host of the current page.
171 172 173 174 |
# File 'lib/capybara/session.rb', line 171 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.
162 163 164 165 |
# File 'lib/capybara/session.rb', line 162 def current_path path = URI.parse(current_url).path path if path and not path.empty? end |
#current_scope ⇒ Object
713 714 715 |
# File 'lib/capybara/session.rb', line 713 def current_scope scopes.last || document end |
#current_url ⇒ String
Returns Fully qualified URL of the current page.
180 181 182 |
# File 'lib/capybara/session.rb', line 180 def current_url driver.current_url end |
#current_window ⇒ Capybara::Window
Returns current window.
343 344 345 |
# File 'lib/capybara/session.rb', line 343 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.
581 582 583 584 585 586 587 |
# File 'lib/capybara/session.rb', line 581 def dismiss_confirm(=nil, ={}, &blk) , = nil, if .is_a?(Hash) [:text] ||= unless .nil? [:wait] ||= Capybara.default_max_wait_time driver.dismiss_modal(:confirm, , &blk) end |
#dismiss_prompt(text, options = {}, &blk) ⇒ String #dismiss_prompt(options = {}, &blk) ⇒ String
Execute the block, dismissing a prompt.
610 611 612 613 614 615 616 |
# File 'lib/capybara/session.rb', line 610 def dismiss_prompt(=nil, ={}, &blk) , = nil, if .is_a?(Hash) [:text] ||= unless .nil? [:wait] ||= Capybara.default_max_wait_time driver.dismiss_modal(:prompt, , &blk) end |
#document ⇒ Object
692 693 694 |
# File 'lib/capybara/session.rb', line 692 def document @document ||= Capybara::Node::Document.new(self, driver) end |
#driver ⇒ Object
79 80 81 82 83 84 85 86 87 |
# File 'lib/capybara/session.rb', line 79 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) ⇒ 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.
536 537 538 539 |
# File 'lib/capybara/session.rb', line 536 def evaluate_script(script) @touched = true driver.evaluate_script(script) end |
#execute_script(script) ⇒ 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.
522 523 524 525 |
# File 'lib/capybara/session.rb', line 522 def execute_script(script) @touched = true driver.execute_script(script) end |
#go_back ⇒ Object
Move back a single entry in the browser’s history.
240 241 242 |
# File 'lib/capybara/session.rb', line 240 def go_back driver.go_back end |
#go_forward ⇒ Object
Move forward a single entry in the browser’s history.
248 249 250 |
# File 'lib/capybara/session.rb', line 248 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).
152 153 154 |
# File 'lib/capybara/session.rb', line 152 def html driver.html end |
#inspect ⇒ Object
709 710 711 |
# File 'lib/capybara/session.rb', line 709 def inspect %(#<Capybara::Session>) end |
#open_new_window ⇒ Capybara::Window
Open new window. Current window doesn’t change as the result of this call. It should be switched to explicitly.
367 368 369 370 371 |
# File 'lib/capybara/session.rb', line 367 def open_new_window window_opened_by do driver.open_new_window end end |
#raise_server_error! ⇒ Object
Raise errors encountered in the server
122 123 124 125 126 |
# File 'lib/capybara/session.rb', line 122 def raise_server_error! raise @server.error if Capybara.raise_server_errors and @server and @server.error ensure @server.reset_error! if @server 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
107 108 109 110 111 112 113 114 |
# File 'lib/capybara/session.rb', line 107 def reset! if @touched driver.reset! @touched = false end @server.wait_for_pending_requests if @server raise_server_error! end |
#response_headers ⇒ Hash{String => String}
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
134 135 136 |
# File 'lib/capybara/session.rb', line 134 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
650 651 652 653 |
# File 'lib/capybara/session.rb', line 650 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
687 688 689 690 |
# File 'lib/capybara/session.rb', line 687 def save_and_open_screenshot(path = nil, = {}) path = save_screenshot(path, ) 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
632 633 634 635 636 |
# File 'lib/capybara/session.rb', line 632 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
668 669 670 671 672 |
# File 'lib/capybara/session.rb', line 668 def save_screenshot(path = nil, = {}) path = prepare_path(path, 'png') driver.save_screenshot(path, ) path end |
#status_code ⇒ Integer
Returns the current HTTP status code as an Integer. Not supported by all drivers (e.g. Selenium)
144 145 146 |
# File 'lib/capybara/session.rb', line 144 def status_code driver.status_code end |
#switch_to_window(&block) ⇒ Capybara::Window #switch_to_window(window) ⇒ Capybara::Window
Returns window that has been switched to.
389 390 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 417 418 419 420 421 422 423 424 425 |
# File 'lib/capybara/session.rb', line 389 def switch_to_window(window = nil, = {}) , 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::SelectorQuery.new().wait 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`.
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 |
# File 'lib/capybara/session.rb', line 210 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
499 500 501 502 503 504 505 506 507 508 509 510 511 512 |
# File 'lib/capybara/session.rb', line 499 def window_opened_by( = {}, &block) old_handles = driver.window_handles block.call wait_time = Capybara::Queries::SelectorQuery.new().wait 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 |
#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.
354 355 356 357 358 |
# File 'lib/capybara/session.rb', line 354 def windows driver.window_handles.map do |handle| Window.new(self, handle) end end |
#within(*find_args) ⇒ Object #within(a_node) ⇒ Object
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')
287 288 289 290 291 292 293 294 295 |
# File 'lib/capybara/session.rb', line 287 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.
303 304 305 306 307 |
# File 'lib/capybara/session.rb', line 303 def within_fieldset(locator) within :fieldset, locator do yield end end |
#within_frame(index) ⇒ Object #within_frame(name) ⇒ Object
Execute the given block within the given iframe using given frame name or index. May be supported by not all drivers. Drivers that support it, may provide additional options.
331 332 333 334 335 336 337 338 |
# File 'lib/capybara/session.rb', line 331 def within_frame(frame_handle) scopes.push(nil) driver.within_frame(frame_handle) do yield end ensure scopes.pop end |
#within_table(locator) ⇒ Object
Execute the given block within the a specific table given the id or caption of that table.
315 316 317 318 319 |
# File 'lib/capybara/session.rb', line 315 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:
-
Switches to the given window (it can be located by window instance/lambda/string).
-
Executes the given block (within window located at previous step).
-
Switches back (this step will be invoked even if exception will happen at second step)
452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 |
# File 'lib/capybara/session.rb', line 452 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 |