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')
expect(session).to 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,
  :refute_selector, :assert_text, :assert_no_text
]
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. 

[
  :title, :assert_title, :assert_no_title, :has_title?, :has_no_title?
]
SESSION_METHODS = 
[
  :body, :html, :source, :current_url, :current_host, :current_path,
  :execute_script, :evaluate_script, :visit, :go_back, :go_forward,
  :within, :within_fieldset, :within_table, :within_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
] + DOCUMENT_METHODS
[
  :accept_alert, :accept_confirm, :dismiss_confirm, :accept_prompt,
  :dismiss_prompt
]
DSL_METHODS = 
NODE_METHODS + SESSION_METHODS + MODAL_METHODS

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mode, app = nil) ⇒ Session

Returns a new instance of Session.



62
63
64
65
66
67
68
69
70
71
 
# File 'lib/capybara/session.rb', line 62

def initialize(mode, app=nil)
  @mode = mode
  @app = app
  if Capybara.run_server and @app and driver.needs_server?
    @server = Capybara::Server.new(@app).boot
  else
    @server = nil
  end
  @touched = false
end

Instance Attribute Details

#app ⇒ Object (readonly)

Returns the value of attribute app.



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

def app
  @app
end

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



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

def mode
  @mode
end

#server ⇒ Object (readonly)

Returns the value of attribute server.



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

def server
  @server
end

#synchronized ⇒ Object

Returns the value of attribute synchronized.



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

def synchronized
  @synchronized
end

Instance Method Details

#accept_alert(text, options = {}, &blk) ⇒ String #accept_alert(options = {}, &blk) ⇒ String

Execute the block, accepting a alert.

Overloads:

  • #accept_alert(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :wait (Numeric) —

    How long to wait for the modal to appear after executing the block.

Returns:

  • (String) —

    the message shown in the modal

Raises:



541
542
543
544
545
546
547
548
549
 
# File 'lib/capybara/session.rb', line 541

def accept_alert(text_or_options=nil, options={}, &blk)
  if text_or_options.is_a? Hash
    options=text_or_options
  else
    options[:text]=text_or_options
  end

  driver.accept_modal(:alert, options, &blk)
end

#accept_confirm(text, options = {}, &blk) ⇒ String #accept_confirm(options = {}, &blk) ⇒ String

Execute the block, accepting a confirm.

Overloads:

  • #accept_confirm(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :wait (Numeric) —

    How long to wait for the modal to appear after executing the block.

Returns:

  • (String) —

    the message shown in the modal

Raises:



557
558
559
560
561
562
563
564
565
 
# File 'lib/capybara/session.rb', line 557

def accept_confirm(text_or_options=nil, options={}, &blk)
  if text_or_options.is_a? Hash
    options=text_or_options
  else
    options[:text]=text_or_options
  end
  
  driver.accept_modal(:confirm, options, &blk)
end

#accept_prompt(text, options = {}, &blk) ⇒ String #accept_prompt(options = {}, &blk) ⇒ String

Execute the block, accepting a prompt, optionally responding to the prompt.

Overloads:

  • #accept_prompt(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :wait (Numeric) —

    How long to wait for the modal to appear after executing the block.

  • :with (String) —

    Response to provide to the prompt

Returns:

  • (String) —

    the message shown in the modal

Raises:



590
591
592
593
594
595
596
597
598
 
# File 'lib/capybara/session.rb', line 590

def accept_prompt(text_or_options=nil, options={}, &blk)
  if text_or_options.is_a? Hash
    options=text_or_options
  else
    options[:text]=text_or_options
  end
  
  driver.accept_modal(:prompt, options, &blk)
end

#current_host ⇒ String

Returns Host of the current page.

Returns:

  • (String) —

    Host of the current page



165
166
167
168
 
# File 'lib/capybara/session.rb', line 165

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.

Returns:

  • (String) —

    Path of the current page, without any domain information



156
157
158
159
 
# File 'lib/capybara/session.rb', line 156

def current_path
  path = URI.parse(current_url).path
  path if path and not path.empty?
end

#current_scope ⇒ Object 



