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') session.should have_content('Capybara')
When using capybara/dsl, the Session is initialized automatically for you.
# File lib/capybara/session.rb, line 51 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
@return [String] Host of the current page
# File lib/capybara/session.rb, line 129 def current_host uri = URI.parse(current_url) "#{uri.scheme}://#{uri.host}" if uri.host end
@return [String] Path of the current page, without any domain information
# File lib/capybara/session.rb, line 120 def current_path path = URI.parse(current_url).path path if path and not path.empty? end
# File lib/capybara/session.rb, line 384 def current_scope scopes.last end
@return [String] Fully qualified URL of the current page
# File lib/capybara/session.rb, line 138 def current_url driver.current_url end
# File lib/capybara/session.rb, line 347 def document @document ||= Capybara::Node::Document.new(self, driver) end
# File lib/capybara/session.rb, line 62 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 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.
@param [String] script A string of JavaScript to evaluate @return [Object] The result of the evaluated JavaScript (may be driver specific)
# File lib/capybara/session.rb, line 303 def evaluate_script(script) @touched = true driver.evaluate_script(script) end
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.
@param [String] script A string of JavaScript to execute
# File lib/capybara/session.rb, line 289 def execute_script(script) @touched = true driver.execute_script(script) end
# File lib/capybara/session.rb, line 373 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
# File lib/capybara/session.rb, line 362 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
@return [String] A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).
# File lib/capybara/session.rb, line 110 def html driver.html end
# File lib/capybara/session.rb, line 358 def inspect %Q(#<Capybara::Session>) end
Reset the session, removing all cookies.
# File lib/capybara/session.rb, line 76 def reset! driver.reset! if @touched @touched = false raise @server.error if Capybara.raise_server_errors and @server and @server.error ensure @server.reset_error! if @server end
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
@return [Hash{String => String}] A hash of response headers.
# File lib/capybara/session.rb, line 92 def response_headers driver.response_headers end
Save a snapshot of the page and open it in a browser for inspection
@param [String] file_name The path to where it should be saved [optional]
# File lib/capybara/session.rb, line 330 def save_and_open_page(file_name=nil) require "launchy" Launchy.open(save_page(file_name)) rescue LoadError warn "Please install the launchy gem to open page with save_and_open_page" end
Save a snapshot of the page.
@param [String] path The path to where it should be saved [optional]
# File lib/capybara/session.rb, line 314 def save_page(path=nil) path ||= "capybara-#{Time.new.strftime("%Y%m%d%H%M%S")}#{rand(10**10)}.html" path = File.expand_path(path, Capybara.save_and_open_page_path) if Capybara.save_and_open_page_path FileUtils.mkdir_p(File.dirname(path)) File.open(path,'w') { |f| f.write(Capybara::Helpers.inject_asset_host(body)) } path end
Save a screenshot of page
@param [String] path A string of image path @option [Hash] options Options for saving screenshot
# File lib/capybara/session.rb, line 343 def save_screenshot(path, options={}) driver.save_screenshot(path, options) end
Returns the current HTTP status code as an Integer. Not supported by all drivers (e.g. Selenium)
@return [Integer] Current HTTP status code
# File lib/capybara/session.rb, line 102 def status_code driver.status_code end
@return [String] Title of the current page
# File lib/capybara/session.rb, line 146 def title driver.title end
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`.
@param [String] url The URL to navigate to
# File lib/capybara/session.rb, line 176 def visit(url) @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
Execute the given block for a particular scope on the page. Within will find the first element matching the given selector and execute the block scoped to that element:
within(:xpath, '//div[@id="delivery-address"]') do fill_in('Street', :with => '12 Main Street') end
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
@overload within(*find_args)
@param (see Capybara::Node::Finders#all)
@overload within(a_node)
@param [Capybara::Node::Base] a_node The node in whose scope the block should be evaluated
@raise [Capybara::ElementNotFound] If the scope can't be found before time expires
# File lib/capybara/session.rb, line 220 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
Execute the given block within the a specific fieldset given the id or legend of that fieldset.
@param [String] locator Id or legend of the fieldset
# File lib/capybara/session.rb, line 236 def within_fieldset(locator) within :fieldset, locator do yield end end
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.
@overload #within_frame(index)
@param [Integer] index index of a frame
@overload #within_frame(name)
@param [String] name name of a frame
# File lib/capybara/session.rb, line 264 def within_frame(frame_handle) driver.within_frame(frame_handle) do yield end end
Execute the given block within the a specific table given the id or caption of that table.
@param [String] locator Id or caption of the table
# File lib/capybara/session.rb, line 248 def within_table(locator) within :table, locator do yield end end
Execute the given block within the given window. Only works on some drivers (e.g. Selenium)
@param [String] handle of the window
# File lib/capybara/session.rb, line 277 def within_window(handle, &blk) driver.within_window(handle, &blk) end
# File lib/capybara/session.rb, line 390 def scopes @scopes ||= [document] end