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?, :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
]
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, :within_window,
  :save_page, :save_and_open_page, :save_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

Instance Method Summary collapse

Constructor Details

#initialize(mode, app = nil) ⇒ Session

Returns a new instance of Session.



52
53
54
55
56
57
58
59
60
61
 
# File 'lib/capybara/session.rb', line 52

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.



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

#server ⇒ Object (readonly)

Returns the value of attribute server.



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

def server
  @server
end

#synchronized ⇒ Object

Returns the value of attribute synchronized.



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

def synchronized
  @synchronized
end

Instance Method Details

#current_host ⇒ String

Returns Host of the current page.

Returns:

  • (String) —

    Host of the current page



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

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



124
125
126
127
 
# File 'lib/capybara/session.rb', line 124

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

#current_scope ⇒ Object 



426
427
428
 
# File 'lib/capybara/session.rb', line 426

def current_scope
  scopes.last || document
end

#current_url ⇒ String

Returns Fully qualified URL of the current page.

Returns:

  • (String) —

    Fully qualified URL of the current page



142
143
144
 
# File 'lib/capybara/session.rb', line 142

def current_url
  driver.current_url
end

#document ⇒ Object 



389
390
391
 
# File 'lib/capybara/session.rb', line 389

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

#driver ⇒ Object 



63
64
65
66
67
68
69
70
71
 
# File 'lib/capybara/session.rb', line 63

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)



340
341
342
343
 
# File 'lib/capybara/session.rb', line 340

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.

Parameters:

  • script (String) —

    A string of JavaScript to execute



326
327
328
329
 
# File 'lib/capybara/session.rb', line 326

def execute_script(script)
  @touched = true
  driver.execute_script(script)
end

#go_back ⇒ Object

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



204
205
206
 
# File 'lib/capybara/session.rb', line 204

def go_back
  driver.go_back
end

#go_forward ⇒ Object

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



212
213
214
 
# File 'lib/capybara/session.rb', line 212

def go_forward
  driver.go_forward
end

#has_no_title?(content) ⇒ Boolean

Returns:

  • (Boolean) 


415
416
417
418
419
420
421
422
423
424
 
# File 'lib/capybara/session.rb', line 415

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

Returns:

  • (Boolean) 


404
405
406
407
408
409
410
411
412
413
 
# File 'lib/capybara/session.rb', line 404

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

Returns:

  • (String) —

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



114
115
116
 
# File 'lib/capybara/session.rb', line 114

def html
  driver.html
end

#inspect ⇒ Object 



400
401
402
 
# File 'lib/capybara/session.rb', line 400

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

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

Reset the session, removing all cookies.



77
78
79
80
81
82
83
84
85
86
 
# File 'lib/capybara/session.rb', line 77

def reset!
  if @touched
    driver.reset!
    @touched = false
    assert_no_selector :xpath, "/html/body/*"
  end
  raise @server.error if Capybara.raise_server_errors and @server and @server.error
ensure
  @server.reset_error! if @server
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.



96
97
98
 
# File 'lib/capybara/session.rb', line 96

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

Parameters:

  • file_name (String) (defaults to: nil) —

    The path to where it should be saved [optional]



367
368
369
370
371
372
373
374
375
376
377
 
# File 'lib/capybara/session.rb', line 367

def save_and_open_page(file_name=nil)
  file_name = save_page(file_name)

  begin
    require "launchy"
    Launchy.open(file_name)
  rescue LoadError
    warn "Page saved to #{file_name} with save_and_open_page."
    warn "Please install the launchy gem to open page automatically."
  end
end

#save_page(path = nil) ⇒ Object

Save a snapshot of the page.

Parameters:

  • path (String) (defaults to: nil) —

    The path to where it should be saved [optional]



351
352
353
354
355
356
357
358
359
 
# File 'lib/capybara/session.rb', line 351

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)

  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 = {}) ⇒ Object

Save a screenshot of page

Parameters:

  • path (String) —

    A string of image path

  • [Hash] (Hash) —

    a customizable set of options



385
386
387
 
# File 'lib/capybara/session.rb', line 385

def save_screenshot(path, options={})
  driver.save_screenshot(path, options)
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



106
107
108
 
# File 'lib/capybara/session.rb', line 106

def status_code
  driver.status_code
end

#title ⇒ String

Returns Title of the current page.

Returns:

  • (String) —

    Title of the current page



150
151
152
 
# File 'lib/capybara/session.rb', line 150

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`.

Parameters:

  • url (String) —

    The URL to navigate to



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

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

Overloads:

  • #within(a_node) ⇒ Object

    Parameters:

Raises:



251
252
253
254
255
256
257
258
259
 
# File 'lib/capybara/session.rb', line 251

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.

Parameters:

  • locator (String) —

    Id or legend of the fieldset



267
268
269
270
271
 
# File 'lib/capybara/session.rb', line 267

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.

Overloads:

  • #within_frame(index) ⇒ Object

    Parameters:

    • index (Integer) —

      index of a frame

  • #within_frame(name) ⇒ Object

    Parameters:

    • name (String) —

      name of a frame



295
296
297
298
299
300
301
302
 
# File 'lib/capybara/session.rb', line 295

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.

Parameters:

  • locator (String) —

    Id or caption of the table



279
280
281
282
283
 
# File 'lib/capybara/session.rb', line 279

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:

  • handle (String) —

    of the window



311
312
313
314
315
316
 
# File 'lib/capybara/session.rb', line 311

def within_window(handle, &blk)
  scopes.push(nil)
  driver.within_window(handle, &blk)
ensure
  scopes.pop
end