Class: Capybara::Simulated::Driver

Inherits:
Driver::Base
  • Object
show all
Defined in:
lib/capybara/simulated/driver.rb

Defined Under Namespace

Classes: FakePlaywrightLocator, FakePlaywrightPage

Constant Summary collapse

PRIMARY_HANDLE =

Per-window Browser/VM. open_aux_window creates a fresh Browser sharing the Driver's cookie + localStorage jars (origin-shared in real browsers) and visits the target URL; switch_to_window flips @active_handle so subsequent driver ops route through current_browser. sessionStorage + DOM + history + the JS VM stay per-window.

'csim-window-0'
@@live_lock = 
Mutex.new
@@live =

[WeakRef] — dead refs filtered on read.

[]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(app, js_engine: nil, viewport: nil, user_agent: nil) ⇒ Driver

viewport: [w, h] and user_agent: (typically supplied via Capybara.register_driver) force the JS-side innerWidth/innerHeight and navigator.userAgent (plus HTTP_USER_AGENT on Rack requests) before the first navigate, so matchMedia / mobile-breakpoint branches and server-side UA-based mobile detection both resolve before any document loads. The Browser tracks both as "defaults" so reset! (per-test teardown) restores them between specs.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/capybara/simulated/driver.rb', line 69

def initialize(app, js_engine: nil, viewport: nil, user_agent: nil)
  @app             = app
  @js_engine       = js_engine
  # Cookies + localStorage are origin-shared across windows
  # (real browser semantics), so we own the jars at the Driver
  # level and inject them into every per-window Browser. Each
  # Browser still has its own sessionStorage + DOM + JS VM.
  @cookies         = {}
  @auth_cache      = {}
  @local_storage   = {}
  # Cache Storage (caches/Cache) is origin-shared like localStorage — owned at the
  # Driver level and injected, so a service worker and every same-origin window see
  # the same caches (partitioned by origin key within the store).
  @cache_storage   = {}
  # Capture the universal-server flag ONCE, at session construction — the WPT
  # runner sets CSIM_LOCAL_ALL_HOSTS only while building the session, then
  # restores it. Every window (incl. aux windows opened later) inherits this so
  # cross-origin iframes eager-build consistently across the whole session.
  @all_hosts_local = ENV['CSIM_LOCAL_ALL_HOSTS'] == '1'
  @browser         = build_window_browser
  @browser.window_handle = PRIMARY_HANDLE
  @aux_windows     = []  # [{handle:, browser:, name:, opener:}, …]
  @active_handle   = nil
  @next_window_seq = 0
  # Driver-level blob URL partition map: url => {browser:, site:}. A blob URL's
  # storage partition is its creating context's top-level SITE; another window
  # can resolve the blob only from the same partition (and same origin, which
  # the blob: URL embeds). Bytes aren't copied here — they're read back from the
  # creating Browser's own store, so this stays a light reference map.
  @blob_partitions      = {}
  @blob_partitions_lock = Mutex.new
  @owner_thread    = Thread.current
  @@live_lock.synchronize { @@live << WeakRef.new(self) }
  @browser.default_viewport   = viewport   if viewport
  @browser.default_user_agent = user_agent if user_agent
end

Instance Attribute Details

#app ⇒ Object (readonly)

Returns the value of attribute app.



45
46
47
 
# File 'lib/capybara/simulated/driver.rb', line 45

def app
  @app
end

#browser ⇒ Object (readonly)

Returns the value of attribute browser.



132
133
134
 
# File 'lib/capybara/simulated/driver.rb', line 132

def browser
  @browser
end

#owner_thread ⇒ Object (readonly)

Returns the value of attribute owner_thread.



45
46
47
 
# File 'lib/capybara/simulated/driver.rb', line 45

def owner_thread
  @owner_thread
end

Class Method Details

.each_live_on_thread(thread) ⇒ Object 



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/capybara/simulated/driver.rb', line 50

def self.each_live_on_thread(thread)
  drivers = @@live_lock.synchronize {
    @@live.select!(&:weakref_alive?)
    @@live.filter_map {|ref| ref.__getobj__ rescue nil }
  }
  # A DISPOSED driver is not live: its runtime context is gone, so calling into it raises
  # (`undefined method 'call' for nil` out of `run_loop_step`). `dispose` deregisters, but the
  # predicate is the belt — a WeakRef stays in the list until GC actually collects.
  drivers.each {|d| yield d if d.owner_thread == thread && !d.disposed? }
end

Instance Method Details

#accept_modal(type, **options, &block) ⇒ Object 



767
 
# File 'lib/capybara/simulated/driver.rb', line 767

