capybara-playwright-driver 0.5.13 → 0.5.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04cd34c80f1466ffb40a7d515384d4fa29d2378bb5f51ce500432166f4c4e904
-  data.tar.gz: 51ccfc4802153ef189db9998d64b8b5f8b63f749556b25e5483920a35c998ae2
+  metadata.gz: 35fdde9b43c2e26b14f271e049ca2a9599d36552a777a00dacaaf6e498b96581
+  data.tar.gz: acf38394ff2727fb1cf519d67401c8c1012bd9b7410dfbc3e7cbeb599fc9401d
 SHA512:
-  metadata.gz: 298e9ab4a179b0d645f77b44befe83e6373f1adc4866b7b6e951200ab4671866d6ac10c9b6264b5831fd7770f4d920d197c0513c3ef89e3984f3576cce7265b8
-  data.tar.gz: a92fe593f5053b052b09d06c576743b2eb364b25a9650ae8c133185c3ac26696147d061a1826ae82c6437e07ad8f7aa79302187e75e6c1e658244afb00cfc24f
+  metadata.gz: 991e90ee94c3ed6e7cb44fc1a1f838e95b7de72cb29ce271ce7c65e0069c712a8c569c8e836bcf6b62bd3932dfcb79ba5569b35497cf6e8dc6659099de8adeca
+  data.tar.gz: 2da9229fcb4f1856f34220aaddb8bff505eb12cda450706e754f678372c6b48c7c133099cdf8420788abcf80ffa35658cb740024410e4ad2e1a30dae2483542a

data/README.md

