capybara-dommy 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c7a62f13890b2fa82ad1270440924e9a1723a20975d71d91aa1bf24938922ae
-  data.tar.gz: 8045f008aaca496cab19488fc3b551cc2a955880d08bdc24034e60981d791ffe
+  metadata.gz: ce693099e9f737e726914acb5cf9129ad87a96978209f5b1d9cc27132925b652
+  data.tar.gz: a69e70e2f0878025fd8d8c5a9411aaa990d6ebd7f812bd623cd3f27c4614e3bd
 SHA512:
-  metadata.gz: e337cfa551b1a24a3f06554d5638260f5b2c2c19c09cad1b90aa3bfe55bd7363b1671f329070eabe32ab489ebcf035b06240cf79d1dea6ce364ff1541b2b9b03
-  data.tar.gz: 05ac1cd5fdda2ba28b907adbac630d3d139e2e33dfaf26f06478bd4fb7a7ca668b662fb4b6726da46818cae9aa09b5f95dc7a0390d81e9915bf64f1ad3ace1a0
+  metadata.gz: 1f351cf3f7989d3bfa1a984dc425cf895790350ed699431f1e6fb8a7d6708c8b1abc05ab20df20f129839a0c926074d6b64774b9885a97b593ad41b8354b0b2a
+  data.tar.gz: 4246e91a681b995f8cc2fb2633eac92a1d6e5b1fc8dad67954d099124cc999055575597a59a94965ea6d37b201ed04d9ec2271a6dbd0146d7eede6b634a416cc

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.10.0 — 2026-07-13
+
+### Added
+- **JavaScript-enabled driver variant** (`:dommy_js`, or `Driver.new(app, javascript: true)` / `config.javascript`): pages run their real Turbo/Stimulus/React bundles in the embedded QuickJS runtime, no browser process. Node interactions behave like a browser instead of the HTML-only fast paths — `click` dispatches the full pointer/mouse/click sequence before the default action (Turbo can `preventDefault` and take over), `set` types with focus + `input` / `change` events, `select_option` fires `input` / `change`, and `send_keys` dispatches real keyboard events. `execute_script` / `evaluate_script` run for real, and a time pump advances the virtual clock inside Capybara's synchronize loop so waiting matchers converge. Requires `dommy-js-quickjs`.
+
+### Fixed
+- The dommy-rack session is fully disposed on `reset!` and when the effective host changes, so JS runtimes and open WebSocket transports no longer leak across tests.
+
+## 0.9.0 — 2026-06-22
+
+Versioned in lockstep with [`dommy`](https://github.com/takahashim/dommy) 0.9.0.
+No functional changes to capybara-dommy itself; it inherits dommy 0.9.0's CSS
+cascade, computed styles, and accessibility tree, and now drives check/choose
+through native click activation.
+
 ## 0.8.0 — 2026-05-31
 
 Versioned in lockstep with [`dommy`](https://github.com/takahashim/dommy) 0.8.0.

data/lib/capybara/dommy/configuration.rb

@@ -6,7 +6,7 @@ module Capybara
     # when a keyword argument is omitted.
     class Configuration
       attr_accessor :default_host, :follow_redirects, :max_redirects, :visibility,
-                    :raise_on_unsupported_js
+                    :raise_on_unsupported_js, :javascript
 
       def initialize
         @default_host = "http://example.org"
@@ -14,6 +14,7 @@ module Capybara
         @max_redirects = 5
         @visibility = :html
         @raise_on_unsupported_js = true
+        @javascript = false
       end
     end
 

data/lib/capybara/dommy/driver.rb

@@ -12,14 +12,28 @@ module Capybara
 
       attr_reader :app, :visibility
 
+      # --- Deterministic-time seam (used by JS runtimes) ---
+      #
+      # A JS runtime assigns a callable here; the driver invokes it before
+      # each DOM read Capybara polls in its synchronize loop (find_css /
+      # find_xpath / html / title). The pump is expected to advance Dommy's
+      # virtual scheduler a small slice and drain microtasks, so "content
+      # appears after a timeout" specs converge without wall-clock sleeps.
+      # Installing a pump also flips `wait?` to true, making Capybara retry
+      # failed expectations instead of raising immediately. Survives
+      # `reset!` (it belongs to the runtime, not to one page session).
+      attr_accessor :time_pump
+
       def initialize(app,
                      default_host: nil,
                      follow_redirects: nil,
                      max_redirects: nil,
-                     visibility: nil)
+                     visibility: nil,
+                     javascript: nil)
         super()
         config = Capybara::Dommy.configuration
         @app = app
+        @javascript = javascript.nil? ? config.javascript : javascript
         @visibility = visibility || config.visibility
         unless VISIBILITY_MODES.include?(@visibility)
           raise ArgumentError,
@@ -34,6 +48,24 @@ module Capybara
           # hosts (e.g. app_host / multi-server specs), so don't enforce origin.
           enforce_same_origin: false
         }
