Class: Capybara::Session

### Home Classes Methods

### In Files

- lib/capybara/session.rb

### Parent

Object

### Methods

- ::new
- #accept_alert
- #accept_confirm
- #accept_prompt
- #body
- #cleanup!
- #current_host
- #current_path
- #current_scope
- #current_url
- #current_window
- #dismiss_confirm
- #dismiss_prompt
- #document
- #driver
- #evaluate_script
- #execute_script
- #go_back
- #go_forward
- #html
- #inspect
- #open_new_window
- #raise_server_error!
- #reset!
- #reset_session!
- #response_headers
- #save_and_open_page
- #save_and_open_screenshot
- #save_page
- #save_screenshot
- #source
- #status_code
- #switch_to_window
- #visit
- #window_opened_by
- #windows
- #within
- #within_fieldset
- #within_frame
- #within_table
- #within_window

### Files

- another_test_file.txt
- test_file.txt

### Class/Module Index

Quicksearch

- Capybara
- Capybara::Ambiguous
- Capybara::CapybaraError
- Capybara::DSL
- Capybara::Driver
- Capybara::Driver::Base
- Capybara::Driver::Node
- Capybara::DriverNotFoundError
- Capybara::ElementNotFound
- Capybara::ExpectationNotMet
- Capybara::Features
- Capybara::FileNotFound
- Capybara::FrozenInTime
- Capybara::Helpers
- Capybara::InfiniteRedirectError
- Capybara::ModalNotFound
- Capybara::Node
- Capybara::Node::Actions
- Capybara::Node::Base
- Capybara::Node::Document
- Capybara::Node::DocumentMatchers
- Capybara::Node::Element
- Capybara::Node::Finders
- Capybara::Node::Matchers
- Capybara::Node::Simple
- Capybara::NotSupportedByDriverError
- Capybara::Queries
- Capybara::Queries::BaseQuery
- Capybara::Queries::TextQuery
- Capybara::Queries::TitleQuery
- Capybara::Query
- Capybara::RSpecMatchers
- Capybara::RSpecMatchers::BecomeClosed
- Capybara::RSpecMatchers::HaveSelector
- Capybara::RSpecMatchers::HaveText
- Capybara::RSpecMatchers::HaveTitle
- Capybara::RSpecMatchers::Matcher
- Capybara::RackTest
- Capybara::RackTest::Browser
- Capybara::RackTest::CSSHandlers
- Capybara::RackTest::Driver
- Capybara::RackTest::Form
- Capybara::RackTest::Form::NilUploadedFile
- Capybara::RackTest::Node
- Capybara::ReadOnlyElementError
- Capybara::Result
- Capybara::ScopeError
- Capybara::Selector
- Capybara::Selector::Filter
- Capybara::Selenium
- Capybara::Selenium::Driver
- Capybara::Selenium::Node
- Capybara::Server
- Capybara::Server::Middleware
- Capybara::Session
- Capybara::SpecHelper
- Capybara::UnselectNotAllowed
- Capybara::Window
- Capybara::WindowError
- TestApp
- TestApp::TestAppError
- Object

No matching classes.

# 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')
    expect(session).to have_content('Capybara')

When using capybara/dsl, the Session is initialized automatically for you.

### Constants

DOCUMENT_METHODS

  @api private

DSL_METHODS
MODAL_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 62
    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

accept_alert(text_or_options=nil, options={}, &blk) click to toggle source

Execute the block, accepting a alert.

@!macro modal_params

    @overload $0(text, options = {}, &blk)
      @param text [String, Regexp]  Text or regex to match against the text in the modal.  If not provided any modal is matched
    @overload $0(options = {}, &blk)
    @option options [Numeric] :wait  How long to wait for the modal to appear after executing the block.
    @return [String]  the message shown in the modal
    @raise [Capybara::ModalNotFound]  if modal dialog hasn't been found

    # File lib/capybara/session.rb, line 542
    def accept_alert(text_or_options=nil, options={}, &blk)
      if text_or_options.is_a? Hash
        options=text_or_options
      else
        options[:text]=text_or_options
      end

      driver.accept_modal(:alert, options, &blk)
    end

