capybara-lightpanda 0.8.0 → 0.9.0

data/lib/capybara/lightpanda/client/subscriber.rb

@@ -58,6 +58,8 @@ module Capybara
           end
         end
 
+        # Test seam: no production caller, but subscriber_test asserts
+        # unsubscribe/clear semantics through it.
         def subscribed?(event)
           @mutex.synchronize { @subscriptions.key?(event) && @subscriptions[event].any? }
         end

data/lib/capybara/lightpanda/client/web_socket.rb

@@ -4,6 +4,8 @@ require "json"
 require "socket"
 require "websocket/driver"
 
+require_relative "../utils/attempt"
+
 module Capybara
   module Lightpanda
     class Client
@@ -36,7 +38,7 @@ module Capybara
 
           @status = :closing
           @messages.close
-          @driver&.close
+          @driver_mutex.synchronize { @driver&.close }
           @thread&.join(1) || @thread&.kill
           @socket&.close
           @status = :closed
@@ -46,15 +48,10 @@ module Capybara
           @status == :closed || @status == :error
         end
 
-        def open?
-          @status == :open
-        end
-
         def write(data)
           @socket.write(data)
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
-          @status = :closed
-          @messages.close
+          mark_dead
         end
 
         private
@@ -73,13 +70,9 @@ module Capybara
           start_reader_thread
         end
 
-        def connect_with_retry(host, port, retries: 10, delay: 0.1)
-          retries.times do |i|
-            return TCPSocket.new(host, port)
-          rescue Errno::ECONNREFUSED
-            raise if i == retries - 1
-
-            sleep delay
+        def connect_with_retry(host, port)
+          Utils::Attempt.with_retry(errors: Errno::ECONNREFUSED, max: 10, wait: 0.1) do
+            TCPSocket.new(host, port)
           end
         end
 
@@ -97,8 +90,7 @@ module Capybara
           end
 
           @driver.on(:close) do
-            @status = :closed
-            @messages.close
+            mark_dead
           end
 
           @driver.on(:error) do |event|
@@ -109,8 +101,7 @@ module Capybara
             # process. Mark the connection dead and let Client#command
             # surface DeadBrowserError on its next dispatch via closed?.
             @logger&.puts("✗ WebSocket error: #{event.message}")
-            @status = :error
-            @messages.close
+            mark_dead(:error)
           end
         end
 
@@ -127,8 +118,7 @@ module Capybara
                 data = @socket.readpartial(4096)
                 @driver_mutex.synchronize { @driver.parse(data) }
               rescue Errno::ECONNRESET, Errno::EPIPE, IOError
-                @status = :closed
-                @messages.close
+                mark_dead
                 break
               end
             end
@@ -144,7 +134,7 @@ module Capybara
             begin
               data = @socket.readpartial(4096)
               @driver.parse(data)
-            rescue EOFError
+            rescue Errno::ECONNRESET, Errno::EPIPE, IOError # IOError covers EOFError
               raise DeadBrowserError, "Connection closed during handshake"
             end
           end
@@ -154,6 +144,14 @@ module Capybara
           raise TimeoutError, "WebSocket handshake timed out after #{@options.handshake_timeout}s"
         end
 
+        # Single home for the "dead implies queue closed" invariant: every
+        # path that gives up on the connection must close @messages so the
+        # Client message thread's blocking pop returns.
+        def mark_dead(status = :closed)
+          @status = status
+          @messages.close
+        end
+
         def parse_message(data)
           JSON.parse(data, max_nesting: false)
         rescue JSON::ParserError => e

data/lib/capybara/lightpanda/client.rb

@@ -9,10 +9,7 @@ require_relative "client/subscriber"
 module Capybara
   module Lightpanda
     class Client
-      attr_reader :ws_url, :options
-
       def initialize(ws_url, options)
-        @ws_url = ws_url
         @options = options
         @ws = WebSocket.new(ws_url, options)
         @command_id = 0
