Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
23 changes: 23 additions & 0 deletions docs/2-customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down
91 changes: 90 additions & 1 deletion lib/capybara/cuprite/browser.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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(...)
Expand All @@ -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
Expand All @@ -44,6 +52,7 @@ def reset
def quit
super
forget_page
@reset_target_id = nil
end

def resize(**options)
Expand Down Expand Up @@ -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
Expand All @@ -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?
Expand All @@ -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?
Expand Down
2 changes: 1 addition & 1 deletion lib/capybara/cuprite/options.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
185 changes: 185 additions & 0 deletions spec/driver_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading