Class: Capybara::Session

Inherits:
Object
  • Object
show all
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.click_button('Search')
session.should 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?,
  :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?
]
SESSION_METHODS = 
[
  :body, :html, :current_url, :current_host, :evaluate_script, :source,
  :visit, :wait_until, :within, :within_fieldset, :within_table,
  :within_frame, :within_window, :current_path, :save_page,
  :save_and_open_page, :reset_session!
]
DSL_METHODS = 
NODE_METHODS + SESSION_METHODS

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mode, app = nil) ⇒ Session

Returns a new instance of Session.



51
52
53
54
 
# File 'lib/capybara/session.rb', line 51

def initialize(mode, app=nil)
  @mode = mode
  @app = app
end

Instance Attribute Details

#app ⇒ Object (readonly)

Returns the value of attribute app.



49
50
51
 
# File 'lib/capybara/session.rb', line 49

def app
  @app
end

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



49
50
51
 
# File 'lib/capybara/session.rb', line 49

def mode
  @mode
end

Instance Method Details

#current_host ⇒ String

Returns Host of the current page.

Returns:

  • (String) —

    Host of the current page



126
127
128
129
 
# File 'lib/capybara/session.rb', line 126

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.

Returns:

  • (String) —

    Path of the current page, without any domain information



117
118
119
120
 
# File 'lib/capybara/session.rb', line 117

def current_path
  path = URI.parse(current_url).path
  path if path and not path.empty?
end

#current_url ⇒ String

Returns Fully qualified URL of the current page.

Returns:

  • (String) —

    Fully qualified URL of the current page



135
136
137
 
# File 'lib/capybara/session.rb', line 135

def current_url
  driver.current_url
end

#document ⇒ Object 



296
297
298
 
# File 'lib/capybara/session.rb', line 296

def document
  @document ||= Capybara::Node::Document.new(self, driver)
end

#driver ⇒ Object 



56
57
58
59
60
61
62
63
64
 
# File 'lib/capybara/session.rb', line 56

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.

Parameters:

  • script (String) —

    A string of JavaScript to evaluate

Returns:

  • (Object) —

    The result of the evaluated JavaScript (may be driver specific)



278
279
280
 
# File 'lib/capybara/session.rb', line 278

def evaluate_script(script)
  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.

Parameters:

  • script (String) —

    A string of JavaScript to execute



265
266
267
 
# File 'lib/capybara/session.rb', line 265

def execute_script(script)
  driver.execute_script(script)
end

#html ⇒ String

Returns A snapshot of the HTML of the current document, as it looks right now (potentially modified by JavaScript).

Returns:

  • (String) —

    A snapshot of the HTML of the current document, as it looks right now (potentially modified by JavaScript).



100
101
102
 
# File 'lib/capybara/session.rb', line 100

def html
  driver.body
end

#inspect ⇒ Object 



308
309
310
 
# File 'lib/capybara/session.rb', line 308

def inspect
  %(#<Capybara::Session>)
end

#reset! ⇒ Object Also known as: cleanup!, reset_session!

Reset the session, removing all cookies.



70
71
72
 
# File 'lib/capybara/session.rb', line 70

def reset!
  driver.reset!
end

#response_headers ⇒ Hash{String => String}

Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)

Returns:

  • (Hash{String => String}) —

    A hash of response headers.



82
83
84
 
# File 'lib/capybara/session.rb', line 82

def response_headers
  driver.response_headers
end

#save_and_open_page ⇒ Object 



291
292
293
294
 
# File 'lib/capybara/session.rb', line 291

def save_and_open_page
  require 'capybara/util/save_and_open_page'
  Capybara.save_and_open_page(body)
end

#save_page ⇒ Object

Save a snapshot of the page and open it in a browser for inspection



286
287
288
289
 
# File 'lib/capybara/session.rb', line 286

def save_page
  require 'capybara/util/save_and_open_page'
  Capybara.save_page(body)
end

#source ⇒ String Also known as: body

Returns HTML source of the document, before being modified by JavaScript.

Returns:

  • (String) —

    HTML source of the document, before being modified by JavaScript.



108
109
110
 
# File 'lib/capybara/session.rb', line 108

def source
  driver.source
end

#status_code ⇒ Integer

Returns the current HTTP status code as an Integer. Not supported by all drivers (e.g. Selenium)

Returns:

  • (Integer) —

    Current HTTP status code



92
93
94
 
# File 'lib/capybara/session.rb', line 92

def status_code
  driver.status_code
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 culerity and selenium 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

Parameters:

  • url (String) —

    The URL to navigate to



157
158
159
 
# File 'lib/capybara/session.rb', line 157

def visit(url)
  driver.visit(url)
end

#wait_until(timeout = Capybara.default_wait_time) ⇒ Object

Retry executing the block until a truthy result is returned or the timeout time is exceeded

Parameters:

  • timeout (Integer) (defaults to: Capybara.default_wait_time) —

    The amount of seconds to retry executing the given block



253
254
255
 
# File 'lib/capybara/session.rb', line 253

def wait_until(timeout = Capybara.default_wait_time)
  Capybara.timeout(timeout,driver) { yield }
end

#within(*find_args) ⇒ Object #within(a_node) ⇒ Object

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

Overloads:

  • #within(a_node) ⇒ Object

    Parameters:

Raises:



185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/capybara/session.rb', line 185

def within(*args)
  new_scope = if args.size == 1 && Capybara::Node::Base === args.first
                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.

Parameters:

  • locator (String) —

    Id or legend of the fieldset



205
206
207
208
209
 
# File 'lib/capybara/session.rb', line 205

def within_fieldset(locator)
  within :fieldset, locator do
    yield
  end
end

#within_frame(frame_id) ⇒ Object

Execute the given block within the given iframe given the id of that iframe. Only works on some drivers (e.g. Selenium)

Parameters:

  • locator (String) —

    Id of the frame



230
231
232
233
234
 
# File 'lib/capybara/session.rb', line 230

def within_frame(frame_id)
  driver.within_frame(frame_id) do
    yield
  end
end

#within_table(locator) ⇒ Object

Execute the given block within the a specific table given the id or caption of that table.

Parameters:

  • locator (String) —

    Id or caption of the table



217
218
219
220
221
 
# File 'lib/capybara/session.rb', line 217

def within_table(locator)
  within :table, locator do
    yield
  end
end

#within_window(handle, &blk) ⇒ Object

Execute the given block within the given window. Only works on some drivers (e.g. Selenium)

Parameters:

  • locator (String) —

    of the window



243
244
245
 
# File 'lib/capybara/session.rb', line 243

def within_window(handle, &blk)
  driver.within_window(handle, &blk)
end