@@ -118,7 +115,11 @@ module Capybara
       def handle_message(message)
         if message["id"]
           pending = @pendings[message["id"]]
-          pending&.set(message)
+          # try_set, not set: a duplicate frame for an already-answered id
+          # (Lightpanda emits occasional malformed/duplicate frames — see
+          # upstream-wishlist.md A41) would raise MultipleAssignmentError on
+          # this thread, and abort_on_exception would kill the whole process.
+          pending&.try_set(message)
         elsif message["method"]
           @subscriber.dispatch(message["method"], message["params"])
         end

data/lib/capybara/lightpanda/driver.rb

@@ -10,7 +10,7 @@ module Capybara
 
       attr_reader :app, :options
 
-      delegate %i[current_url title status_code response_headers] => :browser
+      delegate %i[current_url title status_code response_headers frame_url frame_title] => :browser
 
       def initialize(app, options = {})
         super()
@@ -26,9 +26,7 @@ module Capybara
       end
 
       def browser_alive?
-        @browser.client && !@browser.client.closed?
-      rescue StandardError
-        false
+        !@browser.nil? && @browser.alive?
       end
 
       # Escape hatch to the underlying Browser for callers that need raw CDP
@@ -160,42 +158,20 @@ module Capybara
         end
       end
 
-      # Capybara::Driver::Base falls back to running these via the top
-      # execution context, which always reports the parent document. Resolve
-      # them through the iframe element's contentWindow / contentDocument so
-      # they reflect the active frame.
-      def frame_url
-        frame = browser.frame_stack.last
-        return browser.current_url unless frame
-
-        browser.call_function_on(frame.remote_object_id,
-                                 "function() { return this.contentWindow.location.href }")
-      end
-
-      def frame_title
-        frame = browser.frame_stack.last
-        return browser.title unless frame
-
-        browser.call_function_on(frame.remote_object_id,
-                                 "function() { return this.contentDocument.title }")
-      end
-
       # -- Modal/Dialog Support --
 
+      # find_modal owns the wait default (browser.options.timeout) — pass
+      # wait only when the caller overrode it.
       def accept_modal(type, **options, &block)
         browser.accept_modal(type, text: options[:with])
         block&.call
-        browser.find_modal(type,
-                           text: options[:text],
-                           wait: options.fetch(:wait, browser.options.timeout))
+        browser.find_modal(type, **{ text: options[:text], wait: options[:wait] }.compact)
       end
 
       def dismiss_modal(type, **options, &block)
         browser.dismiss_modal(type)
         block&.call
-        browser.find_modal(type,
-                           text: options[:text],
-                           wait: options.fetch(:wait, browser.options.timeout))
+        browser.find_modal(type, **{ text: options[:text], wait: options[:wait] }.compact)
       end
 
       # -- Screenshots --
@@ -241,12 +217,20 @@ module Capybara
       # Thin Cuprite-style wrapper. The interesting work — disposing the
       # BrowserContext (cookies, storage, all targets) and starting a fresh
       # one — happens in Browser#reset.
+      #
+      # Rescue is the gem hierarchy plus raw IO escapees only — NOT
+      # StandardError: reset! runs between every test, so a blanket rescue
+      # turns programmer errors (e.g. a NoMethodError in browser.rb) into a
+      # silent quit-and-respawn on every example with zero signal. The warn
+      # keeps repeated respawns visible.
       def reset!
         browser.reset
-        @started = false
-      rescue StandardError
+      rescue Error, SystemCallError, IOError => e
+        warn "[capybara-lightpanda] reset! failed (#{e.class}: #{e.message}); respawning browser"
         @browser&.quit
         @browser = nil
+      ensure
+        @started = false
       end
 
       def quit
@@ -315,14 +299,15 @@ module Capybara
       end
 
       # Walk through evaluate-script results turning DOM-node markers (the