+        @session_options[:javascript] = true if @javascript
+        # A JS session needs the virtual clock pumped inside Capybara's
+        # synchronize loop, so waiting expectations converge on timer/fetch
+        # driven updates. A host-installed pump (the documented seam) wins.
+        @time_pump ||= -> { @rack_session&.advance_time(16) } if @javascript
+      end
+
+      # Whether this driver runs page JavaScript (`javascript: true`, backed by
+      # a `Dommy::Rack::Session.new(app, javascript: true)`). Node interactions
+      # then dispatch real DOM events (Turbo/Stimulus handlers run) instead of
+      # the HTML-only fast paths.
+      def javascript? = @javascript
+
+      # Drain the JS runtime after an interaction's events (promise reactions
+      # settle before the next Capybara step). No-op without JavaScript.
+      def drain_js
+        rack_session.after_interaction if @javascript
+        nil
       end
 
       # The dommy-rack session. Named `rack_session` to avoid colliding with
@@ -43,6 +75,7 @@ module Capybara
       def rack_session
         host = effective_host
         if @rack_session.nil? || @rack_session_host != host
+          @rack_session&.dispose
           @rack_session = ::Dommy::Rack::Session.new(@app, **@session_options.merge(default_host: host))
           @rack_session_host = host
         end
@@ -52,6 +85,7 @@ module Capybara
       # --- Navigation ---
 
       def visit(path)
+        @frame_stack = []
         # A fresh visit resolves a relative path against the host root (not the
         # current page's directory), matching browser address-bar semantics.
         rack_session.visit(::URI.join("#{effective_host}/", path.to_s).to_s)
@@ -78,11 +112,15 @@ module Capybara
       # --- Page state ---
 
       def html
+        pump!
         rack_session.html
       end
 
+      # The title of the top-level browsing context, even inside a frame
+      # (Capybara's #title contract); the current frame's title is #frame_title.
       def title
-        document&.title
+        pump!
+        rack_session.document&.title
       end
 
       def status_code
@@ -96,17 +134,59 @@ module Capybara
       # --- Query (returns Capybara::Dommy::Node arrays) ---
 
       def find_css(query, **_options)
+        pump!
         wrap(document&.query_selector_all(query))
       end
 
       def find_xpath(query, **_options)
+        pump!
         wrap(document&.xpath(query))
       end
 
       # --- Node-facing seam (keeps the dommy-rack Session API in one place) ---
 
+      # The document queries run against: the innermost switched-to frame's
+      # document, or the top-level page when no frame is active.
       def document
-        rack_session.document
+        frame_stack.empty? ? rack_session.document : frame_stack.last[:document]
+      end
+
+      # --- Frames ---
+      # Capybara::Session#switch_to_frame drives these with an iframe element
+      # node, :parent, or :top. Frame documents are fetched through the
+      # dommy-rack session (sharing cookies); nothing here touches the
+      # top-level page state, so current_url / title stay top-level.
+
+      def switch_to_frame(frame)
+        case frame
+        when :top
+          @frame_stack = []
+        when :parent
+          frame_stack.pop
+        else
+          frame_stack.push(load_frame(frame.native))
+        end
+      end
+
+      def frame_url
+        frame_stack.empty? ? rack_session.current_url.to_s : frame_stack.last[:url]
+      end
+
+      def frame_title
+        document&.title
+      end
+
+      # --- Focus / keyboard ---
+
+      def active_element
+        Node.new(self, document.active_element)
+      end
+
+      # Session-level send_keys. Without JavaScript only focus navigation is
+      # meaningful, so :tab (the key Capybara's focused: specs use) moves
+      # focus through the tab order; other keys are ignored.
+      def send_keys(*keys)
+        keys.each { |key| focus_next_tabbable if key == :tab }
       end
 
       def follow_link(element)