689
690
691
 
# File 'lib/capybara/session.rb', line 689

def current_scope
  scopes.last || document
end

#current_url ⇒ String

Returns Fully qualified URL of the current page.

Returns:

  • (String) —

    Fully qualified URL of the current page



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

def current_url
  driver.current_url
end

#current_window ⇒ Capybara::Window

Returns current window.

Returns:



336
337
338
 
# File 'lib/capybara/session.rb', line 336

def current_window
  Window.new(self, driver.current_window_handle)
end

#dismiss_confirm(text, options = {}, &blk) ⇒ String #dismiss_confirm(options = {}, &blk) ⇒ String

Execute the block, dismissing a confirm.

Overloads:

  • #dismiss_confirm(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :wait (Numeric) —

    How long to wait for the modal to appear after executing the block.

Returns:

  • (String) —

    the message shown in the modal

Raises:



573
574
575
576
577
578
579
580
581
 
# File 'lib/capybara/session.rb', line 573

def dismiss_confirm(text_or_options=nil, options={}, &blk)
  if text_or_options.is_a? Hash
    options=text_or_options
  else
    options[:text]=text_or_options
  end
  
  driver.dismiss_modal(:confirm, options, &blk)
end

#dismiss_prompt(text, options = {}, &blk) ⇒ String #dismiss_prompt(options = {}, &blk) ⇒ String

Execute the block, dismissing a prompt.

Overloads:

  • #dismiss_prompt(text, options = {}, &blk) ⇒ String

    Parameters:

    • text (String, Regexp) —

      Text or regex to match against the text in the modal. If not provided any modal is matched

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :wait (Numeric) —

    How long to wait for the modal to appear after executing the block.

Returns:

  • (String) —

    the message shown in the modal

Raises:



606
607
608
609
610
611
612
613
614
 
# File 'lib/capybara/session.rb', line 606

def dismiss_prompt(text_or_options=nil, options={}, &blk)
  if text_or_options.is_a? Hash
    options=text_or_options
  else
    options[:text]=text_or_options
  end
  
  driver.dismiss_modal(:prompt, options, &blk)
end

#document ⇒ Object 



668
669
670
 
# File 'lib/capybara/session.rb', line 668

def document
  @document ||= Capybara::Node::Document.new(self, driver)
end

#driver ⇒ Object 



73
74
75
76
77
78
79
80
81
 
# File 'lib/capybara/session.rb', line 73

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.

Parameters:

  • script (String) —

    A string of JavaScript to evaluate

Returns:

  • (Object) —

    The result of the evaluated JavaScript (may be driver specific)



524
525
526
527
 
# File 'lib/capybara/session.rb', line 524

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.

Parameters:

  • script (String) —

    A string of JavaScript to execute



510
511
512
513
 
# File 'lib/capybara/session.rb', line 510

def execute_script(script)
  @touched = true
  driver.execute_script(script)
end

#go_back ⇒ Object

Move back a single entry in the browser’s history.



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

def go_back
  driver.go_back
end

#go_forward ⇒ Object

Move forward a single entry in the browser’s history.



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

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).

Returns:

  • (String) —

    A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).



146
147
148
 
# File 'lib/capybara/session.rb', line 146

def html
  driver.html
end

#inspect ⇒ Object 



685
686
687
 
# File 'lib/capybara/session.rb', line 685

