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, :current_url, :current_host, :evaluate_script, :source,
  :visit, :within, :within_fieldset, :within_table, :within_frame,
  :within_window, :current_path, :save_page, :save_and_open_page,
  :save_screenshot, :reset_session!, :response_headers, :status_code
]
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.



49
50
51
52
53
54
55
56
57
58
# File 'lib/capybara/session.rb', line 49

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

#appObject (readonly)

Returns the value of attribute app.



47
48
49
# File 'lib/capybara/session.rb', line 47

def app
  @app
end

#modeObject (readonly)

Returns the value of attribute mode.



47
48
49
# File 'lib/capybara/session.rb', line 47

def mode
  @mode
end

#serverObject (readonly)

Returns the value of attribute server.



47
48
49
# File 'lib/capybara/session.rb', line 47

def server
  @server
end

Instance Method Details

#current_hostString

Returns Host of the current page.

Returns:

  • (String)

    Host of the current page



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

def current_host
  uri = URI.parse(current_url)
  "#{uri.scheme}://#{uri.host}" if uri.host
end

#current_pathString

Returns Path of the current page, without any domain information.

Returns:

  • (String)

    Path of the current page, without any domain information



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

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

#current_urlString

Returns Fully qualified URL of the current page.

Returns:

  • (String)

    Fully qualified URL of the current page



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

def current_url
  driver.current_url
end

#documentObject



334
335
336
# File 'lib/capybara/session.rb', line 334

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

#driverObject



60
61
62
63
64
65
66
67
68
# File 'lib/capybara/session.rb', line 60

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)



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

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



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

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

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



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

def html
  driver.html
end

#inspectObject



345
346
347
# File 'lib/capybara/session.rb', line 345

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

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

Reset the session, removing all cookies.



74
75
76
77
78
79
80
# File 'lib/capybara/session.rb', line 74

def reset!
  driver.reset! if @touched
  @touched = false
  raise @server.error if @server and @server.error
ensure
  @server.reset_error! if @server
end

#response_headersHash{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.



90
91
92
# File 'lib/capybara/session.rb', line 90

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:

  • path (String)

    The path to where it should be saved [optional]



317
318
319
320
321
322
# File 'lib/capybara/session.rb', line 317

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) ⇒ Object

Save a snapshot of the page.

Parameters:

  • path (String) (defaults to: nil)

    The path to where it should be saved [optional]



301
302
303
304
305
306
307
308
309
# File 'lib/capybara/session.rb', line 301

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(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



330
331
332
# File 'lib/capybara/session.rb', line 330

def save_screenshot(path, options={})
  driver.save_screenshot(path, options)
end

#status_codeInteger

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

Returns:

  • (Integer)

    Current HTTP status code



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

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



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# File 'lib/capybara/session.rb', line 166

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

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:



210
211
212
213
214
215
216
217
218
# File 'lib/capybara/session.rb', line 210

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



226
227
228
229
230
# File 'lib/capybara/session.rb', line 226

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:

  • frame_id (String)

    Id of the frame



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

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



238
239
240
241
242
# File 'lib/capybara/session.rb', line 238

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



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

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