@@ -46,6 +46,16 @@ Refer the [documentation](https://playwright-ruby-client.vercel.app/docs/article
 
 ## Selenium compatibility
 
+`visible?` and selector filters such as `visible: true` do not account for ancestor overflow clipping. An element
+completely clipped by an ancestor with `overflow: hidden` can still be considered visible by this driver, while
+Selenium considers it hidden. This can change the results of queries such as `all('.item', visible: true)` when
+migrating Selenium tests.
+
+Playwright's native visibility methods (`ElementHandle#visible?` and `Locator#visible?` in playwright-ruby-client)
+also consider these clipped elements visible. If a test needs to count items actually displayed inside a clipped
+container, check their geometry relative to the container explicitly. See
+[#174](https://github.com/YusukeIwaki/capybara-playwright-driver/issues/174) for the driver comparison and discussion.
+
 Visible text for ordinary HTML elements follows the browser's
 [`innerText` behavior](https://html.spec.whatwg.org/multipage/dom.html#the-innertext-idl-attribute). This preserves
 meaningful blank lines, but paragraph and rich-text-editor boundaries can differ from Selenium's WebDriver text
@@ -55,18 +65,31 @@ algorithm. When exact whitespace is not part of an assertion, use Capybara's `no
 expect(message).to have_text('Hello Regards', normalize_ws: true)
 ```
 
-This driver delegates keyboard focus and caret behavior to Playwright rather than overriding it with JavaScript. One
-observable difference is that when a `contenteditable` element loses focus between `send_keys` calls, Playwright may
-place the caret differently from Selenium when the element is focused again. Specify the caret movement explicitly
-when the test depends on it:
+Element `send_keys` follows WebDriver's focus and selection rules: an unfocused text input, textarea, or
+`contenteditable` starts at the end of its content; an already focused element keeps its caret or selection.
+The element is prepared once per call. Subsequent keys follow focus changes made by the application, including Tab
+navigation and autocomplete controls. For example, a new call can return to an editor after its autocomplete takes focus:
 
 ```ruby
-editor.send_keys(:end, '@') # The page moves focus to an autocomplete control.
-editor.send_keys(:end, 'alice')
+editor.send_keys('@') # The page moves focus to an autocomplete control.
+editor.send_keys('alice') # Focus the editor again and append at its end.
 ```
 
-For text inputs and textareas, `fill_in` uses Playwright's typing behavior for every character regardless of the value
-length. Playwright sends `keydown`, `keypress`/`input`, and `keyup` for characters on a US keyboard, but sends only
+`set`, `fill_in`, and `send_keys` use the same keyboard sequence handling, including Enter for newlines and Tab for
+tab characters. Replacement selects the target content before typing, including inherited `contenteditable` children.
+`clear: :none` preserves an existing selection when the input already has focus; `clear: :backspace` and key arrays
+send their clearing keys before the replacement text. Contenteditable replacement retains Playwright's visibility,
+enabled-state, and editability waiting. Element key presses retain navigation waiting while following the current
+focus. Elements replaced during waiting, focus, or selection can be retried before typing starts. Once typing begins,
+the sequence is not replayed when the original element is replaced. A Playwright error during dispatch raises
+`Capybara::Playwright::Node::InputInterruptedError` rather than retrying potentially delivered input.
+
+The compatibility specs record two intentional differences from Capybara Selenium: setting an empty string clears
+`contenteditable` content, and a focused input inside a shadow root keeps its selection instead of moving to the end.
+They also retain Playwright's wait for ARIA disabled/readonly state, which Selenium does not apply to contenteditable.
+
+Text entry uses Playwright's typing behavior for every character regardless of the value length. Playwright sends
+`keydown`, `keypress`/`input`, and `keyup` for characters on a US keyboard, but sends only
 `input` for other characters, including Japanese text. This follows
 [Playwright's documented keyboard behavior](https://playwright.dev/docs/api/class-keyboard#keyboard-type). Typing very
 large values is slower than Playwright's native `fill`, which does not send per-character keyboard events. When input

data/lib/capybara/playwright/browser.rb

@@ -238,7 +238,7 @@ module Capybara
         }
       end
 
-      def send_keys(*args)
+      def send_keys(*args, **options)
         Node::SendKeys.new(@playwright_page.keyboard, args).execute
       end
 

data/lib/capybara/playwright/node.rb

@@ -56,86 +56,26 @@ module Capybara
       end
 
       def set_checked_state_via_label?
-        playwright_checkable = find_playwright_element_handle_by_non_label_locator
-        playwright_checkable ||= playwright_locator_by_label unless @locator.nil?
-        return false unless playwright_checkable
+        return false if @locator.nil?
 
-        click_associated_label?(playwright_checkable)
-      rescue Capybara::ElementNotFound, Capybara::ExpectationNotMet, ::Playwright::Error
+        checkable = @node.find(@node_type, @locator, visible: :all, wait: 0)
+        click_associated_label?(checkable.native)
+      rescue Capybara::ElementNotFound, Capybara::ExpectationNotMet,
+             Capybara::Playwright::Node::StaleReferenceError, ::Playwright::Error
         false
       end
 
       private
 
-      def playwright_locator_by_label
-        driver.with_playwright_page do |playwright_page|
-          return playwright_page.get_by_label(@locator.to_s)
-        end
-      end
-
-      def click_associated_label?(playwright_element_handle_or_locator)
-        return true if playwright_element_handle_or_locator.evaluate('el => !!el.checked') == @checked
+      def click_associated_label?(element_handle)
+        return true if element_handle.evaluate('el => !!el.checked') == @checked
 
-        label_element_handle = playwright_element_handle_or_locator.evaluate_handle('(el) => (el.labels && el.labels[0]) || el.closest("label") || null')
+        label_element_handle = element_handle.evaluate_handle('(el) => (el.labels && el.labels[0]) || el.closest("label") || null')
         return false unless label_element_handle.is_a?(::Playwright::ElementHandle)
 
         label_element_handle.click
 
-        playwright_element_handle_or_locator.evaluate('el => !!el.checked') == @checked
-      end
-
-      def find_playwright_element_handle_by_non_label_locator
-        return nil if @locator.nil?
-
-        locator_string = @locator.to_s
-        test_id_attr = session_options.test_id&.to_s
-
-        driver.with_playwright_page do |playwright_page|
-          return non_label_playwright_element_handle_candidates(playwright_page).find do |element_handle|
-            attribute_values = element_handle.evaluate(<<~JAVASCRIPT, arg: test_id_attr)
-            (el, testIdAttr) => ({
-              id: el.id || '',
-              name: el.getAttribute('name') || '',
-              testId: testIdAttr ? (el.getAttribute(testIdAttr) || '') : '',
-            })
-            JAVASCRIPT
-            [attribute_values['id'], attribute_values['name'], attribute_values['testId']].include?(locator_string)
-          end
-        end
-      rescue ::Playwright::Error
-        nil
-      end
-
-      def non_label_playwright_element_handle_candidates(playwright_page)
-        input_type =
-          case @node_type
-          when :checkbox
-            'checkbox'
-          when :radio_button
-            'radio'
-          else
-            return []
-          end
-
-        current_scope = scope_element
-        return current_scope.query_selector_all(%(input[type="#{input_type}"])) if current_scope
-
-        playwright_page.capybara_current_frame.query_selector_all(%(input[type="#{input_type}"]))
-      end
-
-      def scope_element
-        return nil unless @node.is_a?(Capybara::Node::Element)
-        return nil unless @node.send(:base).is_a?(Capybara::Playwright::Node)
-
-        @node.send(:base).send(:element)
-      end
-
-      def driver
-        @node.send(:driver)
-      end
-
-      def session_options
-        @node.send(:session_options)
+        element_handle.evaluate('el => !!el.checked') == @checked
       end
     end
 
@@ -279,6 +219,7 @@ module Capybara
 
       class NotActionableError < StandardError ; end
       class StaleReferenceError < StandardError ; end
+      class InputInterruptedError < StandardError ; end
       class MissingBoundingBoxError < StandardError ; end
       class DragInterruptedError < StandardError ; end
 
@@ -431,109 +372,154 @@ module Capybara
 
       class TextInput < Settable
         def set(value, **options)
+          text = value.to_s
+          input = KeyboardInput.new(@element, @timeout)
+
           case options[:clear]
-          when :backspace
-            @element.press('End', timeout: @timeout)
-            existing_text = @element.evaluate('el => el.value')
-            existing_text.length.times { @element.press('Backspace', timeout: @timeout) }
           when :none
-            @element.press('End', timeout: @timeout)
-            ensure_attached
+            input.send_keys(text)
+          when :backspace
+            length = @element.evaluate('el => el.value || el.textContent || ""').length
+            input.send_keys(:end, *Array.new(length, :backspace), text)
           when Array
-            @internal_logger.warn "options { clear: #{options[:clear]} } is ignored"
-          end
-
-          text = value.to_s
-          if press_enter = text.end_with?("\r\n")
-            text = text[0...-2]
-          elsif press_enter = text.end_with?("\n")
-            text = text[0...-1]
+            input.send_keys(*options[:clear], text)
+          else
+            if text.empty?
+              @element.fill('', timeout: @timeout)
+            else
+              input.replace(text)
+            end
           end
-
-          keyboard = @element.owner_frame.page.keyboard
-          set_text(text, append: options[:clear] == :none, keyboard: keyboard)
-
-          keyboard.press('Enter') if press_enter
         rescue ::Playwright::TimeoutError
           raise if @element.editable?
 
           @internal_logger.info("Node#set: element is not editable. #{@element}")
         end
+      end
 
-        private def set_text(text, append:, keyboard:)
-          # ElementHandle#type can refocus inherited contenteditable descendants and drop the input.
-          if @element.evaluate('el => el.isContentEditable') && !append
-            @element.fill(text, timeout: @timeout)
-            return
-          end
-
-          text = text.gsub(/\r\n?/, "\n")
+      # Prepare the selection once, then let the browser route the whole sequence.
+      # Inherited contenteditable descendants are selected independently of their
+      # editing host, which is the element that can actually receive focus.
+      class KeyboardInput
+        def initialize(element, timeout)
+          @element = element
+          @timeout = timeout
+        end
 
-          if text.include?("\t")
-            type_tab_separated_text(text, append: append, keyboard: keyboard)
-            return
+        def replace(text)
+          if @element.evaluate('element => element.isContentEditable')
+            # This path used fill(), which waits for visibility and editability
+            # (including enabled state). select_text() alone only waits for visibility.
+            # https://playwright.dev/docs/actionability
+            @element.wait_for_element_state('visible', timeout: @timeout)
+            @element.wait_for_element_state('editable', timeout: @timeout)
           end
+          @element.select_text(timeout: @timeout)
+          type_keys([text])
+        end
 
-          if append
-            type_text(keyboard, text)
-          elsif text.empty?
-            @element.fill('', timeout: @timeout)
-          else
-            @element.select_text(timeout: @timeout)
-            replace_text(keyboard, text)
-          end
+        def send_keys(*keys)
+          # WebDriver Element Send Keys moves the caret to the end only when the
+          # element was not focused. Preserve the selection in an active editor.
+          # https://www.w3.org/TR/2026/WD-webdriver2-20260702/#element-send-keys
+          #
+          # References in ChromeDriver's element_commands.cc:
+          # - SendKeysToElement: append to newly focused text controls, then send
+          #   the whole sequence to the window without refocusing for each key.
+          #   https://github.com/chromium/chromium/blob/852d53b2cdde761fff9003021300b31c15fc1636/chrome/test/chromedriver/element_commands.cc#L191-L222
+          # - ExecuteSendKeysToElement: find the top editable ancestor for focus,
+          #   but collapse a Range over the requested element's own contents.
+          #   https://github.com/chromium/chromium/blob/852d53b2cdde761fff9003021300b31c15fc1636/chrome/test/chromedriver/element_commands.cc#L735-L799
+          # This adapts the caret preparation, not all of ChromeDriver's
+          # interactability checks; our differential specs cover the contract.
+          @element.evaluate(<<~JAVASCRIPT)
+            element => {
+              let host = element;
+              if (element.isContentEditable) {
+                while (host.parentElement && host.parentElement.isContentEditable)
+                  host = host.parentElement;
+              }
+              // Our shadow DOM adaptation of ChromeDriver's active-element check:
+              // document.activeElement would identify the shadow host instead.
+              const root = host.getRootNode();
+              if (root.activeElement === host) return;
+
+              // Focus first so it cannot reset the Range we are about to create.
+              host.focus();
+              if (element.isContentEditable) {
+                // Use the target's document so the Range also belongs to its iframe.
+                const range = element.ownerDocument.createRange();
+                range.selectNodeContents(element);
+                range.collapse(false);
+                const selection = element.ownerDocument.getSelection();
+                selection.removeAllRanges();
+                selection.addRange(range);
+              } else if (element.nodeName === 'TEXTAREA' ||
+                         (element.nodeName === 'INPUT' && /^(text|search|tel|url|password)$/.test(element.type))) {
+                // ChromeDriver's kTextControlTypes: other input types do not
+                // support setSelectionRange (e.g. number and email).
+                element.setSelectionRange(element.value.length, element.value.length);
+              }
+            }
+          JAVASCRIPT
+          type_keys(keys)
         end
 
-        private def replace_text(keyboard, text)
-          head, *tail = text.split("\n", -1)
-          if head.empty?
-            @element.press('Enter', timeout: @timeout)
-            head = tail.shift
-            keyboard.type(head) unless head.empty?
-          else
-            first_character = head[/\A\X/]
-            @element.type(first_character, timeout: @timeout)
-            ensure_attached
-            remaining_text = head[first_character.length..-1]
-            keyboard.type(remaining_text) unless remaining_text.empty?
+        private def type_keys(keys)
+          keyboard = FocusedKeyboard.new(@element.owner_frame.page, @timeout)
+          sequence = SendKeys.new(keyboard, keys)
+          # Focus/select can replace the element in a microtask. Check before
+          # dispatch so Capybara can reload it without replaying any keystrokes.
+          @element.enabled?
+          # Do not recheck the original handle after input has begun: the app may
+          # deliberately replace it or move focus, and replaying can duplicate input.
+          begin
+            sequence.execute
+          rescue ::Playwright::Error => err
+            # A navigation or a detached current focus can fail after earlier
+            # keys were delivered. Do not turn that into a retry of the whole set.
+            raise InputInterruptedError.new(err)
           end
-
-          type_lines(keyboard, tail)
         end
+      end
 
-        private def type_text(keyboard, text)
-          return if text.empty?
-
-          head, *tail = text.split("\n", -1)
-          keyboard.type(head) unless head.empty?
-
-          type_lines(keyboard, tail)
+      class FocusedKeyboard
+        def initialize(page, timeout)
+          @page = page
+          @timeout = timeout
         end
 
-        private def type_lines(keyboard, parts)
-          parts.each do |part|
-            keyboard.press('Enter')
-            keyboard.type(part) unless part.empty?
-          end
+        def type(text)
+          @page.keyboard.type(text)
         end
 
-        private def type_tab_separated_text(text, append:, keyboard:)
-          head, *tail = text.split("\t", -1)
-          set_text(head, append: append, keyboard: keyboard)
-
-          tail.each_with_index do |part, index|
-            if index.zero? && !append && head.empty?
-              @element.press('Tab', timeout: @timeout)
-            else
-              keyboard.press('Tab')
-            end
-            type_text(keyboard, part.gsub(/\r\n?/, "\n"))
-          end
+        def press(key)
+          # ElementHandle#press waits for navigation triggered by the key, unlike
+          # Keyboard#press. Use the current focus so Tab/autocomplete can redirect
+          # later keys without returning to the original element.
+          # https://playwright.dev/docs/api/class-elementhandle#element-handle-press
+          focused = focused_element(@page.main_frame)
+          focused.press(key, timeout: @timeout)
+        ensure
+          focused.dispose if focused
         end
 
-        private def ensure_attached
-          # Trigger Playwright's stale-element check without changing focus.
-          @element.enabled?
+        private def focused_element(frame)
+          # Local focus traversal through shadow roots and frames. Pressing the iframe
+          # itself would blur its editor. content_frame also works across origins.
+          focused = frame.evaluate_handle(<<~JAVASCRIPT)
+            () => {
+              let element = document.activeElement;
+              while (element && element.shadowRoot && element.shadowRoot.activeElement)
+                element = element.shadowRoot.activeElement;
+              return element;
+            }
+          JAVASCRIPT
+          child_frame = focused.content_frame
+          return focused unless child_frame
+
+          focused.dispose
+          focused_element(child_frame)
         end
       end
 
@@ -745,7 +731,9 @@ module Capybara
       end
 
       def send_keys(*args)
-        SendKeys.new(@element, args).execute
+        assert_element_not_stale do
+          KeyboardInput.new(@element, capybara_default_wait_time).send_keys(*args)
+        end
       end
 
       class SendKeys
@@ -817,93 +805,63 @@ module Capybara
           command: 'Meta',
         }
 
-        def initialize(element_or_keyboard, keys)
-          @element_or_keyboard = element_or_keyboard
+        def initialize(keyboard, keys)
+          @keyboard = keyboard
+          @executables = []
+          add_keys(keys)
+        end
 
-          holding_keys = []
-          @executables = keys.each_with_object([]) do |key, executables|
-            if MODIFIERS[key]
-              holding_keys << key
-            else
-              if holding_keys.empty?
-                case key
-                when String
-                  executables << TypeText.new(key)
-                when Symbol
-                  executables << PressKey.new(
-                    key: key_for(key),
-                    modifiers: [],
-                  )
-                when Array
-                  _key = key.last
-                  code =
-                    if _key.is_a?(String) && _key.length == 1
-                      _key
-                    elsif _key.is_a?(Symbol)
-                      key_for(_key)
-                    else
-                      raise ArgumentError.new("invalid key: #{_key}. Symbol of 1-length String is expected.")
-                    end
-                  modifiers = key.first(key.size - 1).map { |k| modifier_for(k) }
-                  executables << PressKey.new(
-                    key: code,
-                    modifiers: modifiers,
-                  )
-                end
-              else
-                modifiers = holding_keys.map { |k| modifier_for(k) }
-
-                case key
-                when String
-                  key.each_char do |char|
-                    executables << PressKey.new(
-                      key: char,
-                      modifiers: modifiers,
-                    )
-                  end
-                when Symbol
-                  executables << PressKey.new(
-                    key: key_for(key),
-                    modifiers: modifiers
-                  )
+        private def add_keys(keys, modifiers = [])
+          keys.each do |key|
+            case key
+            when Array
+              add_keys(key, modifiers.dup)
+            when String
+              key.scan(/\r\n|[\r\n\t]|[^\r\n\t]+/).each do |part|
+                case part
+                when "\t"
+                  add_key('Tab', modifiers)
+                when "\r", "\n", "\r\n"
+                  add_key('Enter', modifiers)
                 else
-                  raise ArgumentError.new("#{key} cannot be handled with holding key #{holding_keys}")
+                  if modifiers.empty?
+                    @executables << TypeText.new(part)
+                  else
+                    part.each_char { |character| add_key(character, modifiers) }
+                  end
                 end
               end
+            when Symbol
+              if MODIFIERS.key?(key)
+                modifiers << MODIFIERS.fetch(key)
+              elsif key == :null
+                modifiers.clear
+              else
+                add_key(KEYS.fetch(key) { raise ArgumentError, "invalid key specified: #{key}" }, modifiers)
+              end
+            else
+              raise ArgumentError, "invalid key specified: #{key.inspect}"
             end
           end
         end
 
-        private def modifier_for(modifier)
-          MODIFIERS[modifier] or raise ArgumentError.new("invalid modifier specified: #{modifier}")
-        end
-
-        private def key_for(key)
-          KEYS[key] or raise ArgumentError.new("invalid key specified: #{key}")
+        private def add_key(key, modifiers)
+          @executables << PressKey.new(key: key, modifiers: modifiers)
         end
 
         def execute
-          @executables.each do |executable|
-            executable.execute_for(@element_or_keyboard)
-          end
+          @executables.each { |executable| executable.execute_for(@keyboard) }
         end
 
         class PressKey
           def initialize(key:, modifiers:)
-            # Shift requires an explicitly uppercase a-z key to produce the correct output
-            # See https://playwright.dev/docs/input#keys-and-shortcuts
-            key = key.upcase if modifiers == [MODIFIERS[:shift]] && key.match?(/^[a-z]$/)
-
-            # puts "PressKey: key=#{key} modifiers: #{modifiers}"
-            if modifiers.empty?
-              @key = key
-            else
-              @key = (modifiers + [key]).join('+')
-            end
+            # Playwright needs the uppercase key when Shift modifies a letter.
+            key = key.upcase if modifiers.include?('Shift') && key.match?(/^[a-z]$/)
+            @key = (modifiers + [key]).uniq.join('+')
           end
 
-          def execute_for(element)
-            element.press(@key)
+          def execute_for(keyboard)
+            keyboard.press(@key)
           end
         end
 
@@ -912,8 +870,8 @@ module Capybara
             @text = text
           end
 
-          def execute_for(element)
-            element.type(@text)
+          def execute_for(keyboard)
+            keyboard.type(@text)
           end
         end
       end

data/lib/capybara/playwright/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Playwright
-    VERSION = '0.5.13'
+    VERSION = '0.5.14'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-playwright-driver
 version: !ruby/object:Gem::Version
-  version: 0.5.13
+  version: 0.5.14
 platform: ruby
 authors:
 - YusukeIwaki