def inspect
  %(#<Capybara::Session>)
end

#open_new_window ⇒ Capybara::Window

Open new window. Current window doesn’t change as the result of this call. It should be switched to explicitly.

Returns:



360
361
362
363
364
 
# File 'lib/capybara/session.rb', line 360

def open_new_window
  window_opened_by do
    driver.open_new_window
  end
end

#raise_server_error! ⇒ Object

Raise errors encountered in the server



116
117
118
119
120
 
# File 'lib/capybara/session.rb', line 116

def raise_server_error!
  raise @server.error if Capybara.raise_server_errors and @server and @server.error
ensure
  @server.reset_error! if @server
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



101
102
103
104
105
106
107
108
 
# File 'lib/capybara/session.rb', line 101

def reset!
  if @touched
    driver.reset!
    assert_no_selector :xpath, "/html/body/*"
    @touched = false
  end
  raise_server_error!
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.



128
129
130
 
# File 'lib/capybara/session.rb', line 128

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

Parameters:

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

    The path to where it should be saved [optional]



637
638
639
640
 
# File 'lib/capybara/session.rb', line 637

def save_and_open_page(file_name=nil)
  file_name = save_page(file_name)
  open_file(file_name)
end

#save_and_open_screenshot(file_name = nil) ⇒ Object

Save a screenshot of the page and open it for inspection

Parameters:

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

    The path to where it should be saved [optional]



663
664
665
666
 
# File 'lib/capybara/session.rb', line 663

def save_and_open_screenshot(file_name=nil)
  file_name = save_screenshot(file_name)
  open_file(file_name)
end

#save_page(path = nil) ⇒ Object

Save a snapshot of the page.

Parameters:

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

    The path to where it should be saved [optional]



622
623
624
625
626
627
628
629
 
# File 'lib/capybara/session.rb', line 622

def save_page(path=nil)
  path ||= default_path('html')

  FileUtils.mkdir_p(File.dirname(path))

  File.open(path,'wb') { |f| f.write(Capybara::Helpers.inject_asset_host(body)) }
  path
end

#save_screenshot(path, options = {}) ⇒ Object

Save a screenshot of page

Parameters:

  • path (String) —

    A string of image path

  • [Hash] (Hash) —

    a customizable set of options



648
649
650
651
652
653
654
655
 
# File 'lib/capybara/session.rb', line 648

def save_screenshot(path, options={})
  path ||= default_path('png')

  FileUtils.mkdir_p(File.dirname(path))

  driver.save_screenshot(path, options)
  path
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



138
139
140
 
# File 'lib/capybara/session.rb', line 138

def status_code
  driver.status_code
end

#switch_to_window(&block) ⇒ Capybara::Window #switch_to_window(window) ⇒ Capybara::Window

Returns window that has been switched to.

Overloads:

  • #switch_to_window(&block) ⇒ Capybara::Window

    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.

    Examples:

    window = switch_to_window { title == 'Page title' }

    Raises:

  • #switch_to_window(window) ⇒ Capybara::Window

    Parameters:

    Raises:

Returns:

Raises:

  • (Capybara::ScopeError) —

    if this method is invoked inside ‘within`, `within_frame` or `within_window` methods

  • (ArgumentError) —

    if both or neither arguments were provided



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/capybara/session.rb', line 382

def switch_to_window(window = nil)
  block_given = block_given?
  if window && block_given
    raise ArgumentError, "`switch_to_window` can take either a block or a window, not both"
  elsif !window && !block_given
    raise ArgumentError, "`switch_to_window`: either window or block should be provided"
  elsif scopes.size > 1
    raise Capybara::ScopeError, "`switch_to_window` is not supposed to be invoked from "\
                                "`within`'s, `within_frame`'s' or `within_window`'s' block."
  end

  if window
    driver.switch_to_window(window.handle)
    window
  else
    original_window_handle = driver.current_window_handle
    begin
      driver.window_handles.each do |handle|
        driver.switch_to_window handle
        if yield
          return Window.new(self, handle)
        end
      end
    rescue => e
      driver.switch_to_window(original_window_handle)
      raise e
    else
      driver.switch_to_window(original_window_handle)
      raise Capybara::WindowError, "Could not find a window matching block/lambda"
    end
  end
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:

Capybara.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`.

Parameters:

  • url (String) —

    The URL to navigate to



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/capybara/session.rb', line 204

def visit(url)
  raise_server_error!

  @touched = true

  url_relative = URI.parse(url.to_s).scheme.nil?

  if url_relative && Capybara.app_host
    url = Capybara.app_host + url.to_s
    url_relative = false
  end

  if @server
    url = "http://#{@server.host}:#{@server.port}" + url.to_s if url_relative

    if Capybara.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

#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

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :wait (Numeric) — default: Capybara.default_wait_time —

    wait time

Returns:

Raises:

  • (Capybara::WindowError) —

    if block passed to window hasn’t opened window or opened more than one window



487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/capybara/session.rb', line 487

def window_opened_by(options = {}, &block)
  old_handles = driver.window_handles
  block.call

  wait_time = Capybara::Query.new(options).wait
  document.synchronize(wait_time, errors: [Capybara::WindowError]) 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.

Returns:



347
348
349
350
351
 
# File 'lib/capybara/session.rb', line 347

def windows
  driver.window_handles.map do |handle|
    Window.new(self, handle)
  end
end

#within(*find_args) ⇒ Object #within(a_node) ⇒ Object

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 Capybara.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')

Overloads:

  • #within(a_node) ⇒ Object

    Parameters:

Raises:



280
281
282
283
284
285
286
287
288
 
# File 'lib/capybara/session.rb', line 280

def within(*args)
  new_scope = if args.first.is_a?(Capybara::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.

Parameters:

  • locator (String) —

    Id or legend of the fieldset



296
297
298
299
300
 
# File 'lib/capybara/session.rb', line 296

def within_fieldset(locator)
  within :fieldset, locator do
    yield
  end
end

#within_frame(index) ⇒ Object #within_frame(name) ⇒ Object

Execute the given block within the given iframe using given frame name or index. May be supported by not all drivers. Drivers that support it, may provide additional options.

Overloads:

  • #within_frame(index) ⇒ Object

    Parameters:

    • index (Integer) —

      index of a frame

  • #within_frame(name) ⇒ Object

    Parameters:

    • name (String) —

      name of a frame



324
325
326
327
328
329
330
331
 
# File 'lib/capybara/session.rb', line 324

def within_frame(frame_handle)
  scopes.push(nil)
  driver.within_frame(frame_handle) do
    yield
  end
ensure
  scopes.pop
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



308
309
310
311
312
 
# File 'lib/capybara/session.rb', line 308

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

#within_window(window) ⇒ Object #within_window(proc_or_lambda) ⇒ Object #within_window(string) ⇒ Object

This method does the following:

  1. Switches to the given window (it can be located by window instance/lambda/string).

  2. Executes the given block (within window located at previous step).

  3. Switches back (this step will be invoked even if exception will happen at second step)

Overloads:

  • #within_window(window) ⇒ Object

    Parameters:

    • window (Capybara::Window) —

      instance of ‘Capybara::Window` class that will be switched to

    Raises:

    • (driver#no_such_window_error) —

      if unexistent (e.g. closed) window was passed

  • #within_window(proc_or_lambda) ⇒ Object

    Examples:

    within_window(->{ page.title == 'Page title' }) { click_button 'Submit' }

    Parameters:

    • lambda (Proc) —

      lambda. First window for which lambda returns a value other than false or nil will be switched to.

    Raises:

  • #within_window(string) ⇒ Object
    Deprecated.

    Pass window or lambda instead

    Parameters:

    • handle, (String) —

      name, url or title of the window

Returns:

  • value returned by the block

Raises:

  • (Capybara::ScopeError) —

    if this method is invoked inside ‘within`, `within_frame` or `within_window` methods



440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/capybara/session.rb', line 440

def within_window(window_or_handle)
  if window_or_handle.instance_of?(Capybara::Window)
    original = current_window
    switch_to_window(window_or_handle) unless original == window_or_handle
    scopes << nil
    begin
      yield
    ensure
      @scopes.pop
      switch_to_window(original) unless original == window_or_handle
    end
  elsif window_or_handle.is_a?(Proc)
    original = current_window
    switch_to_window { window_or_handle.call }
    scopes << nil
    begin
      yield
    ensure
      @scopes.pop
      switch_to_window(original)
    end
  else
    offending_line = caller.first
    file_line = offending_line.match(/^(.+?):(\d+)/)[0]
    warn "DEPRECATION WARNING: Passing string argument to #within_window is deprecated. "\
         "Pass window object or lambda. (called from #{file_line})"
    begin
      scopes << nil
      driver.within_window(window_or_handle) { yield }
    ensure
      @scopes.pop
    end
  end
end