class Capybara::Session

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.

Constants

DSL_METHODS
NODE_METHODS
SESSION_METHODS

Attributes

app[R]
mode[R]
server[R]
synchronized[RW]

Public Class Methods

new(mode, app=nil) click to toggle source
# 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

Public Instance Methods

body()
Alias for: html
cleanup!()
Alias for: reset!
current_host() click to toggle source

@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
current_path() click to toggle source

@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
current_scope() click to toggle source
# File lib/capybara/session.rb, line 384
def current_scope
  scopes.last
end
current_url() click to toggle source

@return [String] Fully qualified URL of the current page

# File lib/capybara/session.rb, line 138
def current_url
  driver.current_url
end
document() click to toggle source
# File lib/capybara/session.rb, line 347
def document
  @document ||= Capybara::Node::Document.new(self, driver)
end
driver() click to toggle source
# 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_script(script) click to toggle source

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_script(script) click to toggle source

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
has_no_title?(content) click to toggle source
# 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
has_title?(content) click to toggle source
# 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
html() click to toggle source

@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
Also aliased as: body, source
inspect() click to toggle source
# File lib/capybara/session.rb, line 358
def inspect
  %Q(#<Capybara::Session>)
end
reset!() click to toggle source

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
Also aliased as: cleanup!, reset_session!
reset_session!()
Alias for: reset!
response_headers() click to toggle source

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_and_open_page(file_name=nil) click to toggle source

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_page(path=nil) click to toggle source

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_screenshot(path, options={}) click to toggle source

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
source()
Alias for: html
status_code() click to toggle source

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
title() click to toggle source

@return [String] Title of the current page

# File lib/capybara/session.rb, line 146
def title
  driver.title
end
visit(url) click to toggle source

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
within(*args) { || ... } click to toggle source

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
within_fieldset(locator) { || ... } click to toggle source

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
within_frame(frame_handle) { || ... } click to toggle source

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
within_table(locator) { || ... } click to toggle source

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
within_window(handle, &blk) click to toggle source

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

Private Instance Methods

scopes() click to toggle source
# File lib/capybara/session.rb, line 390
def scopes
  @scopes ||= [document]
end