@@ -120,11 +200,13 @@ module Capybara
       # --- Lifecycle ---
 
       def reset!
+        @rack_session&.dispose
         @rack_session = nil
+        @frame_stack = []
       end
 
       def wait?
-        false
+        !@time_pump.nil?
       end
 
       def needs_server?
@@ -140,12 +222,18 @@ module Capybara
       # When raise_on_unsupported_js is false these become no-ops, so tests
       # that incidentally call them don't fail.
 
-      def execute_script(_script, *_args)
-        unsupported_js!("execute_script")
+      def execute_script(script, *args)
+        return unsupported_js!("execute_script") unless @javascript
+        raise ArgumentError, "script arguments are not supported" unless args.empty?
+
+        rack_session.execute_script(script)
       end
 
-      def evaluate_script(_script, *_args)
-        unsupported_js!("evaluate_script")
+      def evaluate_script(script, *args)
+        return unsupported_js!("evaluate_script") unless @javascript
+        raise ArgumentError, "script arguments are not supported" unless args.empty?
+
+        rack_session.evaluate_script(script)
       end
 
       def evaluate_async_script(_script, *_args)
@@ -162,6 +250,55 @@ module Capybara
 
       private
 
+      def pump!
+        @time_pump&.call
+      end
+
+      def frame_stack
+        @frame_stack ||= []
+      end
+
+      # Fetch an iframe's document, resolving its src against the enclosing
+      # frame's URL so nested frames with relative srcs load correctly.
+      def load_frame(iframe_element)
+        src = iframe_element.get_attribute("src").to_s
+        raise Capybara::Dommy::Error, "iframe has no src" if src.empty?
+
+        url = ::URI.join(frame_url, src).to_s
+        response = rack_session.fetch(url, headers: {"Referer" => frame_url})
+        doc = response.document
+        raise Capybara::Dommy::Error, "iframe did not return an HTML document" unless doc
+
+        {document: doc, url: url}
+      end
+
+      # Sequential focus navigation: elements with a positive tabindex first
+      # (ascending, document order within a value), then the remaining
+      # focusables in document order. The page's tab cycle starts over when
+      # the current active element is not in the order (e.g. body).
+      FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]"
+
+      def focus_next_tabbable
+        ordered = tab_order
+        return if ordered.empty?
+
+        current = document.active_element
+        index = ordered.index { |el| el == current }
+        target = ordered[index ? index + 1 : 0]
+        target&.focus
+      end
+
+      def tab_order
+        candidates = document.query_selector_all(FOCUSABLE_SELECTOR).to_a.reject do |el|
+          el.get_attribute("tabindex").to_s.start_with?("-") ||
+            el.has_attribute?("disabled") ||
+            el.get_attribute("type").to_s.downcase == "hidden" ||
+            !visible?(el)
+        end
+        positive, natural = candidates.each_with_index.partition { |el, _i| el.get_attribute("tabindex").to_i.positive? }
+        positive.sort_by { |el, i| [el.get_attribute("tabindex").to_i, i] }.map(&:first) + natural.map(&:first)
+      end
+
       # Capybara's app_host (set per-example) wins over default_host; falls
       # back to the host this driver was configured with. Guarded so a
       # standalone driver (no owning Capybara session) still works.

data/lib/capybara/dommy/node.rb

@@ -17,7 +17,24 @@ module Capybara
       end
 
       def [](name)
-        native.get_attribute(name.to_s)
+        key = name.to_s
+        # Capybara's validation_message filter reads the constraint-validation
+        # DOM property, which never appears as a markup attribute.
+        if key == "validationMessage" && native.respond_to?(:validation_message)
+          return native.validation_message
+        end
+
+        # `checked` / `selected` reflect the live IDL property (current state),
+        # not the content attribute (which is the *default*) — as WebDriver's
+        # getAttribute does for these boolean attributes.
+        if key == "checked" && native.respond_to?(:checked)
+          return native.checked ? "true" : nil
+        end
+        if key == "selected" && native.respond_to?(:selected)
+          return native.selected ? "true" : nil
+        end
+
+        native.get_attribute(key)
       end
 
       def value
@@ -77,16 +94,56 @@ module Capybara
       end
 
       def path