-      # `{ "__lightpanda_node__" => "..." }` hashes produced by `Browser#unwrap_call_result`)
-      # into Lightpanda::Node instances so Capybara can wrap them as elements.
+      # `{ Browser::NODE_MARKER => "..." }` hashes produced by
+      # `Browser#unwrap_call_result`) into Lightpanda::Node instances so
+      # Capybara can wrap them as elements.
       def unwrap_script_result(value)
         case value
         when Array then value.map { |v| unwrap_script_result(v) }
         when Hash
-          if value.size == 1 && value.key?("__lightpanda_node__")
-            Node.new(self, value["__lightpanda_node__"])
+          if value.size == 1 && value.key?(Browser::NODE_MARKER)
+            Node.new(self, value[Browser::NODE_MARKER])
           else
             value.transform_values { |v| unwrap_script_result(v) }
           end

data/lib/capybara/lightpanda/errors.rb

@@ -5,6 +5,9 @@ module Capybara
     class Error < StandardError; end
 
     class ProcessTimeoutError < Error; end
+    # Subclass so external `rescue ProcessTimeoutError` keeps catching it;
+    # Process#start dispatches on the class instead of message matching.
+    class PortInUseError < ProcessTimeoutError; end
     class BinaryNotFoundError < Error; end
     class BinaryError < Error; end
     class UnsupportedPlatformError < Error; end
@@ -88,6 +91,22 @@ module Capybara
       end
     end
 
+    class InvalidSelector < Error
+      attr_reader :method, :selector
+
+      def initialize(message, method = nil, selector = nil)
+        @method = method
+        @selector = selector
+        super(message)
+      end
+    end
+
+    # --- Cuprite/Ferrum drop-in compatibility surface ---
+    # This gem never raises the three classes below (no coordinate-based
+    # mouse path, no multi-page API, no page-status tracking). They mirror
+    # the peer taxonomy (Cuprite's MouseEventFailed, Ferrum's
+    # NoSuchPageError/StatusError) so suites migrating from those drivers
+    # don't NameError on rescue lists that reference them.
     class MouseEventFailed < BrowserError
       attr_reader :node, :selector, :position
 
@@ -103,16 +122,6 @@ module Capybara
       end
     end
 
-    class InvalidSelector < Error
-      attr_reader :method, :selector
-
-      def initialize(message, method = nil, selector = nil)
-        @method = method
-        @selector = selector
-        super(message)
-      end
-    end
-
     class NoSuchPageError < Error; end
     class StatusError < Error; end
   end

data/lib/capybara/lightpanda/javascripts/attach.js

@@ -0,0 +1,16 @@
+// --- Public surface ---
+// The one place that names window._lightpanda. References the function/var
+// declarations from turbo.js and predicates.js (hoisted into the same IIFE
+// scope by AutoScripts). Runs last in the concatenation order.
+window._lightpanda = {
+  turbo: {
+    pending: function() { return _pendingTurboOps; },
+    idle: function() { return _pendingTurboOps <= 0; }
+  },
+
+  isVisible: isVisible,
+  isObscured: isObscured,
+  isDisabled: isDisabled,
+  isContentEditable: isContentEditable,
+  visibleText: visibleText
+};

data/lib/capybara/lightpanda/javascripts/banner.js

@@ -0,0 +1,15 @@
+// _lightpanda auto-injected bundle. Assembled by AutoScripts (auto_scripts.rb)
+// from the sibling source files in this directory and registered once per
+// session via Page.addScriptToEvaluateOnNewDocument, so it runs in every
+// document — top frame and every iframe.
+//
+// Each source file is a plain sequence of declarations/statements: no IIFE,
+// no `export`/`import`/`require`. AutoScripts wraps them in the IIFE and the
+// `window._lightpanda` idempotency guard. Keeping the files free of module
+// syntax means they parse identically as a classic browser script and as a
+// `new Function(...)` body — which is exactly how the Bun harness (test/js/)
+// loads predicates.js to test them without a build step.
+//
+// Concatenation order (set in auto_scripts.rb): banner, turbo, predicates,
+// attach. `attach.js` reads the names defined by `turbo.js`/`predicates.js`,
+// so it must come last.

