From 11917c2e755a3987f144e828f79ae5af477ad615 Mon Sep 17 00:00:00 2001 From: Dmitry Vorotilin Date: Sun, 15 Nov 2026 07:45:37 -0800 Subject: [PATCH 1/4] feat(browser): add reset: :soft to keep the HTTP cache between tests The default reset disposes the browser context, so every test downloads all assets again. With reset: :soft Cuprite keeps the context and opens a fresh blank window, closes the others and other contexts, clears cookies and clears storage for every origin found in the network traffic. Any failure falls back to the full reset. CUPRITE_RESET=soft runs the suite in soft mode. Refs #128 Co-authored-by: Maxwell Salzberg --- CHANGELOG.md | 2 + README.md | 2 + docs/2-customization.md | 23 ++++++++ lib/capybara/cuprite/browser.rb | 68 +++++++++++++++++++++++- lib/capybara/cuprite/options.rb | 2 +- spec/driver_spec.rb | 93 +++++++++++++++++++++++++++++++++ spec/spec_helper.rb | 9 ++++ spec/support/test_app.rb | 6 +++ spec/unit/driver_spec.rb | 12 +++++ 9 files changed, 215 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 814dbd03..2489f7be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ ## [Unreleased](https://github.com/rubycdp/cuprite/compare/v0.20.1...main) ## ### Added +- `reset: :soft` driver option keeps the browser context and its HTTP cache between tests, clearing cookies, storage + and extra windows instead, so assets aren't downloaded again for every test [#128] - `:url_blocklist` and `:url_allowlist` driver options as aliases for `:url_blacklist` and `:url_whitelist` [#330] ### Changed diff --git a/README.md b/README.md index f8097abe..103b6fb7 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,8 @@ end * `:emulate` (Symbol) - device from Chrome DevTools' list to emulate, e.g. `:iphone_16`, `:pixel_9`, `:ipad_mini` * `:mobile` (Boolean) - emulate a mobile device: viewport meta tag and touch events * `:scale_factor` (Numeric) - device scale factor to emulate + * `:reset` (Symbol) - `:hard` (default) starts every test in a new browser context, `:soft` keeps the context and + its HTTP cache and clears cookies, storage and extra windows instead `emulate:` sets the device's `:window_size`, `:scale_factor`, `:mobile` and user agent, options passed explicitly take precedence: diff --git a/docs/2-customization.md b/docs/2-customization.md index eef5e706..000497f7 100644 --- a/docs/2-customization.md +++ b/docs/2-customization.md @@ -39,6 +39,8 @@ Cuprite-specific options are: by default. Kept across window resizes. * `:scale_factor` (Numeric) - Device scale factor (`window.devicePixelRatio`) to emulate, `0` (browser default) by default. + * `:reset` (Symbol) - How the browser is reset between tests, `:hard` (default) or `:soft`, see + [Soft reset](#soft-reset). Cuprite changes a few Ferrum defaults: @@ -47,6 +49,27 @@ Cuprite changes a few Ferrum defaults: [debug](/docs/cuprite/debugging) can open DevTools, and so is `"disable-web-security" => nil`, so that tests can reach into cross-origin frames. +## Soft reset + +By default every test runs in a new browser context, so each one downloads all the assets again. With `reset: :soft` +Cuprite keeps the context and its HTTP cache, and resets the rest: + +* opens a blank window and closes all the others, together with their session storage, request interception, + headers, authorization, network conditions, modal handlers and running scripts; +* disposes any other browser context; +* clears cookies; +* clears local storage, IndexedDB, service workers, Cache Storage and file systems for every origin the test + requested, as recorded in the network traffic. + +If any step fails, Cuprite falls back to the full reset. + +```ruby +Capybara::Cuprite::Driver.new(app, reset: :soft) +``` + +Origins are taken from `network.traffic`, so clearing it with `network.clear(:traffic)` in a test hides the origins +requested before that from the reset. + ## Examples ```ruby diff --git a/lib/capybara/cuprite/browser.rb b/lib/capybara/cuprite/browser.rb index 6d8db60f..7089b7b7 100644 --- a/lib/capybara/cuprite/browser.rb +++ b/lib/capybara/cuprite/browser.rb @@ -7,6 +7,9 @@ module Cuprite class Browser < Ferrum::Browser include Extensions + RESET_MODES = %i[hard soft].freeze + STORAGE_TYPES = %w[local_storage indexeddb service_workers cache_storage file_systems].join(",") + def initialize(options = nil) device = options&.dig(:emulate) options = Devices.fetch(device).except(:user_agent).merge(options) if device @@ -17,8 +20,10 @@ def initialize(options = nil) @options.raise_on_unhandled_modal = options&.dig(:raise_on_unhandled_modal) @options.url_blacklist = prepare_wildcards(options&.dig(:url_blacklist)) @options.url_whitelist = prepare_wildcards(options&.dig(:url_whitelist)) + @options.reset_mode = prepare_reset_mode(options&.dig(:reset)) @page = nil + @reset_target_id = nil end def command(...) @@ -35,7 +40,9 @@ def page end def reset - super + @options.reset_window_size + forget_page + @options.reset_mode == :soft ? soft_reset : hard_reset ensure @options.reset_window_size forget_page @@ -44,6 +51,7 @@ def reset def quit super forget_page + @reset_target_id = nil end def resize(**options) @@ -87,6 +95,63 @@ def forget_page @page_closed = false end + def hard_reset + @reset_target_id = nil + contexts.reset + end + + def soft_reset + context = default_context + origins = visited_origins(context) + target = context.create_target + close_other_contexts(context) + close_pages(context, except: target) + command("Storage.clearCookies", browserContextId: context.id) + page = attach_page(target.id) + origins.each { |o| page.command("Storage.clearDataForOrigin", origin: o, storageTypes: STORAGE_TYPES) } + @reset_target_id = target.id + rescue Ferrum::Error + hard_reset + end + + def visited_origins(context) + pages = context.targets.values.select(&:page?) + urls = pages.map(&:url) + urls += pages.select(&:connected?).flat_map { |t| t.page.network.traffic.map(&:url) } + urls.filter_map { |url| origin(url) }.uniq + end + + def origin(url) + uri = URI.parse(url.to_s) + return unless %w[http https].include?(uri.scheme) && uri.host + + port = ":#{uri.port}" unless uri.port == uri.default_port + "#{uri.scheme}://#{uri.host}#{port}" + rescue URI::InvalidURIError + nil + end + + def close_other_contexts(context) + contexts.each.map { |id, _| id }.each { |id| contexts.dispose(id) unless id == context.id } + end + + def close_pages(context, except:) + context.targets.values.select(&:page?).each do |target| + next if target.id == except.id + + target.close_connection + command("Target.closeTarget", targetId: target.id) + context.delete_target(target.id) + end + end + + def prepare_reset_mode(mode) + mode ||= :hard + return mode if RESET_MODES.include?(mode) + + raise ArgumentError, "reset must be one of #{RESET_MODES.inspect}, got #{mode.inspect}" + end + def window_target(target_id) target = targets[target_id] raise Ferrum::NoSuchPageError unless target&.page? @@ -95,6 +160,7 @@ def window_target(target_id) end def attach_page(target_id = nil) + target_id ||= @reset_target_id target = targets[target_id] if target_id target ||= default_context.default_target return target.page if target.connected? diff --git a/lib/capybara/cuprite/options.rb b/lib/capybara/cuprite/options.rb index ba1b75f8..ff3e7244 100644 --- a/lib/capybara/cuprite/options.rb +++ b/lib/capybara/cuprite/options.rb @@ -5,7 +5,7 @@ class Browser class Options attr_writer :window_size attr_accessor :url_blacklist, :url_whitelist, :raise_on_unhandled_modal, :raise_on_js_errors, - :raise_on_pending_connections + :raise_on_pending_connections, :reset_mode def mobile @options.fetch(:mobile, nil) diff --git a/spec/driver_spec.rb b/spec/driver_spec.rb index 4548e24c..0d0a0958 100644 --- a/spec/driver_spec.rb +++ b/spec/driver_spec.rb @@ -385,6 +385,99 @@ def session_url(path) JS expect(value).to be_nil end + + context "with reset: :soft" do + around do |example| + @session = TestSessions::CupriteSoftReset + @driver = @session.driver + example.run + ensure + @session.reset! + end + + it "keeps the HTTP cache" do + @session.visit("/cuprite/cacheable") + expect(@driver.browser.network.traffic.last.response.params.dig("response", "fromDiskCache")).to be_falsey + + @session.reset! + @session.visit("/cuprite/cacheable") + + expect(@driver.browser.network.traffic.last.response.params.dig("response", "fromDiskCache")).to be_truthy + end + + it "clears cookies" do + @session.visit("/set_cookie") + expect(@driver.browser.cookies["capybara"]).not_to be_nil + + @session.reset! + @session.visit("/get_cookie") + + expect(@driver.browser.cookies.all).to be_empty + expect(@session.html).not_to include("test_cookie") + end + + it "clears local storage, session storage and IndexedDB" do + @session.visit("/cuprite/simple") + @session.execute_script(<<~JS) + localStorage.setItem("key", "local"); + sessionStorage.setItem("key", "session"); + JS + @session.evaluate_async_script(<<~JS) + const request = indexedDB.open("cuprite_soft_reset"); + request.onsuccess = () => { request.result.close(); arguments[0](); }; + JS + expect(@session.evaluate_async_script(<<~JS)).to include("cuprite_soft_reset") + indexedDB.databases().then((dbs) => arguments[0](dbs.map((db) => db.name))); + JS + + @session.reset! + @session.visit("/cuprite/simple") + + expect(@session.evaluate_script("localStorage.getItem('key')")).to be_nil + expect(@session.evaluate_script("sessionStorage.getItem('key')")).to be_nil + expect(@session.evaluate_async_script(<<~JS)).to be_empty + indexedDB.databases().then((dbs) => arguments[0](dbs.map((db) => db.name))); + JS + end + + it "closes extra windows" do + @session.visit("/cuprite/simple") + @session.switch_to_window(@session.open_new_window) + @session.open_new_window + expect(@session.windows.size).to eq(3) + + @session.reset! + + expect(@session.windows.size).to eq(1) + @session.visit("/cuprite/simple") + expect(@session).to have_content("Foo") + end + + it "drops extra headers and offline mode" do + @driver.browser.headers.set("X-Soft-Reset" => "kept") + @session.visit("/cuprite/headers") + expect(@session).to have_content("SOFT_RESET: kept") + @driver.browser.network.offline_mode + + @session.reset! + @session.visit("/cuprite/headers") + + expect(@session).to have_content("HOST") + expect(@session).not_to have_content("SOFT_RESET") + end + + it "falls back to the full reset when the soft one fails" do + @session.visit("/set_cookie") + context_id = @driver.browser.default_context.id + allow(@driver.browser.default_context).to receive(:create_target).and_raise(Ferrum::TimeoutError) + + @session.reset! + @session.visit("/get_cookie") + + expect(@driver.browser.default_context.id).not_to eq(context_id) + expect(@driver.browser.cookies.all).to be_empty + end + end end describe "#current_url" do diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index ea16b315..39aa51a0 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -29,6 +29,14 @@ options = {} options.merge!(logger: StringIO.new) if ENV["CI"] options.merge!(headless: false) if ENV["HEADLESS"] == "false" + options.merge!(reset: ENV["CUPRITE_RESET"].to_sym) if ENV["CUPRITE_RESET"] + Capybara::Cuprite::Driver.new(app, options) +end + +Capybara.register_driver(:cuprite_soft_reset) do |app| + options = { reset: :soft } + options.merge!(logger: StringIO.new) if ENV["CI"] + options.merge!(headless: false) if ENV["HEADLESS"] == "false" Capybara::Cuprite::Driver.new(app, options) end @@ -43,6 +51,7 @@ module TestSessions Cuprite = Capybara::Session.new(:cuprite, TestApp) CupriteMobile = Capybara::Session.new(:cuprite_mobile, TestApp) + CupriteSoftReset = Capybara::Session.new(:cuprite_soft_reset, TestApp) end RSpec.configure do |config| diff --git a/spec/support/test_app.rb b/spec/support/test_app.rb index 0e78ac65..b107bcd7 100644 --- a/spec/support/test_app.rb +++ b/spec/support/test_app.rb @@ -53,6 +53,12 @@ class TestApp render_string("really slow page") end + get "/cuprite/cacheable" do + cache_control :public, max_age: 60 + etag "deadbeef" + render_string("Cacheable request click me") + end + get "/cuprite/attachment.txt" do attachment "attachment.txt" "attachment contents" diff --git a/spec/unit/driver_spec.rb b/spec/unit/driver_spec.rb index a443fa35..f66575ac 100644 --- a/spec/unit/driver_spec.rb +++ b/spec/unit/driver_spec.rb @@ -31,6 +31,18 @@ expect(driver.browser.options.to_h).to include(save_path: custom_path) end + + it "resets with a new browser context by default" do + driver = described_class.new(nil) + + expect(driver.browser.options.reset_mode).to eq(:hard) + end + + it "rejects an unknown reset mode" do + driver = described_class.new(nil, reset: :partial) + + expect { driver.browser }.to raise_error(ArgumentError, /reset must be one of/) + end end describe "#reset!" do From c8f74ba4b64af9caca2e165e98f0bdfd5c263e0b Mon Sep 17 00:00:00 2001 From: Maxwell Salzberg Date: Sun, 15 Nov 2026 07:46:28 -0800 Subject: [PATCH 2/4] test(driver): cover the state a soft reset drops with the old window Capybara's Session#reset! resets the driver before it waits for pending server requests, so a response can set a cookie after the soft reset clears them. Page timers, an unused modal response and window size, device and media emulation also live in the old window. Each example passes because the soft reset closes the old window and opens a new one. The in-flight request example fails when the old window is left open, and the other three fail when the current window is reused. --- spec/driver_spec.rb | 55 ++++++++++++++++++++++++++++++++++++++++ spec/support/test_app.rb | 6 +++++ 2 files changed, 61 insertions(+) diff --git a/spec/driver_spec.rb b/spec/driver_spec.rb index 0d0a0958..0163ee47 100644 --- a/spec/driver_spec.rb +++ b/spec/driver_spec.rb @@ -440,6 +440,61 @@ def session_url(path) JS end + it "drops cookies set by a request still in flight when the reset starts" do + leaked = 10.times.count do + @session.visit("/cuprite/simple") + @session.execute_script("fetch('/cuprite/slow_cookie')") + sleep 0.005 until @driver.browser.network.traffic.any? { |e| e.url.include?("slow_cookie") } + + @session.reset! + @session.visit("/cuprite/simple") + sleep 0.2 + @driver.browser.cookies["late"] + end + + expect(leaked).to eq(0) + end + + it "stops scripts the previous page left running" do + @session.visit("/cuprite/simple") + @session.execute_script("setInterval(() => { document.cookie = 'late=arrival; path=/' }, 0)") + + @session.reset! + @session.visit("/cuprite/simple") + sleep 0.1 + + expect(@driver.browser.cookies["late"]).to be_nil + end + + it "forgets a modal the previous test never asserted on" do + @session.visit("/cuprite/simple") + @driver.browser.page.accept_confirm + @session.execute_script("setTimeout(() => confirm('left behind'), 0)") + sleep 0.2 + + @session.reset! + @session.visit("/cuprite/simple") + + expect { @session.accept_confirm("left behind", wait: 0.5) { nil } }.to raise_error(Capybara::ModalNotFound) + end + + it "restores the window size and drops device and media emulation" do + @session.visit("/cuprite/simple") + dark = @session.evaluate_script("matchMedia('(prefers-color-scheme: dark)').matches") + @session.current_window.resize_to(402, 874) + @driver.browser.page.command("Emulation.setDeviceMetricsOverride", + width: 375, height: 600, deviceScaleFactor: 2, mobile: true) + @driver.browser.page.command("Emulation.setEmulatedMedia", + features: [{ name: "prefers-color-scheme", value: dark ? "light" : "dark" }]) + + @session.reset! + @session.visit("/cuprite/simple") + + expect(@session.evaluate_script("window.innerWidth")).to eq(@driver.browser.options.window_size[0]) + expect(@session.evaluate_script("window.devicePixelRatio")).to eq(1) + expect(@session.evaluate_script("matchMedia('(prefers-color-scheme: dark)').matches")).to eq(dark) + end + it "closes extra windows" do @session.visit("/cuprite/simple") @session.switch_to_window(@session.open_new_window) diff --git a/spec/support/test_app.rb b/spec/support/test_app.rb index b107bcd7..81000c35 100644 --- a/spec/support/test_app.rb +++ b/spec/support/test_app.rb @@ -53,6 +53,12 @@ class TestApp render_string("really slow page") end + get "/cuprite/slow_cookie" do + sleep 0.1 + response.set_cookie("late", value: "arrival", path: "/") + render_string("slow cookie") + end + get "/cuprite/cacheable" do cache_control :public, max_age: 60 etag "deadbeef" From 56e63fed86d7a1177561814a4bbca4f4cfbcaba4 Mon Sep 17 00:00:00 2001 From: Maxwell Salzberg Date: Sun, 15 Nov 2026 09:49:23 -0800 Subject: [PATCH 3/4] fix(browser): clear storage of windows closed before a soft reset The soft reset collected origins from the windows still open and their network traffic. close_window removes the target, so an origin a test opened in a window and closed before the reset kept its storage into the next test. close_window now remembers the window's origins, and the next soft reset clears them. --- lib/capybara/cuprite/browser.rb | 14 +++++++++++--- spec/driver_spec.rb | 16 ++++++++++++++++ 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/lib/capybara/cuprite/browser.rb b/lib/capybara/cuprite/browser.rb index 7089b7b7..23b5a98e 100644 --- a/lib/capybara/cuprite/browser.rb +++ b/lib/capybara/cuprite/browser.rb @@ -24,6 +24,7 @@ def initialize(options = nil) @page = nil @reset_target_id = nil + @closed_window_origins = [] end def command(...) @@ -84,6 +85,7 @@ def close_window(target_id) forget_page @page_closed = true end + @closed_window_origins |= target_origins(target) target.page.close targets.delete(target_id) # page.close is async, delete target asap end @@ -97,6 +99,7 @@ def forget_page def hard_reset @reset_target_id = nil + @closed_window_origins = [] contexts.reset end @@ -109,6 +112,7 @@ def soft_reset command("Storage.clearCookies", browserContextId: context.id) page = attach_page(target.id) origins.each { |o| page.command("Storage.clearDataForOrigin", origin: o, storageTypes: STORAGE_TYPES) } + @closed_window_origins = [] @reset_target_id = target.id rescue Ferrum::Error hard_reset @@ -116,9 +120,13 @@ def soft_reset def visited_origins(context) pages = context.targets.values.select(&:page?) - urls = pages.map(&:url) - urls += pages.select(&:connected?).flat_map { |t| t.page.network.traffic.map(&:url) } - urls.filter_map { |url| origin(url) }.uniq + (pages.flat_map { |target| target_origins(target) } + @closed_window_origins).uniq + end + + def target_origins(target) + urls = [target.url] + urls += target.page.network.traffic.map(&:url) if target.connected? + urls.filter_map { |url| origin(url) } end def origin(url) diff --git a/spec/driver_spec.rb b/spec/driver_spec.rb index 0163ee47..9d413063 100644 --- a/spec/driver_spec.rb +++ b/spec/driver_spec.rb @@ -508,6 +508,22 @@ def session_url(path) expect(@session).to have_content("Foo") end + it "clears storage of an origin whose window closed before the reset" do + other_origin = "http://localhost:#{@session.server.port}/cuprite/simple" + @session.visit("/cuprite/simple") + popup = @session.open_new_window + @session.within_window(popup) do + @session.visit(other_origin) + @session.execute_script("localStorage.setItem('key', 'left behind')") + end + popup.close + + @session.reset! + @session.visit(other_origin) + + expect(@session.evaluate_script("localStorage.getItem('key')")).to be_nil + end + it "drops extra headers and offline mode" do @driver.browser.headers.set("X-Soft-Reset" => "kept") @session.visit("/cuprite/headers") From 11579c329649b43516f61745d68cded6b78d241a Mon Sep 17 00:00:00 2001 From: Maxwell Salzberg Date: Mon, 16 Nov 2026 08:45:33 -0800 Subject: [PATCH 4/4] fix(browser): wait for closed windows to go before clearing cookies Target.closeTarget returns before Chrome has torn the page down. A busy page kept running for a few milliseconds and could set a cookie, and a response arriving in that window could store one, after the soft reset had cleared them. The soft reset now waits until the closed targets leave Target.getTargets, up to the browser timeout, before it clears cookies. A timeout falls back to the full reset like any other soft reset error. "clears cookies only after the old windows are gone" failed in 4 of 8 runs under full CPU load without the wait and passed 8 of 8 with it. --- lib/capybara/cuprite/browser.rb | 17 ++++++++++++++++- spec/driver_spec.rb | 21 +++++++++++++++++++++ 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/lib/capybara/cuprite/browser.rb b/lib/capybara/cuprite/browser.rb index 23b5a98e..5a8c33cc 100644 --- a/lib/capybara/cuprite/browser.rb +++ b/lib/capybara/cuprite/browser.rb @@ -144,13 +144,28 @@ def close_other_contexts(context) end def close_pages(context, except:) - context.targets.values.select(&:page?).each do |target| + closed_ids = context.targets.values.select(&:page?).filter_map do |target| next if target.id == except.id target.close_connection command("Target.closeTarget", targetId: target.id) context.delete_target(target.id) + target.id end + wait_until_targets_gone(closed_ids) + end + + def wait_until_targets_gone(ids) + deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + timeout + while open_target_ids.intersect?(ids) + raise Ferrum::TimeoutError if ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) > deadline + + sleep 0.005 + end + end + + def open_target_ids + command("Target.getTargets")["targetInfos"].map { |info| info["targetId"] } end def prepare_reset_mode(mode) diff --git a/spec/driver_spec.rb b/spec/driver_spec.rb index 9d413063..f04ebe00 100644 --- a/spec/driver_spec.rb +++ b/spec/driver_spec.rb @@ -508,6 +508,27 @@ def session_url(path) expect(@session).to have_content("Foo") end + it "clears cookies only after the old windows are gone" do + open_at_clear = [] + old_ids = [] + allow(@driver.browser).to receive(:command).and_wrap_original do |original, method, **params| + if method == "Storage.clearCookies" + ids = original.call("Target.getTargets")["targetInfos"].map { |info| info["targetId"] } + open_at_clear.concat(ids & old_ids) + end + original.call(method, **params) + end + + 10.times do + @session.visit("/cuprite/simple") + @session.execute_script("setInterval(() => { document.cookie = 'late=arrival; path=/' }, 0)") + old_ids = @driver.browser.window_handles + @session.reset! + end + + expect(open_at_clear).to eq([]) + end + it "clears storage of an origin whose window closed before the reset" do other_origin = "http://localhost:#{@session.server.port}/cuprite/simple" @session.visit("/cuprite/simple")