+        # Capybara's documented placeholder: a shadow tree has no XPath.
+        if native.respond_to?(:get_root_node) && native.get_root_node.is_a?(::Dommy::ShadowRoot)
+          return "(: Shadow DOM element - no XPath :)"
+        end
+
         native.path
       end
 
-      def style(_styles)
-        {}
+      # Keyboard input without a JS engine: maintains a caret over the field's
+      # value and applies printable keys plus the position/modifier keys
+      # Capybara's non-JS send_keys specs use. Key *events* are not dispatched
+      # (nothing here can observe them without JavaScript).
+      def send_keys(*args)
+        # Under JavaScript, dispatch real keyboard events (keydown/keypress/
+        # input/keyup with browser default actions) through the dommy driver,
+        # so keyboard handlers (arrow navigation, Enter selection) run.
+        # Key chords ([:shift, "o"]) are not supported on this path.
+        return driver.rack_session.send_keys_to(native, *args) if driver.javascript?
+
+        return unless native.respond_to?(:value=)
+
+        state = {chars: native.value.to_s.chars, caret: native.value.to_s.length, shift: false}
+        args.each do |arg|
+          if arg.is_a?(Array)
+            # A chord like [:shift, 'o'] holds its modifiers only for the
+            # duration of the array.
+            held = state[:shift]
+            arg.each { |key| apply_key(state, key) }
+            state[:shift] = held
+          else
+            apply_key(state, arg)
+          end
+        end
+        native.focus if native.respond_to?(:focus)
+        native.value = state[:chars].join
+      end
+
+      # Computed styles for Capybara's matches_style? / style: filters,
+      # served by Dommy's CSS cascade (values come back in the computed
+      # serialization, e.g. colors as rgb()).
+      def style(styles)
+        computed = ::Dommy::Internal::CSS::Cascade.computed_style(native)
+        Array(styles).flatten.to_h { |name| [name.to_s, computed[name.to_s].to_s] }
       end
 
       # --- Interaction ---
 
       def click(_keys = [], **_options)
+        return js_click if driver.javascript?
+
         if link?
           click_link_node
         elsif submits?
@@ -122,6 +179,7 @@ module Capybara
         select_el = select_node
         deselect_all(select_el) unless select_el&.multiple
         native.selected = true
+        notify_select_changed(select_el)
       end
 
       def unselect_option
@@ -132,6 +190,15 @@ module Capybara
         native.selected = false
       end
 
+      # Move the (virtual) pointer over this element: :hover rules and
+      # `matches(":hover")` then apply to it and its ancestors. No
+      # mouseover/mouseout events are dispatched (nothing observes them
+      # without JavaScript).
+      def hover
+        native.owner_document.__internal_set_hovered_element__(native)
+        nil
+      end
+
       # --- Scoped queries (for `within`) ---
 
       def find_css(locator, **_options)
@@ -157,8 +224,34 @@ module Capybara
         RUBY
       end
 
+      # Identity matters to Capybara (e.g. the focused: filter compares a
+      # candidate against session.active_element). Dommy's wrapper cache hands
+      # out one wrapper per DOM node, so native equality is node identity.
+      def ==(other)
+        other.is_a?(Node) && native == other.native
+      end
+
       private
 
+      def apply_key(state, key)
+        case key
+        when String
+          key.each_char do |ch|
+            state[:chars].insert(state[:caret], state[:shift] ? ch.upcase : ch)
+            state[:caret] += 1
+          end
+        when :space
+          state[:chars].insert(state[:caret], " ")
+          state[:caret] += 1
+        when :left
+          state[:caret] = [state[:caret] - 1, 0].max
+        when :right
+          state[:caret] = [state[:caret] + 1, state[:chars].length].min
+        when :shift
+          state[:shift] = true
+        end
+      end
+
       def stale_check
         return if native.document.equal?(driver.document)
 
@@ -173,6 +266,40 @@ module Capybara
       # javascript: links are no-ops in Capybara (a policy decision); every
       # other link delegates to dommy-rack, which handles fragment / same-page
       # / blank-href semantics and raises on genuinely unsupported schemes.
