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 = 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.('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_css?, :has_no_content?, :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
-
#app ⇒ Object
readonly
Returns the value of attribute app.
-
#mode ⇒ Object
readonly
Returns the value of attribute mode.
Instance Method Summary collapse
-
#body ⇒ String
(also: #html)
A snapshot of the HTML of the current document, as it looks right now (potentially modified by JavaScript).
-
#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.
-
#initialize(mode, app = nil) ⇒ Session
constructor
A new instance of Session.
-
#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 ⇒ Object
-
#save_page ⇒ Object
Save a snapshot of the page and open it in a browser for inspection.
-
#source ⇒ String
HTML source of the document, before being modified by JavaScript.
-
#status_code ⇒ Integer
Returns the current HTTP status code as an Integer.
-
#visit(url) ⇒ Object
Navigate to the given URL.
-
#wait_until(timeout = Capybara.default_wait_time) ⇒ Object
Retry executing the block until a truthy result is returned or the timeout time is exceeded.
-
#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.
50 51 52 53 |
# File 'lib/capybara/session.rb', line 50 def initialize(mode, app=nil) @mode = mode @app = app end |
Instance Attribute Details
#app ⇒ Object (readonly)
Returns the value of attribute app.
48 49 50 |
# File 'lib/capybara/session.rb', line 48 def app @app end |
#mode ⇒ Object (readonly)
Returns the value of attribute mode.
48 49 50 |
# File 'lib/capybara/session.rb', line 48 def mode @mode end |
Instance Method Details
#body ⇒ String Also known as: html
Returns A snapshot of the HTML of the current document, as it looks right now (potentially modified by JavaScript).
99 100 101 |
# File 'lib/capybara/session.rb', line 99 def body driver.body end |
#current_host ⇒ String
Returns Host of the current page.
125 126 127 128 |
# File 'lib/capybara/session.rb', line 125 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.
116 117 118 119 |
# File 'lib/capybara/session.rb', line 116 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.
134 135 136 |
# File 'lib/capybara/session.rb', line 134 def current_url driver.current_url end |
#document ⇒ Object
286 287 288 |
# File 'lib/capybara/session.rb', line 286 def document Capybara::Node::Document.new(self, driver) end |
#driver ⇒ Object
55 56 57 58 59 60 61 62 63 |
# File 'lib/capybara/session.rb', line 55 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.
268 269 270 |
# File 'lib/capybara/session.rb', line 268 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.
255 256 257 |
# File 'lib/capybara/session.rb', line 255 def execute_script(script) driver.execute_script(script) end |
#reset! ⇒ Object Also known as: cleanup!, reset_session!
Reset the session, removing all cookies.
69 70 71 |
# File 'lib/capybara/session.rb', line 69 def reset! driver.reset! end |
#response_headers ⇒ Hash{String => String}
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
81 82 83 |
# File 'lib/capybara/session.rb', line 81 def response_headers driver.response_headers end |
#save_and_open_page ⇒ Object
281 282 283 284 |
# File 'lib/capybara/session.rb', line 281 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
276 277 278 279 |
# File 'lib/capybara/session.rb', line 276 def save_page require 'capybara/util/save_and_open_page' Capybara.save_page(body) end |
#source ⇒ String
Returns 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)
91 92 93 |
# File 'lib/capybara/session.rb', line 91 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
156 157 158 |
# File 'lib/capybara/session.rb', line 156 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
243 244 245 |
# File 'lib/capybara/session.rb', line 243 def wait_until(timeout = Capybara.default_wait_time) Capybara.timeout(timeout,driver) { yield } end |
#within(*args) ⇒ 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
179 180 181 182 183 184 185 186 187 |
# File 'lib/capybara/session.rb', line 179 def within(*args) new_scope = find(*args) 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.
195 196 197 198 199 |
# File 'lib/capybara/session.rb', line 195 def within_fieldset(locator) within :xpath, XPath::HTML.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)
220 221 222 223 224 |
# File 'lib/capybara/session.rb', line 220 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.
207 208 209 210 211 |
# File 'lib/capybara/session.rb', line 207 def within_table(locator) within :xpath, XPath::HTML.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)
233 234 235 |
# File 'lib/capybara/session.rb', line 233 def within_window(handle, &blk) driver.within_window(handle, &blk) end |