data/lib/capybara/lightpanda/javascripts/predicates.js

@@ -0,0 +1,152 @@
+// --- DOM visibility / state predicates ---
+// Centralized so node.rb's predicate methods (visible?, obscured?, disabled?)
+// and the visible_text walker share one implementation of the ancestor
+// cascade. Available in iframes too because the bundle is registered via
+// Page.addScriptToEvaluateOnNewDocument.
+//
+// These are bare top-level function declarations — attach.js exposes them on
+// window._lightpanda. They reference each other by name (visibleText calls
+// isVisible), not through `this`, so they keep working when node.rb invokes
+// `_lightpanda.visibleText(this)` with `this` bound to a DOM element by CDP.
+
+// Returns true if `el` is visible per Capybara's semantics. Lightpanda's
+// `checkVisibility()` walks ancestors and rejects `display:none` from
+// inline styles, stylesheets, and the UA sheet (PR #2294 — covers
+// HEAD/SCRIPT/STYLE/NOSCRIPT/TEMPLATE/TITLE, `[hidden]`, `[type=hidden]`,
+// closed-<details> children). `visibility:hidden|collapse` is handled
+// separately because checkVisibility's defaults (per spec) ignore it.
+//
+// External `<link rel=stylesheet>` ARE fetched and applied — the gem
+// always passes --enable-external-stylesheets (Lightpanda PR #2487,
+// guaranteed by the build floor) — so stylesheet-driven `display:none`
+// participates in this check. The remaining gap is viewport emulation:
+// `@media` rules and `matchMedia()` evaluate against the hardcoded
+// 1920×1080 viewport (no resize), so visibility gated on a non-desktop
+// viewport — e.g. a mobile-only CTA under `@media (max-width: …)` —
+// resolves like desktop Chrome at 1920×1080. Keep those specs on a
+// full-layout driver (README's dual-driver setup).
+function isVisible(el) {
+  if (!el || el.nodeType !== 1) return false;
+  var win = el.ownerDocument.defaultView || window;
+  var style = win.getComputedStyle(el);
+  if (style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+  return el.checkVisibility();
+}
+
+// Returns true if the element is obscured at its center point — i.e.
+// hit-testing elementFromPoint at the center returns something that is
+// not the element or its descendant. `visibility:hidden|collapse` is
+// short-circuited explicitly because those elements still produce a
+// layout box (so the rect-zero check below can't catch them); every
+// other "not rendered" case (display:none, [hidden], descendants of
+// either) falls out naturally because getBoundingClientRect returns
+// DOMRect{0,0,0,0} for elements with no layout box.
+function isObscured(el) {
+  var doc = el.ownerDocument;
+  var win = doc.defaultView || window;
+  var style = win.getComputedStyle(el);
+  if (style.visibility === 'hidden' || style.visibility === 'collapse') return true;
+  var r = el.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0) return true;
+  var cx = r.left + (r.width / 2);
+  var cy = r.top + (r.height / 2);
+  var w = win.innerWidth || doc.documentElement.clientWidth;
+  var h = win.innerHeight || doc.documentElement.clientHeight;
+  if (cx < 0 || cy < 0 || cx > w || cy > h) return true;
+  var hit = doc.elementFromPoint(cx, cy);
+  if (!hit) return true;
+  if (hit === el) return false;
+  return !el.contains(hit);
+}
+
+// Capybara's `Node#disabled?` is more permissive than CSS `:disabled`:
+// an `<option>` inside a disabled `<select>` or a disabled `<fieldset>`
+// is reported as disabled, even though those don't match CSS `:disabled`
+// per the HTML spec. Mirrors Cuprite's behavior so the shared specs pass.
+function isDisabled(el) {
+  if (el.matches && el.matches(':disabled')) return true;
+  if ((el.tagName || '').toUpperCase() === 'OPTION') {
+    var p = el.parentElement;
+    while (p) {
+      if (p.disabled) return true;
+      p = p.parentElement;
+    }
+  }
+  return false;
+}
+
+// True if the element is the host of a contenteditable region: it (or any
+// ancestor) has a non-"false" `contenteditable` attribute. Lightpanda's
+// native `HTMLElement.isContentEditable` (PR #2310) is hardwired to return
+// `false` for every element — it has no caret/keyboard editing pipeline —
+// so the IDL property is useless here and we walk ancestors ourselves.
+function isContentEditable(el) {
+  var n = el;
+  while (n && n.nodeType === 1) {
+    if (n.hasAttribute && n.hasAttribute('contenteditable')) {
+      var v = (n.getAttribute('contenteditable') || '').toLowerCase();
+      return v !== 'false';
+    }
+    n = n.parentElement;
+  }
+  return false;
+}
+
+// visibleText's block-detection tables. A node is block-level if its computed
+// `display` is in BLOCK_DISP or its tag is in BLOCK_TAG (the tag table catches
+// elements whose display we can't resolve and elements that are block by UA
+// default). Hoisted to IIFE scope so they're built once at injection, not
+// re-allocated on every visibleText() call.
+var BLOCK_DISP = { BLOCK:1, FLEX:1, GRID:1, 'LIST-ITEM':1, TABLE:1, 'TABLE-ROW':1,
+                   'TABLE-CAPTION':1, 'TABLE-CELL':1 };
+var BLOCK_TAG = { ADDRESS:1, ARTICLE:1, ASIDE:1, BLOCKQUOTE:1, DETAILS:1, DIALOG:1,
+                  DIV:1, DL:1, DT:1, DD:1, FIELDSET:1, FIGCAPTION:1, FIGURE:1,
+                  FOOTER:1, FORM:1, H1:1, H2:1, H3:1, H4:1, H5:1, H6:1, HEADER:1,
+                  HGROUP:1, HR:1, LI:1, MAIN:1, NAV:1, OL:1, P:1, PRE:1, SECTION:1,
+                  TABLE:1, TR:1, UL:1 };
+
+// Walk descendants and accumulate text from visible nodes only. Inserts
+// newlines around block-display containers so paragraphs/lists render with
+// natural breaks (Capybara expects this from Chrome's innerText).
+// Lightpanda's innerText returns textContent verbatim (no rendering, so no
+// hidden-descendant filtering), so we DIY the visibility filtering here.
+function visibleText(el) {
+  // Collapse runs of ASCII whitespace (preserving NBSP) to a single space —
+  // matches Chrome's innerText whitespace handling for text nodes.
+  function normText(s) {
+    return s.replace(/[\t\n\r\f\v ]+/g, ' ');
+  }
+
+  function walk(node) {
+    if (node.nodeType === 3) return normText(node.nodeValue);
+    // DocumentFragment / ShadowRoot — no element of its own to test
+    // for visibility, just walk children.
+    if (node.nodeType === 11) {
+      var fout = '';
+      for (var k = 0; k < node.childNodes.length; k++) fout += walk(node.childNodes[k]);
+      return fout;
+    }
+    if (node.nodeType !== 1) return '';
+    if (!isVisible(node)) return '';
+    var tag = (node.tagName || '').toUpperCase();
+    if (tag === 'TEXTAREA') return node.value || '';
+    if (tag === 'BR') return '\n';
+    var win = node.ownerDocument.defaultView || window;
+    var style = win.getComputedStyle(node);
+    var disp = (style.display || '').toUpperCase();
+    var isBlock = BLOCK_DISP[disp] || BLOCK_TAG[tag];
+    var out = '';
+    for (var i = 0; i < node.childNodes.length; i++) {
+      out += walk(node.childNodes[i]);
+    }
+    // Block-level elements get wrapped in \n…\n only when they actually
+    // contribute visible text. An empty <div> between two inline siblings
+    // would otherwise introduce a phantom line break that Chrome's
+    // innerText algorithm collapses out (required line breaks around
+    // empty blocks coalesce in the line-collapse pass).
+    if (isBlock && /\S/.test(out)) out = '\n' + out + '\n';
+    return out;
+  }
+
+  return walk(el);
+}

