When Capybara.threadsafe == true the sessions options will be initially set
to the current values of the global options and a configuration block can
be passed to the session initializer. For available options see
Capybara::SessionConfig::OPTIONS

Session provides a number of methods for controlling the navigation of the
page, such as visit, +current_path, and so on. It also
delegates a number of methods to a Capybara::Document, representing the
current HTML document. This allows interaction:

Constructor Details

# File 'lib/capybara/session.rb', line 77definitialize(mode,app=nil)raiseTypeError,'The second parameter to Session::new should be a rack app if passed.'ifapp&&!app.respond_to?(:call)@@instance_created=true@mode=mode@app=appifblock_given?raise'A configuration block is only accepted when Capybara.threadsafe == true'unlessCapybara.threadsafeyieldconfigend@server=ifconfig.run_server&&@app&&driver.needs_server?server_options={port:config.server_port,host:config.server_host,reportable_errors:config.server_errors}server_options[:extra_middleware]=[Capybara::Server::AnimationDisabler]ifconfig.disable_animationCapybara::Server.new(@app,server_options).bootend@touched=falseend

#execute_script(script, *args) ⇒ 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

args
—

Optional arguments that will be passed to the script. Driver support for
this is optional and types of objects supported may differ between drivers

#raise_server_error! ⇒ Object

Raise errors encountered in the server

141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

# File 'lib/capybara/session.rb', line 141defraise_server_error!returnunless@server&.error# Force an explanation for the error being raised as the exception cause
beginifconfig.raise_server_errorsraiseCapybaraError,'Your application server raised an error - It has been raised in your test code because Capybara.raise_server_errors == true'endrescueCapybaraError# needed to get the cause set correctly in JRuby -- otherwise we could just do raise @server.error
raise@server.error,@server.error.message,@server.error.backtraceensure@server.reset_error!endend

#refresh ⇒ Object

#reset! ⇒ ObjectAlso known as:
cleanup!, reset_session!

Reset the session (i.e. remove cookies and navigate to blank page)

This method does not:

* accept modal dialogs if they are present (Selenium driver now does, others may not)
* clear browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc.
* modify state of the driver/underlying browser in any other way

as doing so will result in performance downsides and it's not needed to
do everything from the list above for most apps.

If you want to do anything from the list above on a general basis you can:

If you use this method you are responsible for making sure you switch back
to the parent frame when done in the frame changed to.
Capybara::Session#within_frame is preferred over this method and should be
used when possible. May not be supported by all drivers.

# File 'lib/capybara/session.rb', line 374defswitch_to_frame(frame)caseframewhenCapybara::Node::Elementdriver.switch_to_frame(frame)scopes.push(:frame)when:parentifscopes.last!=:frameraiseCapybara::ScopeError,"`switch_to_frame(:parent)` cannot be called from inside a descendant frame's "\
'`within` block.'endscopes.popdriver.switch_to_frame(:parent)when:topidx=scopes.index(:frame)ifidxifscopes.slice(idx..-1).any?{|scope|![:frame,nil].include?(scope)}raiseCapybara::ScopeError,"`switch_to_frame(:top)` cannot be called from inside a descendant frame's "\
'`within` block.'endscopes.slice!(idx..-1)driver.switch_to_frame(:top)endelseraiseArgumentError,'You must provide a frame element, :parent, or :top when calling switch_to_frame'endend

Switches to the first window for which given block returns a value other
than false or nil. If window that matches block can't be found, the
window will be switched back and `WindowError` will be raised.

# File 'lib/capybara/session.rb', line 471defswitch_to_window(window=nil,**options,&window_locator)raiseArgumentError,'`switch_to_window` can take either a block or a window, not both'ifwindow&&block_given?raiseArgumentError,'`switch_to_window`: either window or block should be provided'if!window&&!block_given?unlessscopes.last.nil?raiseCapybara::ScopeError,'`switch_to_window` is not supposed to be invoked from '\
'`within` or `within_frame` blocks.'end_switch_to_window(window,options,&window_locator)end

#visit(visit_uri) ⇒ 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:

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:

# File 'lib/capybara/session.rb', line 245defvisit(visit_uri)raise_server_error!@touched=truevisit_uri=::Addressable::URI.parse(visit_uri.to_s)base_uri=::Addressable::URI.parse(config.app_host||server_url)ifbase_uri&&[nil,'http','https'].include?(visit_uri.scheme)ifvisit_uri.relative?visit_uri_parts=visit_uri.to_hash.delete_if{|_k,value|value.nil?}# Useful to people deploying to a subdirectory
# and/or single page apps where only the url fragment changes
visit_uri_parts[:path]=base_uri.path+visit_uri.pathvisit_uri=base_uri.merge(visit_uri_parts)endadjust_server_port(visit_uri)enddriver.visit(visit_uri.to_s)end

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"]')dofill_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')dofill_in('Street',with:'12 Main Street')end

Note that a lot of uses of `within` can be replaced more succinctly with
chaining:

# File 'lib/capybara/session.rb', line 504defwithin_window(window_or_proc)original=current_windowscopes<<nilbegincasewindow_or_procwhenCapybara::Window_switch_to_window(window_or_proc)unlessoriginal==window_or_procwhenProc_switch_to_window{window_or_proc.call}elseraiseArgumentError('`#within_window` requires a `Capybara::Window` instance or a lambda')endbeginyieldifblock_given?ensure_switch_to_window(original)unlessoriginal==window_or_procendensurescopes.popendend