Method: Capybara::Session#within_window

Defined in:
lib/capybara/session.rb

#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



488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
# File 'lib/capybara/session.rb', line 488

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