data/lib/capybara/lightpanda/javascripts/turbo.js

@@ -0,0 +1,67 @@
+// --- Turbo activity tracking ---
+// Tracks pending Turbo operations so the driver can wait for Turbo to settle.
+// Inspired by the CapybaraLockstep approach for stabilizing Turbo integration tests.
+// Events are not perfectly symmetrical in Turbo, so we track multiple pairs
+// and use a counter to handle overlapping operations.
+//
+// Transitions across 0 emit `__lightpanda_turbo_busy` / `__lightpanda_turbo_idle`
+// sentinels via console.debug. Browser#wait_for_turbo subscribes to those
+// sentinels (Runtime.consoleAPICalled) and toggles a Concurrent::Event so the
+// Ruby side can wait event-driven instead of polling.
+//
+// Pages without Turbo never trigger _turboStart, so no sentinels fire and the
+// Ruby Event stays set (idle by default) — wait_for_turbo returns immediately.
+var _pendingTurboOps = 0;
+function _signalTurbo(state) {
+  try { console.debug('__lightpanda_turbo_' + state); } catch (e) {}
+}
+function _turboStart() {
+  _pendingTurboOps++;
+  if (_pendingTurboOps === 1) _signalTurbo('busy');
+}
+function _turboEnd() {
+  if (_pendingTurboOps > 0) {
+    _pendingTurboOps--;
+    if (_pendingTurboOps === 0) _signalTurbo('idle');
+  }
+}
+
+// Fetch requests (covers Drive, Frames, and Form submission fetches)
+document.addEventListener('turbo:before-fetch-request', _turboStart);
+document.addEventListener('turbo:before-fetch-response', _turboEnd);
+document.addEventListener('turbo:fetch-request-error', _turboEnd);
+
+// Form submissions (can outlast their underlying fetch)
+document.addEventListener('turbo:submit-start', _turboStart);
+document.addEventListener('turbo:submit-end', _turboEnd);
+
+// Frame rendering (can outlast the fetch that triggered it)
+document.addEventListener('turbo:before-frame-render', _turboStart);
+document.addEventListener('turbo:frame-render', _turboEnd);
+
+// Stream rendering (no symmetric end event — wrap the render function)
+document.addEventListener('turbo:before-stream-render', function(event) {
+  _turboStart();
+  if (event.detail && event.detail.render) {
+    var originalRender = event.detail.render;
+    event.detail.render = function(streamElement) {
+      var result = originalRender(streamElement);
+      if (result && typeof result.then === 'function') {
+        return result.finally(_turboEnd);
+      }
+      _turboEnd();
+      return result;
+    };
+  } else {
+    _turboEnd();
+  }
+});
+
+// Drive page visits: turbo:load fires after the page is fully rendered.
+// Also serves as a safety reset — clears any counter leaks from aborted fetches.
+// Always re-signal idle so the Ruby Event re-arms even if some `_turboEnd`
+// call dropped on the floor mid-navigation.
+document.addEventListener('turbo:load', function() {
+  _pendingTurboOps = 0;
+  _signalTurbo('idle');
+});