def accept_modal(type, **options, &block) = run_modal(type, accept: true, **options, &block)

#active_element ⇒ Object 



739
740
741
742
 
# File 'lib/capybara/simulated/driver.rb', line 739

def active_element
  handle = current_browser.active_element_handle
  handle ? Node.new(self, handle) : nil
end

#blob_bytes_for(url, accessor) ⇒ Object

Resolve a blob: URL's bytes from whichever Browser created it (the bytes live in the creator's isolate, not necessarily the navigator's). Used to load a blob document into a TOP-LEVEL window (window.open / a window navigation): that new context is the blob's own partition, so no partition gate applies here — the cross-partition rule for windows is the noopener severing above, and for nested frames it is enforced at the frame-navigation site. Falls back to the accessor's own store for an unpartitioned URL (worker / legacy path).



490
491
492
493
494
 
# File 'lib/capybara/simulated/driver.rb', line 490

def blob_bytes_for(url, accessor)
  entry = @blob_partitions_lock.synchronize { @blob_partitions[url.to_s] }
  creator = entry ? entry[:browser] : accessor
  creator.respond_to?(:read_blob_for_window) ? creator.read_blob_for_window(url) : nil
end

#blob_partition_site_of(url) ⇒ Object

The storage-partition site a blob: URL was created in (its creator's top-level site), or nil for an unknown / revoked / unpartitioned URL.



470
471
472
473
 
# File 'lib/capybara/simulated/driver.rb', line 470

def blob_partition_site_of(url)
  e = @blob_partitions_lock.synchronize { @blob_partitions[url.to_s] }
  e && e[:site]
end

#broadcast_channel(source_browser, name, data, origin = nil) ⇒ Object

BroadcastChannel.postMessage — deliver to every OTHER window's channels with the same name (same-window delivery is handled in-VM by the sender).



548
549
550
551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/capybara/simulated/driver.rb', line 548

def broadcast_channel(source_browser, name, data, origin = nil)
  # An opaque origin is unique to its own agent cluster; its key is a token ('opaque:…') minted
  # per-realm and therefore only unique WITHIN one isolate — two unrelated opaque contexts in
  # DIFFERENT windows could mint the same token. A BroadcastChannel never bridges two distinct
  # opaque origins, and no opaque origin spans separate top-level windows here, so a cross-
  # WINDOW post from an opaque origin reaches no one: drop it rather than risk a cross-isolate
  # token collision. (Same-isolate opaque peers are reached in-VM / via enqueue_broadcast; an
  # inherited-origin blob worker via its own inbox — neither goes through this cross-window path.)
  return if origin.to_s.start_with?('opaque:')
  window_entries.each do |w|
    next if w[:browser].equal?(source_browser)
    w[:browser].enqueue_broadcast(name, data, nil, origin)
  end
end

#close_window(h) ⇒ Object 



663
664
665
666
667
668
669
670
671
672
 
# File 'lib/capybara/simulated/driver.rb', line 663

def close_window(h)
  return if h == PRIMARY_HANDLE
  @aux_windows.reject! {|w|
    next false unless w[:handle] == h
    drop_blob_partitions_for(w[:browser])   # don't leave entries pointing at a disposed VM
    w[:browser].dispose rescue nil
    true
  }
  @active_handle = nil if @active_handle == h
end

#cross_partition_blob?(url, accessor) ⇒ Boolean

Is this blob: URL in a different storage partition than accessor's top-level site? Unknown blobs (no entry) are treated as same-partition (no extra gating beyond the existing same-origin behaviour).

Returns:

  • (Boolean) 


478
479
480
481
 
# File 'lib/capybara/simulated/driver.rb', line 478

def cross_partition_blob?(url, accessor)
  site = blob_partition_site_of(url)
  !site.nil? && site != accessor.blob_partition_site
end

#current_browser ⇒ Object

Active window's Browser. Primary by default; switches when the test calls switch_to_window(aux_handle). Every DOM / URL / JS-touching driver method routes through here so per-window state (DOM, sessionStorage, history) stays window-scoped.



138
139
140
141
142
 
# File 'lib/capybara/simulated/driver.rb', line 138

def current_browser
  return @browser unless @active_handle
  w = @aux_windows.find {|win| win[:handle] == @active_handle }
  w ? w[:browser] : @browser
end

#current_trace ⇒ Object 



130
 
# File 'lib/capybara/simulated/driver.rb', line 130

def current_trace = browser.trace || browser.pending_trace

#current_url ⇒ Object 



331
 
# File 'lib/capybara/simulated/driver.rb', line 331

def current_url          = current_browser.current_url || ''

#current_window_handle ⇒ Object 



362
 
# File 'lib/capybara/simulated/driver.rb', line 362

def current_window_handle    = @active_handle || PRIMARY_HANDLE

#dismiss_modal(type, **options, &block) ⇒ Object 



768
 
# File 'lib/capybara/simulated/driver.rb', line 768

def dismiss_modal(type, **options, &block) = run_modal(type, accept: false, **options, &block)

#dispose ⇒ Object

Full teardown of the whole driver: aux windows AND the primary browser's V8 isolate. reset_windows! deliberately keeps the primary alive (the per-test reset path rebuilds only its page); this is for permanently DROPPING a session. A caller that nils its session without this leaks the primary isolate — with its heap, canvas pixel buffers, and worker threads — into V8Runtime's process-wide @@live until at_exit. The WPT runner recycles the cross-origin session per .sub./.https. file, so that leak is ~one isolate per cross-origin file (hundreds over the suite); disposing here incrementally is what reset_windows! already does for aux windows.



315
316
317
318
319
320
321
322
323
 
# File 'lib/capybara/simulated/driver.rb', line 315

def dispose
  return if @disposed
  @disposed = true
  # Drop out of the live registry FIRST: everything below tears down the runtime this driver
  # would be asked to step if `each_live_on_thread` still yielded it.
  @@live_lock.synchronize { @@live.reject! {|ref| (ref.__getobj__ rescue nil).equal?(self) } }
  reset_windows!
  @browser.dispose rescue nil
end

#disposed? ⇒ Boolean

Has this driver been permanently dropped? (A reset! between examples does NOT set this — that rebuilds the page on a live runtime.)

Returns:

  • (Boolean) 


327
 
# File 'lib/capybara/simulated/driver.rb', line 327

def disposed? = @disposed == true

#evaluate_async_script(script, *args) ⇒ Object 



716
717
718
 
# File 'lib/capybara/simulated/driver.rb', line 716

def evaluate_async_script(script, *args)
  unwrap(current_browser.evaluate_async_script(script, args))
end

#evaluate_script(script, *args) ⇒ Object 



701
702
703
 
# File 'lib/capybara/simulated/driver.rb', line 701

def evaluate_script(script, *args)
  unwrap(current_browser.evaluate_script(script, args))
end

#execute_script(script, *args) ⇒ Object

Capybara's execute_script contract is "run it, discard the return". Route through a no-return JS path so a script that returns a non-marshallable value (jQuery $('…').text('…') returns a chainable jQuery object that the engine's value filter recurses into until it stack-overflows) doesn't blow up on the way back.



