Class: Capybara::Session
- Inherits:
-
Object
- Object
- Capybara::Session
- Includes:
- Minitest::Expectations, SessionMatchers
- Defined in:
- lib/capybara/session.rb,
lib/capybara/minitest/spec.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')
When threadsafe is 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 = Capybara::Session.new(:driver, MyRackApp) do |config|
config.app_host = "http://my_host.dev"
end
The 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 Document, representing the current HTML document. This allows interaction:
session.fill_in('q', with: 'Capybara')
session.('Search')
expect(session).to have_content('Capybara')
When using capybara/dsl
, the Session is initialized automatically for you.
Constant Summary collapse
- NODE_METHODS =
%i[ all first attach_file text check choose scroll_to scroll_by click double_click right_click click_link_or_button click_button click_link fill_in find find_all 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? 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 assert_all_of_selectors assert_none_of_selectors assert_any_of_selectors refute_selector assert_text assert_no_text ].freeze
- DOCUMENT_METHODS =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
%i[ title assert_title assert_no_title has_title? has_no_title? ].freeze
- SESSION_METHODS =
%i[ body html source current_url current_host current_path execute_script evaluate_script evaluate_async_script visit refresh go_back go_forward send_keys within within_element within_fieldset within_table within_frame switch_to_frame current_window windows open_new_window switch_to_window within_window window_opened_by save_page save_and_open_page save_screenshot save_and_open_screenshot reset_session! response_headers status_code current_scope assert_current_path assert_no_current_path has_current_path? has_no_current_path? ].freeze + DOCUMENT_METHODS
- MODAL_METHODS =
%i[ accept_alert accept_confirm dismiss_confirm accept_prompt dismiss_prompt ].freeze
- DSL_METHODS =
NODE_METHODS + SESSION_METHODS + MODAL_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.
-
#synchronized ⇒ Object
Returns the value of attribute synchronized.
Class Method Summary collapse
Instance Method Summary collapse
-
#accept_alert(text = nil, **options, &blk) ⇒ String
Execute the block, accepting a alert.
-
#accept_confirm(text = nil, **options, &blk) ⇒ String
Execute the block, accepting a confirm.
-
#accept_prompt(text = nil, **options, &blk) ⇒ String
Execute the block, accepting a prompt, optionally responding to the prompt.
-
#active_element ⇒ Object
Returns the element with focus.
- #config ⇒ Object
-
#configure {|config| ... } ⇒ Object
Accepts a block to set the configuration options if threadsafe is
true
. -
#current_host ⇒ String
Host of the current page.
-
#current_path ⇒ String
Path of the current page, without any domain information.
- #current_scope ⇒ Object
-
#current_url ⇒ String
Fully qualified URL of the current page.
-
#current_window ⇒ Capybara::Window
Current window.
-
#dismiss_confirm(text = nil, **options, &blk) ⇒ String
Execute the block, dismissing a confirm.
-
#dismiss_prompt(text = nil, **options, &blk) ⇒ String
Execute the block, dismissing a prompt.
- #document ⇒ Object
- #driver ⇒ Object
-
#evaluate_async_script(script, *args) ⇒ Object
Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.
-
#evaluate_script(script, *args) ⇒ Object
Evaluate the given JavaScript and return the result.
-
#execute_script(script, *args) ⇒ Object
Execute the given script, not returning a result.
-
#go_back ⇒ Object
Move back a single entry in the browser's history.
-
#go_forward ⇒ Object
Move forward a single entry in the browser's history.
-
#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
-
#open_new_window(kind = :tab) ⇒ Capybara::Window
Open a new window.
-
#quit ⇒ Object
Disconnect from the current driver.
-
#raise_server_error! ⇒ Object
Raise errors encountered in the server.
-
#refresh ⇒ Object
Refresh the page.
-
#reset! ⇒ Object
(also: #cleanup!, #reset_session!)
Reset the session (i.e. remove cookies and navigate to blank page).
-
#response_headers ⇒ Hash<String, String>
Returns a hash of response headers.
-
#save_and_open_page(path = nil) ⇒ Object
Save a snapshot of the page and open it in a browser for inspection.
-
#save_and_open_screenshot(path = nil, **options) ⇒ Object
Save a screenshot of the page and open it for inspection.
-
#save_page(path = nil) ⇒ String
Save a snapshot of the page.
-
#save_screenshot(path = nil, **options) ⇒ String
Save a screenshot of page.
- #send_keys ⇒ Object
- #server_url ⇒ Object
-
#status_code ⇒ Integer
Returns the current HTTP status code as an integer.
-
#switch_to_frame(frame) ⇒ Object
Switch to the given frame.
-
#switch_to_window(window = nil, **options, &window_locator) ⇒ Capybara::Window
Switch to the given window.
-
#using_wait_time(seconds, &block) ⇒ Object
Yield a block using a specific maximum wait time.
-
#visit(visit_uri) ⇒ Object
Navigate to the given URL.
-
#window_opened_by(**options, &block) ⇒ Capybara::Window
Get the window that has been opened by the passed block.
-
#windows ⇒ Array<Capybara::Window>
Get all opened windows.
-
#within(*args, **kw_args) ⇒ Object
(also: #within_element)
Executes the given block within the context of a node.
-
#within_fieldset(locator, &block) ⇒ Object
Execute the given block within the a specific fieldset given the id or legend of that fieldset.
-
#within_frame(*args, **kw_args) ⇒ Object
Execute the given block within the given iframe using given frame, frame name/id or index.
-
#within_table(locator, &block) ⇒ Object
Execute the given block within the a specific table given the id or caption of that table.
-
#within_window(window_or_proc) ⇒ Object
This method does the following:.
Methods included from Minitest::Expectations
#must_have_all_of_selectors, #must_have_ancestor, #must_have_any_of_selectors, #must_have_button, #must_have_checked_field, #must_have_content, #must_have_css, #must_have_current_path, #must_have_field, #must_have_link, #must_have_none_of_selectors, #must_have_select, #must_have_selector, #must_have_sibling, #must_have_style, #must_have_table, #must_have_text, #must_have_title, #must_have_unchecked_field, #must_have_xpath, #must_match_style, #wont_have_button, #wont_have_checked_field, #wont_have_content, #wont_have_css, #wont_have_current_path, #wont_have_field, #wont_have_link, #wont_have_select, #wont_have_selector, #wont_have_table, #wont_have_text, #wont_have_title, #wont_have_unchecked_field, #wont_have_xpath
Methods included from SessionMatchers
#assert_current_path, #assert_no_current_path, #has_current_path?, #has_no_current_path?
Constructor Details
#initialize(mode, app = nil) ⇒ Session
Returns a new instance of Session.
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 |
# File 'lib/capybara/session.rb', line 78 def initialize(mode, app = nil) if app && !app.respond_to?(:call) raise TypeError, 'The second parameter to Session::new should be a rack app if passed.' end @@instance_created = true # rubocop:disable Style/ClassVars @mode = mode @app = app if block_given? raise 'A configuration block is only accepted when Capybara.threadsafe == true' unless Capybara.threadsafe yield config end @server = if config.run_server && @app && driver.needs_server? = { port: config.server_port, host: config.server_host, reportable_errors: config.server_errors } [:extra_middleware] = [Capybara::Server::AnimationDisabler] if config.disable_animation Capybara::Server.new(@app, **).boot end @touched = false end |
Instance Attribute Details
#app ⇒ Object (readonly)
Returns the value of attribute app.
75 76 77 |
# File 'lib/capybara/session.rb', line 75 def app @app end |
#mode ⇒ Object (readonly)
Returns the value of attribute mode.
75 76 77 |
# File 'lib/capybara/session.rb', line 75 def mode @mode end |
#server ⇒ Object (readonly)
Returns the value of attribute server.
75 76 77 |
# File 'lib/capybara/session.rb', line 75 def server @server end |
#synchronized ⇒ Object
Returns the value of attribute synchronized.
76 77 78 |
# File 'lib/capybara/session.rb', line 76 def synchronized @synchronized end |
Class Method Details
.instance_created? ⇒ Boolean
824 825 826 |
# File 'lib/capybara/session.rb', line 824 def self.instance_created? @@instance_created end |
Instance Method Details
#accept_alert(text, **options) { ... } ⇒ String #accept_alert(**options) { ... } ⇒ String
Execute the block, accepting a alert.
Expects a block whose actions will trigger the display modal to appear.
658 659 660 |
# File 'lib/capybara/session.rb', line 658 def accept_alert(text = nil, **, &blk) accept_modal(:alert, text, , &blk) end |
#accept_confirm(text, **options) { ... } ⇒ String #accept_confirm(**options) { ... } ⇒ String
Execute the block, accepting a confirm.
Expects a block whose actions will trigger the display modal to appear.
668 669 670 |
# File 'lib/capybara/session.rb', line 668 def accept_confirm(text = nil, **, &blk) accept_modal(:confirm, text, , &blk) end |
#accept_prompt(text, **options) { ... } ⇒ String #accept_prompt(**options) { ... } ⇒ String
Execute the block, accepting a prompt, optionally responding to the prompt.
Expects a block whose actions will trigger the display modal to appear.
689 690 691 |
# File 'lib/capybara/session.rb', line 689 def accept_prompt(text = nil, **, &blk) accept_modal(:prompt, text, , &blk) end |
#active_element ⇒ Object
Returns the element with focus.
Not supported by Rack Test
322 323 324 |
# File 'lib/capybara/session.rb', line 322 def active_element Capybara::Queries::ActiveElementQuery.new.resolve_for(self)[0].tap(&:allow_reload!) end |
#config ⇒ Object
828 829 830 831 832 833 834 |
# File 'lib/capybara/session.rb', line 828 def config @config ||= if Capybara.threadsafe Capybara..dup else Capybara::ReadOnlySessionConfig.new(Capybara.) end end |
#configure {|config| ... } ⇒ Object
Accepts a block to set the configuration options if threadsafe is true
. Note that some options only have an effect
if set at initialization time, so look at the configuration block that can be passed to the initializer too.
818 819 820 821 822 |
# File 'lib/capybara/session.rb', line 818 def configure raise 'Session configuration is only supported when Capybara.threadsafe == true' unless Capybara.threadsafe yield config end |
#current_host ⇒ String
Returns Host of the current page.
221 222 223 224 |
# File 'lib/capybara/session.rb', line 221 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.
206 207 208 209 210 211 212 213 214 215 |
# File 'lib/capybara/session.rb', line 206 def current_path # Addressable parsing is more lenient than URI uri = ::Addressable::URI.parse(current_url) # Addressable doesn't support opaque URIs - we want nil here return nil if uri&.scheme == 'about' path = uri&.path path unless path&.empty? end |
#current_scope ⇒ Object
790 791 792 793 |
# File 'lib/capybara/session.rb', line 790 def current_scope scope = scopes.last [nil, :frame].include?(scope) ? document : scope end |
#current_url ⇒ String
Returns Fully qualified URL of the current page.
230 231 232 |
# File 'lib/capybara/session.rb', line 230 def current_url driver.current_url end |
#current_window ⇒ Capybara::Window
Returns current window.
459 460 461 |
# File 'lib/capybara/session.rb', line 459 def current_window Window.new(self, driver.current_window_handle) end |
#dismiss_confirm(text, **options) { ... } ⇒ String #dismiss_confirm(**options) { ... } ⇒ String
Execute the block, dismissing a confirm.
Expects a block whose actions will trigger the display modal to appear.
678 679 680 |
# File 'lib/capybara/session.rb', line 678 def dismiss_confirm(text = nil, **, &blk) dismiss_modal(:confirm, text, , &blk) end |
#dismiss_prompt(text, **options) { ... } ⇒ String #dismiss_prompt(**options) { ... } ⇒ String
Execute the block, dismissing a prompt.
Expects a block whose actions will trigger the display modal to appear.
699 700 701 |
# File 'lib/capybara/session.rb', line 699 def dismiss_prompt(text = nil, **, &blk) dismiss_modal(:prompt, text, , &blk) end |
#document ⇒ Object
765 766 767 |
# File 'lib/capybara/session.rb', line 765 def document @document ||= Capybara::Node::Document.new(self, driver) end |
#driver ⇒ Object
99 100 101 102 103 104 105 106 107 108 109 |
# File 'lib/capybara/session.rb', line 99 def driver @driver ||= begin unless Capybara.drivers[mode] other_drivers = Capybara.drivers.names.map(&:inspect) raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}" end driver = Capybara.drivers[mode].call(app) driver.session = self if driver.respond_to?(:session=) driver end end |
#evaluate_async_script(script, *args) ⇒ Object
Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.
632 633 634 635 636 |
# File 'lib/capybara/session.rb', line 632 def evaluate_async_script(script, *args) @touched = true result = driver.evaluate_async_script(script, *driver_args(args)) element_script_result(result) end |
#evaluate_script(script, *args) ⇒ 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.
618 619 620 621 622 |
# File 'lib/capybara/session.rb', line 618 def evaluate_script(script, *args) @touched = true result = driver.evaluate_script(script.strip, *driver_args(args)) element_script_result(result) end |
#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.
603 604 605 606 |
# File 'lib/capybara/session.rb', line 603 def execute_script(script, *args) @touched = true driver.execute_script(script, *driver_args(args)) end |
#go_back ⇒ Object
Move back a single entry in the browser's history.
296 297 298 |
# File 'lib/capybara/session.rb', line 296 def go_back driver.go_back end |
#go_forward ⇒ Object
Move forward a single entry in the browser's history.
304 305 306 |
# File 'lib/capybara/session.rb', line 304 def go_forward driver.go_forward 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).
196 197 198 |
# File 'lib/capybara/session.rb', line 196 def html driver.html || '' end |
#inspect ⇒ Object
786 787 788 |
# File 'lib/capybara/session.rb', line 786 def inspect %(#<Capybara::Session>) end |
#open_new_window(kind = :tab) ⇒ Capybara::Window
Open a new window. The current window doesn't change as the result of this call. It should be switched to explicitly.
483 484 485 486 487 488 489 490 491 |
# File 'lib/capybara/session.rb', line 483 def open_new_window(kind = :tab) window_opened_by do if driver.method(:open_new_window).arity.zero? driver.open_new_window else driver.open_new_window(kind) end end end |
#quit ⇒ Object
Disconnect from the current driver. A new driver will be instantiated on the next interaction.
146 147 148 149 150 151 |
# File 'lib/capybara/session.rb', line 146 def quit @driver.quit if @driver.respond_to? :quit @document = @driver = nil @touched = false @server&.reset_error! end |
#raise_server_error! ⇒ Object
Raise errors encountered in the server.
157 158 159 160 161 162 163 164 165 166 167 168 169 170 |
# File 'lib/capybara/session.rb', line 157 def raise_server_error! return unless @server&.error # Force an explanation for the error being raised as the exception cause begin if config.raise_server_errors raise CapybaraError, 'Your application server raised an error - It has been raised in your test code because Capybara.raise_server_errors == true' end rescue CapybaraError => capy_error # rubocop:disable Naming/RescuedExceptionsVariableName raise @server.error, cause: capy_error ensure @server.reset_error! end end |
#refresh ⇒ Object
Refresh the page.
287 288 289 290 |
# File 'lib/capybara/session.rb', line 287 def refresh raise_server_error! driver.refresh end |
#reset! ⇒ Object Also 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:
- write RSpec/Cucumber/etc. after hook
- monkeypatch this method
- use Ruby's
prepend
method
129 130 131 132 133 134 135 136 137 138 |
# File 'lib/capybara/session.rb', line 129 def reset! if @touched driver.reset! @touched = false switch_to_frame(:top) rescue nil # rubocop:disable Style/RescueModifier @scopes = [nil] end @server&.wait_for_pending_requests raise_server_error! end |
#response_headers ⇒ Hash<String, String>
Returns a hash of response headers. Not supported by all drivers (e.g. Selenium).
178 179 180 |
# File 'lib/capybara/session.rb', line 178 def response_headers driver.response_headers end |
#save_and_open_page(path = nil) ⇒ Object
731 732 733 |
# File 'lib/capybara/session.rb', line 731 def save_and_open_page(path = nil) save_page(path).tap { |s_path| open_file(s_path) } end |
#save_and_open_screenshot(path = nil, **options) ⇒ Object
761 762 763 |
# File 'lib/capybara/session.rb', line 761 def save_and_open_screenshot(path = nil, **) save_screenshot(path, **).tap { |s_path| open_file(s_path) } end |
#save_page(path = nil) ⇒ String
Save a snapshot of the page. If asset_host is set it will inject base
tag
pointing to asset_host.
If invoked without arguments it will save file to save_path and file will be given randomly generated filename. If invoked with a relative path the path will be relative to save_path.
715 716 717 718 719 |
# File 'lib/capybara/session.rb', line 715 def save_page(path = nil) prepare_path(path, 'html').tap do |p_path| File.write(p_path, Capybara::Helpers.inject_asset_host(body, host: config.asset_host), mode: 'wb') end end |
#save_screenshot(path = nil, **options) ⇒ String
746 747 748 |
# File 'lib/capybara/session.rb', line 746 def save_screenshot(path = nil, **) prepare_path(path, 'png').tap { |p_path| driver.save_screenshot(p_path, **) } end |
#send_keys ⇒ Object
312 313 314 |
# File 'lib/capybara/session.rb', line 312 def send_keys(*args, **kw_args) driver.send_keys(*args, **kw_args) end |
#server_url ⇒ Object
836 837 838 |
# File 'lib/capybara/session.rb', line 836 def server_url @server&.base_url end |
#status_code ⇒ Integer
Returns the current HTTP status code as an integer. Not supported by all drivers (e.g. Selenium).
188 189 190 |
# File 'lib/capybara/session.rb', line 188 def status_code driver.status_code end |
#switch_to_frame(element) ⇒ Object #switch_to_frame(location) ⇒ Object
Switch to the given frame.
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. #within_frame is preferred over this method and should be used when possible. May not be supported by all drivers.
407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 |
# File 'lib/capybara/session.rb', line 407 def switch_to_frame(frame) case frame when Capybara::Node::Element driver.switch_to_frame(frame) scopes.push(:frame) when :parent if scopes.last != :frame raise Capybara::ScopeError, "`switch_to_frame(:parent)` cannot be called from inside a descendant frame's " \ '`within` block.' end scopes.pop driver.switch_to_frame(:parent) when :top idx = scopes.index(:frame) top_level_scopes = [:frame, nil] if idx if scopes.slice(idx..).any? { |scope| !top_level_scopes.include?(scope) } raise Capybara::ScopeError, "`switch_to_frame(:top)` cannot be called from inside a descendant frame's " \ '`within` block.' end scopes.slice!(idx..) driver.switch_to_frame(:top) end else raise ArgumentError, 'You must provide a frame element, :parent, or :top when calling switch_to_frame' end end |
#switch_to_window(&block) ⇒ Capybara::Window #switch_to_window(window) ⇒ Capybara::Window
Switch to the given window.
511 512 513 514 515 516 517 518 519 520 521 |
# File 'lib/capybara/session.rb', line 511 def switch_to_window(window = nil, **, &window_locator) raise ArgumentError, '`switch_to_window` can take either a block or a window, not both' if window && window_locator raise ArgumentError, '`switch_to_window`: either window or block should be provided' if !window && !window_locator unless scopes.last.nil? raise Capybara::ScopeError, '`switch_to_window` is not supposed to be invoked from ' \ '`within` or `within_frame` blocks.' end _switch_to_window(window, **, &window_locator) end |
#using_wait_time(seconds, &block) ⇒ Object
Yield a block using a specific maximum wait time.
799 800 801 802 803 804 805 806 807 808 809 810 811 |
# File 'lib/capybara/session.rb', line 799 def using_wait_time(seconds, &block) if Capybara.threadsafe begin previous_wait_time = config.default_max_wait_time config.default_max_wait_time = seconds yield ensure config.default_max_wait_time = previous_wait_time end else Capybara.using_wait_time(seconds, &block) end 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 app_host will make the remote server the default. For example:
Capybara.app_host = 'http://google.com'
session.visit('/') # visits the google homepage
If 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 http://google.com:4567/test
.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 |
# File 'lib/capybara/session.rb', line 260 def visit(visit_uri) raise_server_error! @touched = true visit_uri = ::Addressable::URI.parse(visit_uri.to_s) base_uri = ::Addressable::URI.parse(config.app_host || server_url) if base_uri && [nil, 'http', 'https'].include?(visit_uri.scheme) if visit_uri.relative? visit_uri_parts = visit_uri.to_hash.compact # 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.path visit_uri = base_uri.merge(visit_uri_parts) end adjust_server_port(visit_uri) end driver.visit(visit_uri.to_s) end |
#window_opened_by(**options, &block) ⇒ Capybara::Window
Get the window that has been opened by the passed block.
It will wait for it to be opened (in the same way as other Capybara methods wait).
It's better to use this method than windows.last
as order of windows isn't defined in some drivers.
580 581 582 583 584 585 586 587 588 589 590 591 592 |
# File 'lib/capybara/session.rb', line 580 def window_opened_by(**) old_handles = driver.window_handles yield synchronize_windows() do opened_handles = (driver.window_handles - old_handles) if opened_handles.size != 1 raise Capybara::WindowError, 'block passed to #window_opened_by ' \ "opened #{opened_handles.size} windows instead of 1" end Window.new(self, opened_handles.first) end end |
#windows ⇒ Array<Capybara::Window>
Get all opened windows. The order of windows in returned array is not defined. The driver may sort windows by their creation time but it's not required.
470 471 472 473 474 |
# File 'lib/capybara/session.rb', line 470 def windows driver.window_handles.map do |handle| Window.new(self, handle) end end |
#within(*find_args) ⇒ Object #within(a_node) ⇒ Object Also known as: within_element
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"]') do
fill_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 default_selector.
within('div#delivery-address') do
fill_in('Street', with: '12 Main Street')
end
Note that a lot of uses of #within can be replaced more succinctly with chaining:
find('div#delivery-address').fill_in('Street', with: '12 Main Street')
361 362 363 364 365 366 367 368 369 |
# File 'lib/capybara/session.rb', line 361 def within(*args, **kw_args) new_scope = args.first.respond_to?(:to_capybara_node) ? args.first. : find(*args, **kw_args) begin scopes.push(new_scope) yield new_scope if block_given? ensure scopes.pop end end |
#within_fieldset(locator, &block) ⇒ Object
Execute the given block within the a specific fieldset given the id or legend of that fieldset.
378 379 380 |
# File 'lib/capybara/session.rb', line 378 def within_fieldset(locator, &block) within(:fieldset, locator, &block) end |
#within_frame(element) ⇒ Object #within_frame([kind = :frame], locator, **options) ⇒ Object #within_frame(index) ⇒ Object
Execute the given block within the given iframe using given frame, frame name/id or index. May not be supported by all drivers.
447 448 449 450 451 452 453 454 |
# File 'lib/capybara/session.rb', line 447 def within_frame(*args, **kw_args) switch_to_frame(_find_frame(*args, **kw_args)) begin yield if block_given? ensure switch_to_frame(:parent) end end |
#within_table(locator, &block) ⇒ Object
Execute the given block within the a specific table given the id or caption of that table.
388 389 390 |
# File 'lib/capybara/session.rb', line 388 def within_table(locator, &block) within(:table, locator, &block) end |
#within_window(window) ⇒ Object #within_window(proc_or_lambda) ⇒ Object
This method does the following:
- Switches to the given window (it can be located by window instance/lambda/string).
- Executes the given block (within window located at previous step).
- Switches back (this step will be invoked even if an exception occurs at the second step).
544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 |
# File 'lib/capybara/session.rb', line 544 def within_window(window_or_proc) original = current_window scopes << nil begin case window_or_proc when Capybara::Window _switch_to_window(window_or_proc) unless original == window_or_proc when Proc _switch_to_window { window_or_proc.call } else raise ArgumentError, '`#within_window` requires a `Capybara::Window` instance or a lambda' end begin yield if block_given? ensure _switch_to_window(original) unless original == window_or_proc end ensure scopes.pop end end |