diff --git a/CHANGELOG.md b/CHANGELOG.md index 814dbd0..2489f7b 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 f8097ab..103b6fb 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 eef5e70..000497f 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 6d8db60..5a8c33c 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,11 @@ 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 + @closed_window_origins = [] end def command(...) @@ -35,7 +41,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 +52,7 @@ def reset def quit super forget_page + @reset_target_id = nil end def resize(**options) @@ -76,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 @@ -87,6 +97,84 @@ def forget_page @page_closed = false end + def hard_reset + @reset_target_id = nil + @closed_window_origins = [] + 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) } + @closed_window_origins = [] + @reset_target_id = target.id + rescue Ferrum::Error + hard_reset + end + + def visited_origins(context) + pages = context.targets.values.select(&:page?) + (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) + 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:) + 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) + 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 +183,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 ba1b75f..ff3e724 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 4548e24..f04ebe0 100644 --- a/spec/driver_spec.rb +++ b/spec/driver_spec.rb @@ -385,6 +385,191 @@ 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 "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) + @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 "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") + 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") + 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 ea16b31..39aa51a 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 0e78ac6..81000c3 100644 --- a/spec/support/test_app.rb +++ b/spec/support/test_app.rb @@ -53,6 +53,18 @@ 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" + 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 a443fa3..f66575a 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