teamcapybara/capybara · error · ArgumentError

`switch_to_window`: either window or block should be provide

Error message

`switch_to_window`: either window or block should be provided

What it means

switch_to_window requires exactly one of a window argument or a locator block; calling it with neither raises ArgumentError immediately. This usually means a variable meant to hold a Window was nil, or the call was written as a bare 'focus the other window' habit from other APIs.

Source

Thrown at lib/capybara/session.rb:514

    #
    # @overload switch_to_window(&block)
    #   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 {Capybara::WindowError} will be raised.
    #   @example
    #     window = switch_to_window { title == 'Page title' }
    #   @raise [Capybara::WindowError]     if no window matches given block
    # @overload switch_to_window(window)
    #   @param window [Capybara::Window]   window that should be switched to
    #   @raise [Capybara::Driver::Base#no_such_window_error] if nonexistent (e.g. closed) window was passed
    #
    # @return [Capybara::Window]         window that has been switched to
    # @raise [Capybara::ScopeError]        if this method is invoked inside {#within} or
    #   {#within_frame} methods
    # @raise [ArgumentError]               if both or neither arguments were provided
    #
    def switch_to_window(window = nil, **options, &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, **options, &window_locator)
    end

    ##
    # 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 an exception occurs at the second step).
    #
    # @overload within_window(window) { do_something }
    #   @param window [Capybara::Window]       instance of {Capybara::Window} class

View on GitHub (pinned to 15b5fdb76e)

Solutions

1. Provide one: switch_to_window { title == 'Chat' } or switch_to_window(stored_window)
2. If you wanted the current window, use page.current_window instead of switching
3. Guard nils from lookups: switch_to_window(win) if win

Example fix

# before
switch_to_window # nothing given

# after
switch_to_window { title == 'Chat' }
# or, with a stored window:
switch_to_window(popup_window) if popup_window

raise ArgumentError, 'window or block required' if window.nil? && !block_given?
switch_to_window(window, &blk)

When it happens

Trigger: A bare switch_to_window with no argument and no block; switch_to_window(@popup) where @popup was never assigned (nil after a failed window_opened_by, for example).

Common situations: Nil window variables after a rescue or failed lookup; stubs/mocks returning nil; team members expecting switch_to_window to focus 'the other window' by default.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• `switch_to_window` can take either a block or a window, not
• `switch_to_window` is not supposed to be invoked from `withi
• Window cannot be switched inside a `within_frame` block
• Could not find a window matching block/lambda
• `#within_window` requires a `Capybara::Window` instance or a

AI-assisted analysis of teamcapybara/capybara@15b5fdb76e (2026-08-21). Data as JSON: /api/errors/ee98e5b9ad72e421. Report an issue: GitHub.