+      # A JavaScript click: dispatch the full pointer/mouse/click sequence
+      # (Stimulus actions, Turbo's link/submit interception run like in a
+      # browser), then perform the un-prevented default action ourselves —
+      # link navigation, or the form submission algorithm (a cancelable
+      # submit event, then the real submission if nothing canceled it;
+      # Turbo cancels and takes over). Checkbox/radio toggling already ran
+      # as the click event's activation behavior.
+      def js_click
+        prevented = ::Dommy::Interaction::EventSynthesis.click(native)
+        unless prevented
+          # Link navigation and form submission are the elements' own activation
+          # behavior — run inside EventSynthesis.click above, routing through the
+          # session's navigation delegate (performed when driver.drain_js drains).
+          # Only the non-navigating default actions remain here.
+          if tag_name == "label"
+            click_label
+          elsif (details = native.closest("details"))
+            toggle_details(details)
+          end
+        end
+        driver.drain_js
+        nil
+      end
+
+      # Selecting an option through the UI fires input + change on the select
+      # (under JavaScript; nothing listens without it).
+      def notify_select_changed(select_el)
+        return unless driver.javascript? && select_el
+
+        ::Dommy::Interaction::EventSynthesis.input(select_el)
+        ::Dommy::Interaction::EventSynthesis.change(select_el)
+        driver.drain_js
+      end
+
       def click_link_node
         scheme = native.get_attribute("href").to_s.split(":", 2).first.to_s.downcase
         return if scheme == "javascript"
@@ -219,11 +346,28 @@ module Capybara
         # There is no submitter button in this case.
         form = single_field_form
         if input_field? && string.end_with?("\n") && form
-          native.value = string.chomp
+          write_text(string.chomp)
           driver.submit_form(form, submitter: nil)
         else
+          write_text(string)
+        end
+      end
+
+      # Set a text field's value. Under JavaScript this types like a user:
+      # focus, value, then input + change events, so Stimulus/React handlers
+      # observe the edit; the JS-less driver keeps the bare value write
+      # (nothing listens).
+      def write_text(string)
+        unless driver.javascript?
           native.value = string
+          return
         end
+
+        ::Dommy::Interaction::EventSynthesis.focus(native)
+        native.value = string
+        ::Dommy::Interaction::EventSynthesis.input(native, string)
+        ::Dommy::Interaction::EventSynthesis.change(native)
+        driver.drain_js
       end
 
       def single_field_form
@@ -248,25 +392,15 @@ module Capybara
         value && !value.empty?
       end
 
-      # Reflect checked state on the attribute so node[:checked] and form
-      # submission both observe it (Dommy's `checked=` only sets the property).
+      # Toggle through the control's native activation behavior (which fires
+      # input/change and, for a radio, maintains its group) — only when it
+      # isn't already in the requested state, matching a real click.
       def set_checkbox(value)
-        if value
-          native.set_attribute("checked", "checked")
-        else
-          native.remove_attribute("checked")
-        end
+        native.click if checked? != !!value
       end
 
       def set_radio
-        name = native.get_attribute("name")
-        scope = native.closest("form") || document
-        if name && scope
-          scope.query_selector_all("input[type='radio']").each do |radio|
-            radio.remove_attribute("checked") if radio.get_attribute("name") == name
-          end
-        end
-        native.set_attribute("checked", "checked")
+        native.click unless checked?
       end
 
       def set_file(value)

data/lib/capybara/dommy/rails.rb

@@ -8,3 +8,10 @@ require "capybara/dommy"
 Capybara.register_driver(:dommy) do |app|
   Capybara::Dommy::Driver.new(app)
 end
+
+# The JavaScript-enabled variant (`driven_by :dommy_js`): pages run their real
+# Turbo/Stimulus/React bundles in the embedded QuickJS runtime, no browser
+# process. Requires dommy-js-quickjs.
+Capybara.register_driver(:dommy_js) do |app|
+  Capybara::Dommy::Driver.new(app, javascript: true)
+end

data/lib/capybara/dommy/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Dommy
-    VERSION = "0.8.0"
+    VERSION = "0.10.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capybara-dommy
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - takahashim
 bindir: exe
 cert_chain: []
-date: 2026-05-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -29,28 +29,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: dommy-rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.10.0
 description: |
   capybara-dommy is a Capybara driver backed by Dommy and dommy-rack. It drives
   Rack/Rails apps through the Capybara DSL without a real browser or JavaScript,
@@ -94,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Dommy-backed Capybara driver
 test_files: []