{"record":{"id":"9bb9cffea17d5e69","repo":"teamcapybara/capybara","slug":"window-size-not-stable-within-seconds-seconds","errorCode":null,"errorMessage":"Window size not stable within #{seconds} seconds.","messagePattern":"Window size not stable within #(.+?) seconds\\.","errorType":"exception","errorClass":"Capybara::WindowError","httpStatus":null,"severity":"error","filePath":"lib/capybara/window.rb","lineNumber":139,"sourceCode":"      [@session, @handle].hash\n    end\n\n    def inspect\n      \"#<Window @handle=#{@handle.inspect}>\"\n    end\n\n  private\n\n    def wait_for_stable_size(seconds = session.config.default_max_wait_time)\n      res = yield if block_given?\n      timer = Capybara::Helpers.timer(expire_in: seconds)\n      loop do\n        prev_size = size\n        sleep 0.025\n        return res if prev_size == size\n        break if timer.expired?\n      end\n      raise Capybara::WindowError, \"Window size not stable within #{seconds} seconds.\"\n    end\n  end\nend\n","sourceCodeStart":121,"sourceCodeEnd":143,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/window.rb#L121-L143","documentation":"Window#resize_to and Window#maximize call the driver and then poll the window size every 0.025s until two consecutive reads are identical, bounded by default_max_wait_time. If the reported size keeps fluctuating until the timer expires, Capybara raises Capybara::WindowError with this message. It signals an unstable window/viewport, not that the resize command failed outright.","triggerScenarios":"page.current_window.resize_to(1024, 768) or page.current_window.maximize while the window manager or driver keeps reporting changing sizes: continuous CSS/layout thrash affecting the viewport, remote Selenium Grid nodes under load, Xvfb without a window manager (maximize has no stable target), or mobile-emulation viewports.","commonSituations":"CI (headless Chrome, Xvfb, Docker, BrowserStack/Sauce/LambdaTest) where resizing is flaky; default_max_wait_time set low; responsive-design test suites calling resize_to between examples.","solutions":["Retry the resize/maximize once or twice with a short delay; transient driver flakiness usually stabilizes on the second attempt.","Increase Capybara.default_max_wait_time (or the session's default_max_wait_time) so the polling loop has time to settle.","Prefer fixing the window size at driver registration (Selenium chrome args '--window-size=1024,768' or browser options) instead of calling resize_to in CI.","For headless/Xvfb runs, configure a fixed display/screen size so maximize resolves to a deterministic geometry."],"exampleFix":"# before\npage.current_window.resize_to(1024, 768) # raises Capybara::WindowError on flaky CI\n\n# after\nbegin\n  page.current_window.resize_to(1024, 768)\nrescue Capybara::WindowError\n  sleep 0.5\n  retry\nend","handlingStrategy":"retry","validationCode":"def stable_resize_to!(window, width, height, attempts: 3)\n  window.resize_to(width, height)\nrescue Capybara::WindowError\n  attempts -= 1\n  raise if attempts.zero?\n  sleep 0.5\n  retry\nend","typeGuard":null,"tryCatchPattern":"begin\n  page.current_window.resize_to(1024, 768)\nrescue Capybara::WindowError => e\n  sleep 0.5\n  retry if (attempts -= 1).positive? # initialize attempts = 2 before begin\n  raise e # surface persistent instability after bounded retries\nend","preventionTips":["Pin the window size in the driver registration (Selenium chrome args --window-size=W,H) instead of runtime resize on CI.","Keep Capybara.default_max_wait_time generous enough for resize polling on loaded Grid nodes.","Give Xvfb/headless environments a fixed screen geometry so maximize has a deterministic target.","Wrap resize_to/maximize in a bounded retry helper once, in a shared spec helper, rather than ad hoc in each spec."],"tags":["capybara","selenium","browser-window","ci","timeout"],"backgroundTag":"wait-for-condition-timeout","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}