711
712
713
714
 
# File 'lib/capybara/simulated/driver.rb', line 711

def execute_script(script, *args)
  current_browser.execute_script(script, args)
  nil
end

#find_css(query, **_) ⇒ Object 



342
343
344
 
# File 'lib/capybara/simulated/driver.rb', line 342

def find_css(query, **_)
  current_browser.find_css(query).map {|id| Node.new(self, id) }
end

#find_xpath(query, **_) ⇒ Object 



338
339
340
 
# File 'lib/capybara/simulated/driver.rb', line 338

def find_xpath(query, **_)
  current_browser.find_xpath(query).map {|id| Node.new(self, id) }
end

#fire_aux_window_load(handle) ⇒ Object

Cross-window remote-ref RPC: route a node/object proxy op to the window that owns the ref (handle), executing in that window's VM.



584
 
# File 'lib/capybara/simulated/driver.rb', line 584

def fire_aux_window_load(handle)             = ((b = window_browser(handle)) && b.fire_own_window_load)

#fullscreen_window(handle) ⇒ Object 



695
 
# File 'lib/capybara/simulated/driver.rb', line 695

def fullscreen_window(handle) = restore_window_size(handle)

#go_back ⇒ Object 



328
 
# File 'lib/capybara/simulated/driver.rb', line 328

def go_back              = current_browser.go_back

#go_forward ⇒ Object 



329
 
# File 'lib/capybara/simulated/driver.rb', line 329

def go_forward           = current_browser.go_forward

#header(name, value) ⇒ Object 



336
 
# File 'lib/capybara/simulated/driver.rb', line 336

def header(name, value)  = current_browser.set_header(name, value)

#html ⇒ Object 



332
 
# File 'lib/capybara/simulated/driver.rb', line 332

def html                 = current_browser.html

#invalid_element_errors ⇒ Object 



731
 
# File 'lib/capybara/simulated/driver.rb', line 731

def invalid_element_errors = [Capybara::Simulated::StaleElement]

#javascript_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


145
 
# File 'lib/capybara/simulated/driver.rb', line 145

def javascript_enabled? = true

#maximize_window(handle) ⇒ Object