data/lib/capybara/lightpanda/keyboard.rb

@@ -14,6 +14,7 @@ module Capybara
         enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
         shift: { key: "Shift", code: "ShiftLeft", keyCode: 16 },
         control: { key: "Control", code: "ControlLeft", keyCode: 17 },
+        ctrl: { key: "Control", code: "ControlLeft", keyCode: 17 },
         alt: { key: "Alt", code: "AltLeft", keyCode: 18 },
         pause: { key: "Pause", code: "Pause", keyCode: 19 },
         escape: { key: "Escape", code: "Escape", keyCode: 27 },
@@ -120,12 +121,14 @@ module Capybara
       def press_modifier(mod, active_mods)
         return if active_mods.include?(mod)
 
-        send_key_event("keyDown", KEYS[mod])
+        # key_definition (not KEYS[mod]) so a MODIFIERS entry missing its
+        # KEYS counterpart fails as ArgumentError, not NoMethodError on nil.
+        send_key_event("keyDown", key_definition(mod))
         active_mods << mod
       end
 
       def release_modifiers(active_mods)
-        active_mods.reverse_each { |m| send_key_event("keyUp", KEYS[m]) }
+        active_mods.reverse_each { |m| send_key_event("keyUp", key_definition(m)) }
         active_mods.clear
       end
 
