Class: Capybara::Session
- Inherits:
-
Object
- Object
- Capybara::Session
- 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 = ::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 = ::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.('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
-
#app ⇒ Object
readonly
Returns the value of attribute app.
-
#mode ⇒ Object
readonly
Returns the value of attribute mode.
-
#server ⇒ Object
readonly
Returns the value of attribute server.
Instance Method Summary collapse
-
#current_host ⇒ String
Host of the current page.
-
#current_path ⇒ String
Path of the current page, without any domain information.
-
#current_url ⇒ String
Fully qualified URL of the current page.
- #document ⇒ Object
- #driver ⇒ Object
-
#evaluate_script(script) ⇒ Object
Evaluate the given JavaScript and return the result.
-
#execute_script(script) ⇒ Object
Execute the given script, not returning a result.
-
#html ⇒ String
(also: #body, #source)
A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).
-
#initialize(mode, app = nil) ⇒ Session
constructor
A new instance of Session.
- #inspect ⇒ Object
-
#reset! ⇒ Object
(also: #cleanup!, #reset_session!)
Reset the session, removing all cookies.
-
#response_headers ⇒ Hash{String => String}
Returns a hash of response headers.
-
#save_and_open_page(file_name = nil) ⇒ Object
Save a snapshot of the page and open it in a browser for inspection.
-
#save_page(path = nil) ⇒ Object
Save a snapshot of the page.
-
#save_screenshot(path, options = {}) ⇒ Object
Save a screenshot of page.
-
#status_code ⇒ Integer
Returns the current HTTP status code as an Integer.
-
#visit(url) ⇒ Object
Navigate to the given URL.
-
#within(*args) ⇒ Object
Execute the given block for a particular scope on the page.
-
#within_fieldset(locator) ⇒ Object
Execute the given block within the a specific fieldset given the id or legend of that fieldset.
-
#within_frame(frame_id) ⇒ Object
Execute the given block within the given iframe given the id of that iframe.
-
#within_table(locator) ⇒ Object
Execute the given block within the a specific table given the id or caption of that table.
-
#within_window(handle, &blk) ⇒ Object
Execute the given block within the given window.
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 .run_server and @app and driver.needs_server? @server = ::Server.new(@app).boot else @server = nil end @touched = false end |
Instance Attribute Details
#app ⇒ Object (readonly)
Returns the value of attribute app.
47 48 49 |
# File 'lib/capybara/session.rb', line 47 def app @app end |
#mode ⇒ Object (readonly)
Returns the value of attribute mode.
47 48 49 |
# File 'lib/capybara/session.rb', line 47 def mode @mode end |
#server ⇒ Object (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_host ⇒ String
Returns 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_path ⇒ String
Returns 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_url ⇒ String
Returns Fully qualified URL of the current page.
136 137 138 |
# File 'lib/capybara/session.rb', line 136 def current_url driver.current_url end |
#document ⇒ Object
334 335 336 |
# File 'lib/capybara/session.rb', line 334 def document @document ||= ::Node::Document.new(self, driver) end |
#driver ⇒ Object
60 61 62 63 64 65 66 67 68 |
# File 'lib/capybara/session.rb', line 60 def driver @driver ||= begin unless .drivers.has_key?(mode) other_drivers = .drivers.keys.map { |key| key.inspect } raise ::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}" end .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.
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.
276 277 278 279 |
# File 'lib/capybara/session.rb', line 276 def execute_script(script) @touched = true driver.execute_script(script) 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).
108 109 110 |
# File 'lib/capybara/session.rb', line 108 def html driver.html end |
#inspect ⇒ Object
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_headers ⇒ Hash{String => String}
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
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
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.
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.(path, .save_and_open_page_path) if .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
330 331 332 |
# File 'lib/capybara/session.rb', line 330 def save_screenshot(path, ={}) driver.save_screenshot(path, ) end |
#status_code ⇒ Integer
Returns the current HTTP status code as an Integer. Not supported by all drivers (e.g. Selenium)
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:
.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`.
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 .app_host url = .app_host + url.to_s end if @server url = "http://#{@server.host}:#{@server.port}" + url.to_s unless url =~ /^http/ if .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
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?(::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.
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)
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.
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)
264 265 266 |
# File 'lib/capybara/session.rb', line 264 def within_window(handle, &blk) driver.within_window(handle, &blk) end |