Both restore the window to the display it lives on (Browser#screen_size), which is where it started — so they undo a resize_to rather than doing nothing. Coarse: we model no window chrome, so a maximized window and a fullscreen one end up the same size (a real browser's fullscreen is taller by the chrome it hides).



694
 
# File 'lib/capybara/simulated/driver.rb', line 694

def maximize_window(handle)   = restore_window_size(handle)

#needs_server? ⇒ Boolean

Returns:

  • (Boolean) 


144
 
# File 'lib/capybara/simulated/driver.rb', line 144

def needs_server?       = false

#no_such_window_error ⇒ Object 



732
 
# File 'lib/capybara/simulated/driver.rb', line 732

def no_such_window_error   = Capybara::WindowError

#open_aux_window(url = nil, name: nil, opener_handle: nil, source: nil, blob_snapshot: nil, post: nil, opener: false, referrer: nil) ⇒ Object

Open (or, by name, reuse) an auxiliary window. target="_blank" clicks and window.open both land here. A non-empty name that matches an existing window navigates that window instead of opening a new one (HTML window-name targeting); opener_handle records the opener so the new window's window.opener resolves back to it.



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'lib/capybara/simulated/driver.rb', line 388

def open_aux_window(url = nil, name: nil, opener_handle: nil, source: nil, blob_snapshot: nil, post: nil, opener: false, referrer: nil)
  name = name.to_s
  # A blob: URL opened from a different storage partition is forced noopener
  # (cross-partition-navigation), overriding an explicit rel=opener — the new
  # top-level window is the blob's own partition (so the blob still loads), but
  # the opener relationship is severed.
  opener = false if opener && url.to_s.start_with?('blob:') && source && cross_partition_blob?(url, source)
  # A `<form target>` keeps its opener by default (unlike a `target=_blank`
  # LINK, which is noopener) — resolve the opener handle from the source.
  opener_handle ||= handle_for(source) if opener && source
  if !name.empty? && (existing = @aux_windows.find {|w| w[:name] == name })
    if post
      existing[:browser].navigate_post(url, post[:body], post[:content_type], referer: referrer)
    else
      navigate_window(existing[:browser], url, source: source)
    end
    return existing[:handle]
  end
  @next_window_seq += 1
  handle = "csim-window-#{@next_window_seq}"
  aux = build_window_browser
  aux.window_handle = handle
  # Register BEFORE visiting: the opened document's own boot scripts read
  # `window.opener`, which resolves through this entry — so the entry
  # (with its opener) must exist before `visit` runs those scripts.
  @aux_windows << {handle: handle, browser: aux, name: name, opener: opener_handle}
  if url && !url.empty?
    if post
      # A `<form target=_blank method=post>` loads the new window via POST,
      # carrying the opener's URL as referrer (unless rel=noreferrer → '').
      aux.navigate_post(url, post[:body], post[:content_type], referer: referrer)
    # A blob: URL isn't rack-navigable and its bytes live in the OPENER's
    # isolate — load the document directly from a click-time snapshot (a
    # deferred target=_blank nav may revoke the URL first) or, failing that,
    # the opener's blob store.
    elsif !(url.to_s.start_with?('blob:') && load_blob_into_window(aux, url, source, snapshot: blob_snapshot))
      # A form submission carries a referrer (the opener's URL) unless the
      # form opted out via rel=noreferrer (referrer: '').
      aux.visit(url, referer: referrer)
    end
  end
  handle
rescue StandardError => e
  # Aux window URL-load failure (binary content, network error, …)
  # shouldn't tear down the test — the handle is already recorded so
  # `window_opened_by` succeeds; within_window assertions on
  # `current_url` may still pass through whatever `visit` managed to set
  # before raising.
  warn "[csim] open_aux_window(#{url.inspect}) raised: #{e.class}: #{e.message[0, 200]}"
  handle
end

#open_new_window(_kind = :tab) ⇒ Object

Capybara Session#open_new_window(:tab) entry point — opens at about:blank (so current_url/title match a real new tab) and the test then switch_to_window + visits the real URL. We don't distinguish :tab from :window (no window-chrome semantics here).



652
653
654
 
# File 'lib/capybara/simulated/driver.rb', line 652

def open_new_window(_kind = :tab)
  open_aux_window('about:blank')
end

#open_window_from_js(opener_browser, url, name, opener_realm_id = 0, about_base = nil, about_origin = nil) ⇒ Object

window.open(url, name) from the opener window's JS. Resolves the URL against the opener's document and records the opener relationship.



446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
 
# File 'lib/capybara/simulated/driver.rb', line 446

def open_window_from_js(opener_browser, url, name, opener_realm_id = 0, about_base = nil, about_origin = nil)
  resolved = url.to_s.empty? ? nil : opener_browser.resolve_document_url(url)
  # Opening a blob: URL whose storage partition differs from the opener's
  # top-level site is forced NOOPENER (cross-partition-navigation): the new
  # auxiliary window is its own top-level context in the blob's partition, so the
  # blob still loads — but there is no opener relationship and `window.open`
  # returns null. Same-partition keeps the normal opener.
  if resolved.to_s.start_with?('blob:') && cross_partition_blob?(resolved, opener_browser)
    open_aux_window(resolved, name: name, source: opener_browser)   # no opener_handle ⇒ window.opener null
    return nil                                                      # window.open(...) === null
  end
  # Same-origin window → a realm in the opener's isolate (shared heap); the
  # returned realm-id context becomes a native WindowProxy on the JS side, so
  # cross-window scripting/adoption need no cross-isolate RPC. The opener's realm
  # id wires the popup's window.opener. Falls through to the separate-VM aux path
  # (cross-origin, or a URL we don't yet realm-load).
  if (rid = opener_browser.open_window_realm(resolved, name: name, opener_realm_id: opener_realm_id, about_base: about_base, about_origin: about_origin))
    return rid
  end
  open_aux_window(resolved, name: name, opener_handle: handle_for(opener_browser), source: opener_browser)
end

#opener_handle_of(browser) ⇒ Object 



620
621
622
623
 
# File 'lib/capybara/simulated/driver.rb', line 620

def opener_handle_of(browser)
  handle = handle_for(browser)
  window_entries.find {|w| w[:handle] == handle }&.fetch(:opener)
end

#peek_script(expr) ⇒ Object

Clock-free read of a JS expression in the active browsing context (no virtual-time advance, unlike evaluate_script) — for polling page state between event-loop frames without perturbing the clock.



282
 
# File 'lib/capybara/simulated/driver.rb', line 282

def peek_script(expr) = current_browser.peek_script(expr)

#refresh ⇒ Object 



285
 
# File 'lib/capybara/simulated/driver.rb', line 285

def refresh              = current_browser.refresh

#register_blob_partition(url, browser, site) ⇒ Object

Record / drop a blob URL's storage partition (called by Browser#blob_register / #blob_unregister). site is the creating context's top-level site.



498
499
500
 
# File 'lib/capybara/simulated/driver.rb', line 498

def register_blob_partition(url, browser, site)
  @blob_partitions_lock.synchronize { @blob_partitions[url.to_s] = {browser: browser, site: site.to_s} }
end

#reset! ⇒ Object 



286
287
288
289
 
# File 'lib/capybara/simulated/driver.rb', line 286

def reset!
  reset_windows!
  browser.reset!
end

#reset_history! ⇒ Object 



330
 
# File 'lib/capybara/simulated/driver.rb', line 330

def reset_history!       = current_browser.reset_history!

#reset_windows! ⇒ Object

Dispose every auxiliary window and return focus to the primary — a fresh browsing context has no sibling windows. Disposing each aux Browser tears down its worker / SSE / websocket threads and its V8 isolate eagerly; left alone they pile into V8Runtime's process-wide @@live set and are only reclaimed by the at_exit hook, which on a long-lived multi-file session (the WPT runner) means a slow — sometimes minutes-long — process exit. Split out of reset! so a caller can drop windows WITHOUT resetting the primary's page state (the WPT runner rebuilds the primary itself, per file, via visit).



299
300
301
302
303
304
 
# File 'lib/capybara/simulated/driver.rb', line 299

def reset_windows!
  @aux_windows.each {|w| w[:browser].dispose rescue nil }
  @aux_windows.clear
  @active_handle = nil
  @blob_partitions_lock.synchronize { @blob_partitions.clear }
end

#resize(w, h) ⇒ Object

Forem's ahoy-tracking spec calls driver.resize(w, h) directly rather than through current_window.resize_to.



689
690
691
692
693
 
# File 'lib/capybara/simulated/driver.rb', line 689

def resize(w, h) = current_browser.set_viewport(w, h)
# Both restore the window to the display it lives on (`Browser#screen_size`), which is where
# it started — so they undo a `resize_to` rather than doing nothing. Coarse: we model no
# window chrome, so a maximized window and a fullscreen one end up the same size (a real
# browser's fullscreen is taller by the chrome it hides).

#resize_window_to(handle, w, h) ⇒ Object 



686
687
688
 
# File 'lib/capybara/simulated/driver.rb', line 686

def resize_window_to(handle, w, h) = window_browser!(handle).set_viewport(w, h)
# Forem's ahoy-tracking spec calls `driver.resize(w, h)` directly
# rather than through `current_window.resize_to`.

#response_headers ⇒ Object 



335
 
# File 'lib/capybara/simulated/driver.rb', line 335

def response_headers     = current_browser.response_headers

#revoke_blob_partitioned(url, source) ⇒ Object

A user URL.revokeObjectURL(url) from source. Storage-partitioned: a revoke from a different top-level site than the blob's is a NO-OP (cross-partition.https "shouldn't be revocable from a cross-partition iframe/worker"). A same-partition revoke drops the Driver entry AND invalidates the blob in the CREATOR's isolate (the blob may have been created in another window), so every window stops resolving it. Returns false when vetoed (caller leaves its local copy intact).



512
513
514
515
516
517
518
519
 
# File 'lib/capybara/simulated/driver.rb', line 512

def revoke_blob_partitioned(url, source)
  entry = @blob_partitions_lock.synchronize { @blob_partitions[url.to_s] }
  return false if entry && entry[:site] != source.blob_partition_site
  @blob_partitions_lock.synchronize { @blob_partitions.delete(url.to_s) }
  creator = entry && entry[:browser]
  creator.drop_local_blob(url.to_s) if creator && creator.respond_to?(:drop_local_blob) && !creator.equal?(source)
  true
end

#run_event_loop_frame(frame_ms) ⇒ Object

Run one real-cadence event-loop frame and return the loop's observable state. Drives "advance the page one frame" without the full poll tick evaluate_script would incur per read; the wpt_runner uses it to drain a page to completion at browser cadence.

EVERY live window steps, not just the active one: an auxiliary window is a separate VM, but the cross-context orchestration the dispatcher framework builds on (a popup running an executor that polls a shared queue while the opener waits) needs those background windows to make progress autonomously. The active window's state leads; each aux window folds its progress / raf / async / nearest-timer in so the caller keeps pumping while any window works.



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/capybara/simulated/driver.rb', line 240

def run_event_loop_frame(frame_ms)
  state = current_browser.run_event_loop_frame(frame_ms)
  # Iterate a SNAPSHOT: a window's drain can open or close windows mid-loop (a
  # popup spawning another, or window.close disposing one). Re-check each window
  # is still open before stepping it, and isolate a per-window failure so one
  # dead/half-torn-down VM can't abort the whole frame pump.
  @aux_windows.dup.each do |w|
    b = w[:browser]
    next if b.equal?(current_browser)
    next unless @aux_windows.include?(w)   # closed earlier this loop → skip
    begin
      state = merge_frame_state(state, b.run_event_loop_frame(frame_ms))
    rescue StandardError
      next
    end
  end
  state
end

#save_screenshot(path, **_opts) ⇒ Object 



734
735
736
737
 
# File 'lib/capybara/simulated/driver.rb', line 734

def save_screenshot(path, **_opts)
  File.write(path, current_browser.html.to_s)
  path
end

#send_keys(*keys) ⇒ Object 



753
754
755
756
757
758
759
760
761
762
763
764
765
 
# File 'lib/capybara/simulated/driver.rb', line 753

def send_keys(*keys)
  # Selenium contract: top-level modifier symbols (`send_keys(
  # :shift, :enter)`) press the modifier *and hold it* over the
  # following key, releasing at the end of the call. Nested
  # arrays (`send_keys([:control, "/"])`) are chords — modifiers
  # combined with the final key in one press. Pass the whole
  # batch to `Browser#send_session_keys` in one call so the
  # JS-side handler can build a `combo` atom from the held
  # modifiers + the next key. Iterating per-key would split the
  # chord across calls and drop the modifier flags.
  current_browser.send_session_keys(keys)
  nil
end

#set_geolocation(latitude: nil, longitude: nil, accuracy: 10, denied: false, **rest) ⇒ Object

CDP-ish geolocation override (Capybara driver-level API).

page.driver.set_geolocation(latitude: 35.6, longitude: 139.7)
page.driver.set_geolocation(denied: true)  # PERMISSION_DENIED
page.driver.set_geolocation                # clear -> POSITION_UNAVAILABLE


749
750
751
 
# File 'lib/capybara/simulated/driver.rb', line 749

def set_geolocation(latitude: nil, longitude: nil, accuracy: 10, denied: false, **rest)
  current_browser.set_geolocation(latitude: latitude, longitude: longitude, accuracy: accuracy, denied: denied, **rest)
end

#start_tracing(**metadata) ⇒ Object

Per-test trace recording. Mirrors capybara-playwright-driver's start_tracing / stop_tracing shape so suites can swap drivers without rewriting hooks.



120
 
# File 'lib/capybara/simulated/driver.rb', line 120

def start_tracing(**metadata) = browser.start_trace(metadata)

#status_code ⇒ Object 



334
 
# File 'lib/capybara/simulated/driver.rb', line 334

def status_code          = current_browser.status_code

#stop_tracing(path: nil) ⇒ Object 



122
123
124
125
126
127
 
# File 'lib/capybara/simulated/driver.rb', line 122

def stop_tracing(path: nil)
  active = current_trace or return nil
  result = path ? browser.finish_trace_to(path, active) : active
  browser.clear_trace!
  result
end

#storage_broadcast(source_browser, kind, key, old, new, url) ⇒ Object

A localStorage change fans out to every OTHER window (localStorage spans same-origin browsing contexts). Every window shares the Driver's one @local_storage jar, so all windows are same-origin peers here (cross-origin storage partitioning is a separate backlog item); a nil source realm reaches each target's every realm. sessionStorage is per-context and never reaches this path.



568
569
570
571
572
573
 
# File 'lib/capybara/simulated/driver.rb', line 568

def storage_broadcast(source_browser, kind, key, old, new, url)
  window_entries.each do |w|
    next if w[:browser].equal?(source_browser)
    w[:browser].enqueue_storage_event(kind, key, old, new, url, nil)
  end
end

#switch_to_frame(frame) ⇒ Object

Capybara within_frame / switch_to_frame. frame is the iframe Capybara::Node::Element (its .native is our driver Node), or the :parent / :top symbols. The block's finds + actions then route into the frame's own V8 realm via the Browser's @current_realm_id.



350
351
352
353
 
# File 'lib/capybara/simulated/driver.rb', line 350

def switch_to_frame(frame)
  target = frame.is_a?(Symbol) ? frame : frame.native.handle_id
  current_browser.switch_to_frame(target)
end

#switch_to_window(h) ⇒ Object 



682
683
684
685
 
# File 'lib/capybara/simulated/driver.rb', line 682

def switch_to_window(h)
  window_browser!(h)   # unknown / already-closed handle → WindowError
  @active_handle = (h == PRIMARY_HANDLE ? nil : h)
end

#title ⇒ Object 



333
 
# File 'lib/capybara/simulated/driver.rb', line 333

def title                = current_browser.title

#tracing? ⇒ Boolean

Returns:

  • (Boolean) 


129
 
# File 'lib/capybara/simulated/driver.rb', line 129

def tracing?      = !current_trace.nil?

#unregister_blob_partition(url) ⇒ Object 



502
503
504
 
# File 'lib/capybara/simulated/driver.rb', line 502

def unregister_blob_partition(url)
  @blob_partitions_lock.synchronize { @blob_partitions.delete(url.to_s) }
end

#visit(path) ⇒ Object 



284
 
# File 'lib/capybara/simulated/driver.rb', line 284

def visit(path)          = current_browser.visit(path)

#wait? ⇒ Boolean

Dynamic wait?: only poll when there's pending timer work that real-time advancement could resolve. With no timers queued, polling can't change anything, so we fail fast via the wait? = false synchronize path.

Returns:

  • (Boolean) 


227
 
# File 'lib/capybara/simulated/driver.rb', line 227

def wait?               = current_browser.polling?

#window_browser(handle) ⇒ Object

The Browser backing a handle, or nil if the window is closed/unknown.



373
374
375
 
# File 'lib/capybara/simulated/driver.rb', line 373

def window_browser(handle)
  window_entries.find {|w| w[:handle] == handle }&.fetch(:browser)
end

#window_browser!(handle) ⇒ Object

Same, but for the operations that ADDRESS a window rather than probe for one: a closed or unknown handle is Capybara's WindowError, never a silent fall back to the current window.



379
380
381
 
# File 'lib/capybara/simulated/driver.rb', line 379

def window_browser!(handle)
  window_browser(handle) or raise Capybara::WindowError, "Unknown window handle: #{handle}"
end

#window_closed?(handle) ⇒ Boolean

Returns:

  • (Boolean) 


619
 
# File 'lib/capybara/simulated/driver.rb', line 619

def window_closed?(handle)         = window_browser(handle).nil?

#window_handles ⇒ Object 



363
364
365
 
# File 'lib/capybara/simulated/driver.rb', line 363

def window_handles
  [PRIMARY_HANDLE] + @aux_windows.map {|w| w[:handle] }
end

#window_history_go(handle, delta) ⇒ Object

A cross-window w.history.back()/forward()/go(n): traverse the target window's history. The opener's VM is the one executing, so a non-active target can rebuild eagerly (like navigate_window); an active target (e.g. opener.history.back() from an aux) defers to avoid tearing down the running VM mid-call. Returns true when the traversal crossed a document boundary — the JS proxy then fires the target's deferred load (the same deferral as navAux) so the restored page's window.onload runs after the opener's current task. False for a same-document (pushState) traversal — popstate already fired — or a no-op.



606
607
608
609
610
611
612
613
614
615
616
617
618
 
# File 'lib/capybara/simulated/driver.rb', line 606

def window_history_go(handle, delta)
  b = window_browser(handle) or return false
  if b.equal?(current_browser)
    # `opener.history.back()` targeting the active window: defer (can't
    # rebuild the running VM mid-call) and return false — the active
    # window's load fires through its own navigation path when the pending
    # traversal drains, NOT via the aux-load deferral the caller would run.
    b.history_go(delta)
    false
  else
    b.history_go(delta, force: true) == :cross_document
  end
end

#window_location(handle) ⇒ Object 



575
576
577
 
# File 'lib/capybara/simulated/driver.rb', line 575

def window_location(handle)        = (window_browser(handle)&.current_url).to_s
# A cross-window property read (`win.foo` / `win.document.foo`) — read the
# primitive off the target window's VM.

#window_post_message(source_browser, target_handle, data, _origin) ⇒ Object

targetWindow.postMessage(data, origin) — queue on the target window's Browser, tagged with the source window's handle.



541
542
543
544
 
# File 'lib/capybara/simulated/driver.rb', line 541

def window_post_message(source_browser, target_handle, data, _origin)
  target = window_browser(target_handle) or return
  target.enqueue_window_message(data, _origin, handle_for(source_browser))
end

#window_read(handle, prop, doc: false) ⇒ Object

A cross-window property read (win.foo / win.document.foo) — read the primitive off the target window's VM.



578
579
580
581
 
# File 'lib/capybara/simulated/driver.rb', line 578

def window_read(handle, prop, doc: false)
  b = window_browser(handle) or return nil
  b.read_property(prop, doc: doc)
end

#window_ref_call(handle, id, method, args) ⇒ Object 



587
 
# File 'lib/capybara/simulated/driver.rb', line 587

def window_ref_call(handle, id, method, args) = (b = window_browser(handle)) ? b.remote_ref_call(id, method, args) : nil

#window_ref_get(handle, id, prop) ⇒ Object 



585
 
# File 'lib/capybara/simulated/driver.rb', line 585

def window_ref_get(handle, id, prop)         = (b = window_browser(handle)) ? b.remote_ref_get(id, prop) : nil

#window_ref_set(handle, id, prop, value) ⇒ Object 



586
 
# File 'lib/capybara/simulated/driver.rb', line 586

def window_ref_set(handle, id, prop, value)  = ((b = window_browser(handle)) && b.remote_ref_set(id, prop, value))

#window_set_location(handle, url) ⇒ Object 



588
589
590
591
592
593
594
595
596
 
# File 'lib/capybara/simulated/driver.rb', line 588

def window_set_location(handle, url)
  b = window_browser(handle) or return
  # Per HTML, `w.location = url` parses `url` relative to the ENTRY settings
  # object — the document of the script doing the assignment (the active
  # window) — NOT the target window's current document. So a cross-window
  # `w.location.href = 'resources/x.html'` resolves against the opener's
  # base, not the aux's (which would double a shared path segment).
  navigate_window(b, current_browser.resolve_document_url(url), source: current_browser)
end

#window_size(handle) ⇒ Object

Every window has its own viewport, so these address the window the handle names — not the active one. Capybara::Window#resize_to on a background window must resize THAT window and leave the current one (and Capybara's idea of which window is current) alone.



659
660
661
662
 
# File 'lib/capybara/simulated/driver.rb', line 659

def window_size(handle)
  b = window_browser!(handle)
  [b.viewport_width, b.viewport_height]
end

#with_playwright_page {|FakePlaywrightPage.new(current_browser)| ... } ⇒ Object

Playwright-driver compatibility shim. Discourse's system-spec before(:each) calls page.driver.with_playwright_page to install a JS-console logger, apply a CDP setTimezoneOverride, and (in dev_tools_spec) evaluate window.enableDevTools(). Yield a FakePlaywrightPage that delegates evaluate(js) to our JS engine and silently no-ops every other Playwright-only method via method_missing → self. Chained accessors like pw.context.new_cdp_session(pw).send_message("…") therefore propagate as a no-op rather than NoMethodError, while pw.evaluate("…") runs the JS where it matters.

Yields:



157
158
159
 
# File 'lib/capybara/simulated/driver.rb', line 157

def with_playwright_page
  yield FakePlaywrightPage.new(current_browser) if block_given?
end