@@ -133,7 +136,7 @@ module Capybara
         return dispatch_key(key) if active_mods.empty?
 
         modifier_value = active_mods.sum { |m| MODIFIERS[m] }
-        dispatch_modified(key, modifier_value, active_mods)
+        raw_dispatch(key_definition(key), modifiers: modifier_value)
       end
 
       def dispatch_char_with_mods(char, active_mods)
@@ -144,31 +147,28 @@ module Capybara
       end
 
       def dispatch_key(key)
-        definition = KEYS.fetch(key) { raise ArgumentError, "Unknown key: #{key.inspect}" }
-        raw_dispatch(definition)
+        raw_dispatch(key_definition(key))
       end
 
       def dispatch_char(char)
         @browser.page_command("Input.insertText", text: char)
       end
 
+      # An array groups modifiers with the keys they modify —
+      # `send_keys([:ctrl, "a"])` — scoped to the array instead of the rest
+      # of the call. Same press/dispatch/release machinery as held modifiers.
       def type_with_modifiers(keys)
-        modifiers, chars = keys.partition { |k| k.is_a?(Symbol) && MODIFIERS.key?(k) }
-        modifier_value = modifiers.sum { |m| MODIFIERS[m] }
+        modifiers, rest = keys.partition { |k| k.is_a?(Symbol) && MODIFIERS.key?(k) }
 
-        modifiers.each { |m| send_key_event("keyDown", KEYS[m]) }
-        chars.each { |key| dispatch_modified(key, modifier_value, modifiers) }
-        modifiers.reverse_each { |m| send_key_event("keyUp", KEYS[m]) }
-      end
-
-      def dispatch_modified(key, modifier_value, modifiers)
-        case key
-        when Symbol
-          definition = KEYS.fetch(key) { raise ArgumentError, "Unknown key: #{key.inspect}" }
-          raw_dispatch(definition, modifiers: modifier_value)
-        when String
-          key.each_char { |char| dispatch_modified_char(char, modifier_value, modifiers) }
+        active_mods = []
+        modifiers.each { |m| press_modifier(m, active_mods) }
+        rest.each do |key|
+          case key
+          when Symbol then dispatch_key_with_mods(key, active_mods)
+          when String then key.each_char { |char| dispatch_char_with_mods(char, active_mods) }
+          end
         end
+        release_modifiers(active_mods)
       end
 
       def dispatch_modified_char(char, modifier_value, modifiers)
@@ -177,6 +177,10 @@ module Capybara
         send_key_event("keyUp", { key: text }, modifiers: modifier_value)
       end
 
+      def key_definition(key)
+        KEYS.fetch(key) { raise ArgumentError, "Unknown key: #{key.inspect}" }
+      end
+
       def raw_dispatch(definition, modifiers: 0)
         type = definition[:text] ? "keyDown" : "rawKeyDown"
         send_key_event(type, definition, modifiers: modifiers)