{"record":{"id":"639fa9fa9563fb33","repo":"teamcapybara/capybara","slug":"within-window-requires-a-capybara-window-ins","errorCode":null,"errorMessage":"`#within_window` requires a `Capybara::Window` instance or a lambda","messagePattern":"`#within_window` requires a `Capybara::Window` instance or a lambda","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/capybara/session.rb","lineNumber":555,"sourceCode":"    #     returns a value other than false or nil will be switched to.\n    #   @example\n    #     within_window(->{ page.title == 'Page title' }) { click_button 'Submit' }\n    #   @raise [Capybara::WindowError]         if no window matching lambda was found\n    #\n    # @raise [Capybara::ScopeError]        if this method is invoked inside {#within_frame} method\n    # @return                              value returned by the block\n    #\n    def within_window(window_or_proc)\n      original = current_window\n      scopes << nil\n      begin\n        case window_or_proc\n        when Capybara::Window\n          _switch_to_window(window_or_proc) unless original == window_or_proc\n        when Proc\n          _switch_to_window { window_or_proc.call }\n        else\n          raise ArgumentError, '`#within_window` requires a `Capybara::Window` instance or a lambda'\n        end\n\n        begin\n          yield if block_given?\n        ensure\n          _switch_to_window(original) unless original == window_or_proc\n        end\n      ensure\n        scopes.pop\n      end\n    end\n\n    ##\n    # Get the window that has been opened by the passed block.\n    # It will wait for it to be opened (in the same way as other Capybara methods wait).\n    # It's better to use this method than `windows.last`\n    # {https://dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html#h_note_10 as order of windows isn't defined in some drivers}.\n    #","sourceCodeStart":537,"sourceCodeEnd":573,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/session.rb#L537-L573","documentation":"within_window accepts a Capybara::Window instance or a Proc/lambda used as a window locator; anything else raises ArgumentError. The common trigger is a plain String - the Capybara 1.x API allowed within_window('window_name'), which 2.x+ rejects.","triggerScenarios":"within_window('popup') { ... } left over from Capybara 1.x; passing a window handle String or a Symbol; passing page.windows.first.title as the target.","commonSituations":"Suite upgrades from Capybara 1.x to 2.x+; blog/docs examples predating the API change; old helpers that returned window names being passed through.","solutions":["Pass a Window object: within_window(page.windows.last) { ... }","Or a locator lambda: within_window(-> { title == 'popup' }) { ... }","During upgrades, grep the suite for within_window(' to catch every 1.x-style call"],"exampleFix":"# before (Capybara 1.x style)\nwithin_window('popup') { click_link 'Close' }\n\n# after\nwithin_window(-> { title == 'popup' }) { click_link 'Close' }\n# or\nwithin_window(page.windows.last) { click_link 'Close' }","handlingStrategy":"type-guard","validationCode":"raise ArgumentError, 'Window or lambda required' unless window_or_proc.is_a?(Capybara::Window) || window_or_proc.is_a?(Proc)\nwithin_window(window_or_proc) { click_link 'Close' }","typeGuard":"def window_target?(obj)\n  obj.is_a?(Capybara::Window) || obj.is_a?(Proc)\nend","tryCatchPattern":"begin\n  within_window(target) { yield }\nrescue ArgumentError\n  within_window(-> { title == target }) { yield } # target was a title string\nend","preventionTips":["Grep for string arguments to within_window when upgrading from Capybara 1.x","Store Window objects or title-matching lambdas in page-object accessors"],"tags":["windows","within-window","capybara-1-x-upgrade","argument-validation"],"backgroundTag":"api-upgrade-breaking-change","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}