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

DSL_METHODS = 
[
  :all, :attach_file, :body, :check, :choose, :click_link_or_button, :click_button, :click_link, :current_url, :drag, :evaluate_script,
  :field_labeled, :fill_in, :find, :find_button, :find_by_id, :find_field, :find_link, :has_content?, :has_css?,
  :has_no_content?, :has_no_css?, :has_no_xpath?, :has_xpath?, :locate, :save_and_open_page, :select, :source, :uncheck,
  :visit, :wait_until, :within, :within_fieldset, :within_table, :within_frame, :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?, :current_path, :scope_to, :click, :driver
]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mode, app = nil) ⇒ Session

Returns a new instance of Session.



40
41
42
43
 
# File 'lib/capybara/session.rb', line 40

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(*args) ⇒ Object 



260
261
262
 
# File 'lib/capybara/session.rb', line 260

def method_missing(*args)
  current_node.send(*args)
end

Instance Attribute Details

#app ⇒ Object (readonly)

Returns the value of attribute app.



38
39
40
 
# File 'lib/capybara/session.rb', line 38

def app
  @app
end

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



38
39
40
 
# File 'lib/capybara/session.rb', line 38

def mode
  @mode
end

Instance Method Details

#body ⇒ String

Returns A snapshot of the HTML of the current document, as it looks right now.

Returns:

  • (String) —

    A snapshot of the HTML of the current document, as it looks right now



87
88
89
 
# File 'lib/capybara/session.rb', line 87

def body
  driver.body
end

#cleanup! ⇒ Object

Reset the session, removing all cookies.



59
60
61
 
# File 'lib/capybara/session.rb', line 59

def cleanup!
  driver.cleanup!
end

#click(locator) ⇒ Object

Deprecated.

click is deprecated, please use Node::Actions#click_link_or_button instead



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

def click(locator)
  warn "DEPRECATED: click is deprecated, use click_link_or_button instead"
  current_node.click_link_or_button(locator)
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



103
104
105
 
# File 'lib/capybara/session.rb', line 103

def current_path
  URI.parse(current_url).path
end

#current_url ⇒ String

Returns Fully qualified URL of the current page.

Returns:

  • (String) —

    Fully qualified URL of the current page



111
112
113
 
# File 'lib/capybara/session.rb', line 111

def current_url
  driver.current_url
end

#document ⇒ Object 



256
257
258
 
# File 'lib/capybara/session.rb', line 256

def document
  Capybara::Document.new(self, driver)
end

#driver ⇒ Object 



45
46
47
48
49
50
51
52
53
 
# File 'lib/capybara/session.rb', line 45

def driver
  @driver ||= begin                    
    string = mode.to_s
    string.gsub!(%r{(^.)|(_.)}) { |m| m[m.length-1,1].upcase }
    Capybara::Driver.const_get(string.to_sym).new(app)
  rescue NameError
    raise Capybara::DriverNotFoundError, "no driver called #{mode} was found"
  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)



234
235
236
 
# File 'lib/capybara/session.rb', line 234

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 always be used over evaluate_script whenever possible.

Parameters:

  • script (String) —

    A string of JavaScript to execute



221
222
223
 
# File 'lib/capybara/session.rb', line 221

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

#respond_to?(method) ⇒ Boolean

Returns:

  • (Boolean) 


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

def respond_to?(method)
  super || current_node.respond_to?(method)
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.



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

def response_headers
  driver.response_headers
end

#save_and_open_page ⇒ Object

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



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

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

#source ⇒ String

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

Returns:

  • (String) —

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



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

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



79
80
81
 
# File 'lib/capybara/session.rb', line 79

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



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

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



209
210
211
 
# File 'lib/capybara/session.rb', line 209

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

#within(kind, selector = nil) ⇒ 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

Parameters:

  • kind (:css, :xpath, String) —

    The type of selector or the selector if the second argument is blank

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

    The selector within which to execute the given block



156
157
158
159
160
161
162
163
164
 
# File 'lib/capybara/session.rb', line 156

def within(kind, selector=nil)
  new_scope = find(kind, selector, :message => "scope '#{selector || kind}' not found on page")
  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



172
173
174
175
176
 
# File 'lib/capybara/session.rb', line 172

def within_fieldset(locator)
  within :xpath, XPath.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



197
198
199
200
201
 
# File 'lib/capybara/session.rb', line 197

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



184
185
186
187
188
 
# File 'lib/capybara/session.rb', line 184

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