accept_confirm(text_or_options=nil, options={}, &blk) click to toggle source

Execute the block, accepting a confirm.

@macro modal_params

    # File lib/capybara/session.rb, line 558
    def accept_confirm(text_or_options=nil, options={}, &blk)
      if text_or_options.is_a? Hash
        options=text_or_options
      else
        options[:text]=text_or_options
      end

      driver.accept_modal(:confirm, options, &blk)
    end

accept_prompt(text_or_options=nil, options={}, &blk) click to toggle source

Execute the block, accepting a prompt, optionally responding to the prompt.

@macro modal_params @option options [String] :with Response to provide to the prompt

    # File lib/capybara/session.rb, line 591
    def accept_prompt(text_or_options=nil, options={}, &blk)
      if text_or_options.is_a? Hash
        options=text_or_options
      else
        options[:text]=text_or_options
      end

      driver.accept_modal(:prompt, options, &blk)
    end

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

@return [String] Host of the current page

    # File lib/capybara/session.rb, line 165
    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 156
    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 690
    def current_scope
      scopes.last || document
    end

current_url() click to toggle source

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

    # File lib/capybara/session.rb, line 174
    def current_url
      driver.current_url
    end

current_window() click to toggle source

@return [Capybara::Window] current window

    # File lib/capybara/session.rb, line 337
    def current_window
      Window.new(self, driver.current_window_handle)
    end

dismiss_confirm(text_or_options=nil, options={}, &blk) click to toggle source

Execute the block, dismissing a confirm.

@macro modal_params

    # File lib/capybara/session.rb, line 574
    def dismiss_confirm(text_or_options=nil, options={}, &blk)
      if text_or_options.is_a? Hash
        options=text_or_options
      else
        options[:text]=text_or_options
      end

      driver.dismiss_modal(:confirm, options, &blk)
    end

dismiss_prompt(text_or_options=nil, options={}, &blk) click to toggle source

Execute the block, dismissing a prompt.

@macro modal_params

    # File lib/capybara/session.rb, line 607
    def dismiss_prompt(text_or_options=nil, options={}, &blk)
      if text_or_options.is_a? Hash
        options=text_or_options
      else
        options[:text]=text_or_options
      end

      driver.dismiss_modal(:prompt, options, &blk)
    end

document() click to toggle source

    # File lib/capybara/session.rb, line 669
    def document
      @document ||= Capybara::Node::Document.new(self, driver)
    end

driver() click to toggle source

    # File lib/capybara/session.rb, line 73
    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 525
    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 511
    def execute_script(script)
      @touched = true
      driver.execute_script(script)
    end

go_back() click to toggle source

Move back a single entry in the browser's history.

    # File lib/capybara/session.rb, line 234
    def go_back
      driver.go_back
    end

go_forward() click to toggle source

Move forward a single entry in the browser's history.

    # File lib/capybara/session.rb, line 242
    def go_forward
      driver.go_forward
    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 146
    def html
      driver.html
    end

Also aliased as: body, source
inspect() click to toggle source

    # File lib/capybara/session.rb, line 686
    def inspect
      %(#<Capybara::Session>)
    end

open_new_window() click to toggle source

Open new window. Current window doesn't change as the result of this call. It should be switched to explicitly.

@return [Capybara::Window] window that has been opened

    # File lib/capybara/session.rb, line 361
    def open_new_window
      window_opened_by do
        driver.open_new_window
      end
    end

raise_server_error!() click to toggle source

Raise errors encountered in the server

    # File lib/capybara/session.rb, line 116
    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!() click to toggle source

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

    # File lib/capybara/session.rb, line 101
    def reset!
      if @touched
        driver.reset!
        assert_no_selector :xpath, "/html/body/*"
        @touched = false
      end
      raise_server_error!
    end

Also aliased as: cleanup!, reset_session!
reset_session!() click to toggle source
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 128
    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 638
    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) click to toggle source

