Class: Capybara::Session
- Inherits:
-
Object
- Object
- Capybara::Session
- 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_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 ]
- 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, :title, :has_title?, :has_no_title?, :current_scope ]
- DSL_METHODS =
NODE_METHODS + SESSION_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
-
#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.
- #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.
- #has_no_title?(content) ⇒ Boolean
- #has_title?(content) ⇒ Boolean
-
#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(file_name = nil) ⇒ Object
Save a snapshot of the page and open it in a browser for inspection.
-
#save_and_open_screenshot(file_name = nil) ⇒ Object
Save a screenshot of the page and open it for inspection.
-
#save_page(path = nil) ⇒ Object
Save a snapshot of the page.
-
#save_screenshot(path, options = {}) ⇒ Object
Save a screenshot of page.
-
#status_code ⇒ Integer
Returns the current HTTP status code as an Integer.
-
#switch_to_window(window = nil) ⇒ Capybara::Window
Window that has been switched to.
-
#title ⇒ String
Title of the current page.
-
#visit(url) ⇒ 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:.
Constructor Details
#initialize(mode, app = nil) ⇒ Session
Returns a new instance of Session.
54 55 56 57 58 59 60 61 62 63 |
# File 'lib/capybara/session.rb', line 54 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.
51 52 53 |
# File 'lib/capybara/session.rb', line 51 def app @app end |
#mode ⇒ Object (readonly)
Returns the value of attribute mode.
51 52 53 |
# File 'lib/capybara/session.rb', line 51 def mode @mode end |
#server ⇒ Object (readonly)
Returns the value of attribute server.
51 52 53 |
# File 'lib/capybara/session.rb', line 51 def server @server end |
#synchronized ⇒ Object
Returns the value of attribute synchronized.
52 53 54 |
# File 'lib/capybara/session.rb', line 52 def synchronized @synchronized end |
Instance Method Details
#current_host ⇒ String
Returns Host of the current page.
157 158 159 160 |
# File 'lib/capybara/session.rb', line 157 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.
148 149 150 151 |
# File 'lib/capybara/session.rb', line 148 def current_path path = URI.parse(current_url).path path if path and not path.empty? end |
#current_scope ⇒ Object
615 616 617 |
# File 'lib/capybara/session.rb', line 615 def current_scope scopes.last || document end |
#current_url ⇒ String
Returns Fully qualified URL of the current page.
166 167 168 |
# File 'lib/capybara/session.rb', line 166 def current_url driver.current_url end |
#current_window ⇒ Capybara::Window
Returns current window.
333 334 335 |
# File 'lib/capybara/session.rb', line 333 def current_window Window.new(self, driver.current_window_handle) end |
#document ⇒ Object
578 579 580 |
# File 'lib/capybara/session.rb', line 578 def document @document ||= Capybara::Node::Document.new(self, driver) end |
#driver ⇒ Object
65 66 67 68 69 70 71 72 73 |
# File 'lib/capybara/session.rb', line 65 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.
521 522 523 524 |
# File 'lib/capybara/session.rb', line 521 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.
507 508 509 510 |
# File 'lib/capybara/session.rb', line 507 def execute_script(script) @touched = true driver.execute_script(script) end |
#go_back ⇒ Object
Move back a single entry in the browser’s history.
230 231 232 |
# File 'lib/capybara/session.rb', line 230 def go_back driver.go_back end |
#go_forward ⇒ Object
Move forward a single entry in the browser’s history.
238 239 240 |
# File 'lib/capybara/session.rb', line 238 def go_forward driver.go_forward end |
#has_no_title?(content) ⇒ Boolean
604 605 606 607 608 609 610 611 612 613 |
# File 'lib/capybara/session.rb', line 604 def has_no_title?(content) document.synchronize do if title.match(Capybara::Helpers.to_regexp(content)) raise ExpectationNotMet end end return true rescue Capybara::ExpectationNotMet return false end |
#has_title?(content) ⇒ Boolean
593 594 595 596 597 598 599 600 601 602 |
# File 'lib/capybara/session.rb', line 593 def has_title?(content) document.synchronize do unless title.match(Capybara::Helpers.to_regexp(content)) raise ExpectationNotMet end end return true rescue Capybara::ExpectationNotMet return false 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).
138 139 140 |
# File 'lib/capybara/session.rb', line 138 def html driver.html end |
#inspect ⇒ Object
589 590 591 |
# File 'lib/capybara/session.rb', line 589 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.
357 358 359 360 361 |
# File 'lib/capybara/session.rb', line 357 def open_new_window window_opened_by do driver.open_new_window end end |
#raise_server_error! ⇒ Object
Raise errors encountered in the server
108 109 110 111 112 |
# File 'lib/capybara/session.rb', line 108 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
* 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
93 94 95 96 97 98 99 100 |
# File 'lib/capybara/session.rb', line 93 def reset! if @touched driver.reset! assert_no_selector :xpath, "/html/body/*" @touched = false end raise_server_error! end |
#response_headers ⇒ Hash{String => String}
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
120 121 122 |
# File 'lib/capybara/session.rb', line 120 def response_headers driver.response_headers end |
#save_and_open_page(file_name = nil) ⇒ Object
Save a snapshot of the page and open it in a browser for inspection
547 548 549 550 |
# File 'lib/capybara/session.rb', line 547 def save_and_open_page(file_name=nil) file_name = save_page(file_name) open_file(file_name) end |
#save_and_open_screenshot(file_name = nil) ⇒ Object
Save a screenshot of the page and open it for inspection
573 574 575 576 |
# File 'lib/capybara/session.rb', line 573 def save_and_open_screenshot(file_name=nil) file_name = save_screenshot(file_name) open_file(file_name) end |
#save_page(path = nil) ⇒ Object
Save a snapshot of the page.
532 533 534 535 536 537 538 539 |
# File 'lib/capybara/session.rb', line 532 def save_page(path=nil) path ||= default_path('html') FileUtils.mkdir_p(File.dirname(path)) File.open(path,'wb') { |f| f.write(Capybara::Helpers.inject_asset_host(body)) } path end |
#save_screenshot(path, options = {}) ⇒ Object
Save a screenshot of page
558 559 560 561 562 563 564 565 |
# File 'lib/capybara/session.rb', line 558 def save_screenshot(path, ={}) path ||= default_path('png') FileUtils.mkdir_p(File.dirname(path)) 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)
130 131 132 |
# File 'lib/capybara/session.rb', line 130 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.
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 |
# File 'lib/capybara/session.rb', line 379 def switch_to_window(window = nil) 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 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 |
#title ⇒ String
Returns Title of the current page.
174 175 176 |
# File 'lib/capybara/session.rb', line 174 def title driver.title end |
#visit(url) ⇒ 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`.
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 |
# File 'lib/capybara/session.rb', line 204 def visit(url) raise_server_error! @touched = true if url !~ /^http/ and Capybara.app_host url = Capybara.app_host + url.to_s end if @server url = "http://#{@server.host}:#{@server.port}" + url.to_s unless url =~ /^http/ if Capybara.always_include_port uri = URI.parse(url) uri.port = @server.port if uri.port == uri.default_port url = uri.to_s end end driver.visit(url) 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
484 485 486 487 488 489 490 491 492 493 494 495 496 497 |
# File 'lib/capybara/session.rb', line 484 def window_opened_by( = {}, &block) old_handles = driver.window_handles block.call wait_time = Capybara::Query.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.
344 345 346 347 348 |
# File 'lib/capybara/session.rb', line 344 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')
277 278 279 280 281 282 283 284 285 |
# File 'lib/capybara/session.rb', line 277 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.
293 294 295 296 297 |
# File 'lib/capybara/session.rb', line 293 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.
321 322 323 324 325 326 327 328 |
# File 'lib/capybara/session.rb', line 321 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.
305 306 307 308 309 |
# File 'lib/capybara/session.rb', line 305 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)
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 |
# File 'lib/capybara/session.rb', line 437 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 |