Save a screenshot of the page and open it for inspection

@param [String] file_name The path to where it should be saved [optional]

    # File lib/capybara/session.rb, line 664
    def save_and_open_screenshot(file_name=nil)
      file_name = save_screenshot(file_name)
      open_file(file_name)
    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 623
    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={}) 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 649
    def save_screenshot(path, options={})
      path ||= default_path('png')

      FileUtils.mkdir_p(File.dirname(path))

      driver.save_screenshot(path, options)
      path
    end

source() click to toggle 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 138
    def status_code
      driver.status_code
    end

switch_to_window(window = nil) click to toggle source

@overload switch_to_window(&block)

    Switches to the first window for which given block returns a value other than false or nil.
    If window that matches block can't be found, the window will be switched back and `WindowError` will be raised.
    @example
      window = switch_to_window { title == 'Page title' }
    @raise [Capybara::WindowError]     if no window matches given block

@overload switch_to_window(window)

    @param window [Capybara::Window]   window that should be switched to
    @raise [Capybara::Driver::Base#no_such_window_error] if unexistent (e.g. closed) window was passed

@return [Capybara::Window] window that has been switched to @raise [Capybara::ScopeError] if this method is invoked inside `within`,

    `within_frame` or `within_window` methods

@raise [ArgumentError] if both or neither arguments were provided

    # File lib/capybara/session.rb, line 383
    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

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 [to_s] url The URL to navigate to. The parameter will be cast to a String.

    # File lib/capybara/session.rb, line 204
    def visit(url)
      raise_server_error!

      url = url.to_s
      @touched = true

      url_relative = URI.parse(url).scheme.nil?

      if url_relative && Capybara.app_host
        url = Capybara.app_host + url
        url_relative = false
      end

      if @server
        url = "http://#{@server.host}:#{@server.port}" + url if url_relative

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

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` {dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html#h_note_10 as order of windows isn't defined in some drivers}

@param options [Hash] @option options [Numeric] :wait (Capybara.default_wait_time) wait time @return [Capybara::Window] the window that has been opened within a block @raise [Capybara::WindowError] if block passed to window hasn't opened window

    or opened more than one window

    # File lib/capybara/session.rb, line 488
    def window_opened_by(options = {}, &block)
      old_handles = driver.window_handles
      block.call

      wait_time = Capybara::Query.new(options).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() click to toggle source

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.

@return [Array<Capybara::Window>] an array of all windows

    # File lib/capybara/session.rb, line 348
    def windows
      driver.window_handles.map do |handle|
        Window.new(self, handle)
      end
    end

within(*args) click to toggle source

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')

@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 281
    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 297
    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 325
    def within_frame(frame_handle)
      scopes.push(nil)
      driver.within_frame(frame_handle) do
        yield
      end
    ensure
      scopes.pop
    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 309
    def within_table(locator)
      within :table, locator do
        yield
      end
    end

within_window(window_or_handle) click to toggle source

This method does the following:

1. Switches to the given window (it can be located by window instance/lambda/string).

2. Executes the given block (within window located at previous step).

3. Switches back (this step will be invoked even if exception will happen at second step)

@overload within_window(window) { do_something }

    @param window [Capybara::Window]       instance of `Capybara::Window` class
      that will be switched to
    @raise [driver#no_such_window_error] if unexistent (e.g. closed) window was passed

@overload within_window(proc_or_lambda) { do_something }

    @param lambda [Proc]                  lambda. First window for which lambda
      returns a value other than false or nil will be switched to.
    @example
      within_window(->{ page.title == 'Page title' }) { click_button 'Submit' }
    @raise [Capybara::WindowError]         if no window matching lambda was found

@overload within_window(string) { do_something }

    @deprecated                            Pass window or lambda instead
    @param [String]                        handle, name, url or title of the window

@raise [Capybara::ScopeError] if this method is invoked inside `within`,

    `within_frame` or `within_window` methods

@return value returned by the block

    # File lib/capybara/session.rb, line 441
    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

[Validate]

Generated with the Darkfish Rdoc Generator 2.