capybara-playwright-driver 0.5.10 → 0.5.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9766817ce50a7580acf4f72c062780da5a2363ea838dea3a8f17207c359c144
-  data.tar.gz: 5b48eb5b0eb4145088457e8b0c1a26c5843f80dc3e3d9acf120c095fd2d7691a
+  metadata.gz: 4a90dd1edbae8b79e2f4d7eac72dcc8014e8d9e491730cbffa20be906c74ee5c
+  data.tar.gz: 729834c2bd8e56d523230e043f3d148777a89e2870da1624294d109eadd9434a
 SHA512:
-  metadata.gz: d7b079c7c184643a16cfae94e7aaafd325460a3a13e3ece9cf453b127045a44a8ea008b29b65c326325ad3cbb7b3a8f092ff325267df512ac3f1645565ef6baa
-  data.tar.gz: 46290aabe5623d54094efa2cd30369261ca32525b99835e0f6e393ddc48de3e9d1e21011e64cd61dfd00531bf05818dab69525c1cb450f9f2d46679b9c19b0c5
+  metadata.gz: 9b674a26ae213904eacec537a259f9111c5c4686d2317691bfe6bd965ad9fe4d57bad3dfb701cb2f456676f7a9d50ed94b50fb94723f83055b1bd79cb2c3d95c
+  data.tar.gz: 350f3c693c186594ccac2aa32e05cfd762f7baa069e01ebd6df8d20c744a3e72dfdfdd03a29728fcce77b5b173bd3bc6a2efcaedb55ca66fde43b8d55340bd9b

data/AGENTS.md

@@ -106,6 +106,11 @@ end
 - Prefer concise Ruby that reads top-to-bottom without carrying unnecessary temporary state.
 - Prefer small private helper objects only when they reduce complexity. Once extracted, give them Ruby-like method names and keep their public surface minimal.
 
+## Test Style
+- Avoid assertion roulette. Each example must verify one clearly named behavior so a failure identifies the broken behavior directly.
+- Do not use loops, parameter tables, or metaprogramming to generate examples for distinct public operations. Write an explicit `it` block for each operation, even when their setup and expectations are similar.
+- Split independent expectations into separate examples. Keep multiple expectations together only when they jointly describe one inseparable outcome.
+
 ## How to execute RSpec or Ruby
 
 `ruby` uses macOS system ruby interpreter (typically 2.6 or older). rbenv should be used.

data/README.md

@@ -26,13 +26,14 @@ Capybara.save_path = 'tmp/capybara'
 # run
 Capybara.app_host = 'https://github.com'
 visit '/'
-first('div.search-input-container').click
-fill_in('query-builder-test', with: 'Capybara')
+find('button[aria-label^="Search or jump to"]').click
+search_field = find('input[aria-label="Search or jump to"]')
+search_field.fill_in(with: 'Capybara')
 
 ## [REMARK] We can use Playwright-native selector and action, instead of Capybara DSL.
-# first('[aria-label="Capybara, Search all of GitHub"]').click
+# search_field.send_keys(:enter)
 page.driver.with_playwright_page do |page|
-  page.get_by_label('Capybara, Search all of GitHub').click
+  page.get_by_label('Search or jump to', exact: true).press('Enter')
 end
 
 all('[data-testid="results-list"] h3').each do |li|
@@ -43,6 +44,38 @@ end
 
 Refer the [documentation](https://playwright-ruby-client.vercel.app/docs/article/guides/rails_integration) for more detailed configuration.
 
+## Selenium compatibility
+
+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
+algorithm. When exact whitespace is not part of an assertion, use Capybara's `normalize_ws: true` option:
+
+```ruby
+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:
+
+```ruby
+editor.send_keys(:end, '@') # The page moves focus to an autocomplete control.
+editor.send_keys(:end, 'alice')
+```
+
+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
+`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
+speed matters more than those events, consider using `fill` directly:
+
+```ruby
+page.driver.with_playwright_page { |playwright_page| playwright_page.get_by_label('Body').fill(large_value) }
+```
+
 ## Development
 
 Prepare to run tests:

data/lib/capybara/playwright/browser.rb

@@ -94,15 +94,25 @@ module Capybara
       end
 
       def refresh
-        if firefox?
-          # ref: https://github.com/microsoft/playwright/issues/39738
-          @playwright_page.capybara_current_frame.evaluate('() => { location.reload(true) }')
-        else
-          assert_page_alive {
+        assert_page_alive {
+          if firefox?
+            # Preserve POST requests: https://github.com/microsoft/playwright/issues/39738
+            # Mark the old document so pushState and an earlier navigation's load
+            # cannot satisfy the wait for the reloaded document.
+            @playwright_page.evaluate(<<~JAVASCRIPT)
+              () => {
+                document[Symbol.for('capybara-playwright-driver.refresh')] = true;
+                location.reload(true);
+              }
+            JAVASCRIPT
+            @playwright_page.wait_for_function(<<~JAVASCRIPT, polling: 10, timeout: @default_navigation_timeout).dispose
+              () => !document[Symbol.for('capybara-playwright-driver.refresh')] && document.readyState === 'complete'
+            JAVASCRIPT
+          else
             response = @playwright_page.reload
             @playwright_page.capybara_set_last_response(response)
-          }
-        end
+          end
+        }
       end
 
       def find_xpath(query, **options)

data/lib/capybara/playwright/node.rb

@@ -1,22 +1,38 @@
 module Capybara
   module ElementClickOptionPatch
     def perform_click_action(keys, **options)
-      # Expose `wait` value to the block given to perform_click_action.
-      if options[:wait].is_a?(Numeric)
-        options[:_playwright_wait] = options[:wait]
-      end
+      return super unless driver.is_a?(Capybara::Playwright::Driver)
 
-      # Playwright has own auto-waiting feature.
-      # So disable Capybara's retry logic.
-      if driver.is_a?(Capybara::Playwright::Driver)
-        options[:wait] = 0
-      end
+      wait = options[:wait]
+
+      # Expose `wait` value to the block given to perform_click_action.
+      options[:_playwright_wait] = wait if wait.is_a?(Numeric)
+      options[:wait] = 0 if wait == false
 
+      # Playwright waits for actionability while Capybara retries replaced elements.
       super
     end
   end
   Node::Element.prepend(ElementClickOptionPatch)
 
+  module ElementDragToPatch
+    def drag_to(target, **options)
+      return super unless driver.is_a?(Capybara::Playwright::Driver)
+
+      synchronize do
+        begin
+          base.drag_to(target.base, **options)
+        rescue Capybara::Playwright::Node::StaleReferenceError
+          # Capybara's synchronize reloads only the source element.
+          target.reload if session_options.automatic_reload
+          raise
+        end
+      end
+      self
+    end
+  end
+  Node::Element.prepend(ElementDragToPatch)
+
   module WithElementHandlePatch
     def with_playwright_element_handle(&block)
       raise ArgumentError.new('block must be given') unless block
@@ -263,6 +279,21 @@ module Capybara
 
       class NotActionableError < StandardError ; end
       class StaleReferenceError < StandardError ; end
+      class MissingBoundingBoxError < StandardError ; end
+      class DragInterruptedError < StandardError ; end
+
+      class ElementGeometry
+        def self.bounding_box(element)
+          box = element.bounding_box
+          return box if box
+
+          unless element.evaluate('element => element.isConnected')
+            raise StaleReferenceError, 'Element is not attached to the DOM'
+          end
+
+          raise MissingBoundingBoxError, 'Element is attached but has no bounding box'
+        end
+      end
 
       def all_text
         assert_element_not_stale {
@@ -284,7 +315,7 @@ module Capybara
               if (el.nodeName == 'TEXTAREA'){
                 return el.textContent;
               } else if (el instanceof SVGElement) {
-                return el.textContent;
+                return el.textContent.replace(/\\n+/g, '\\n');
               } else {
                 return el.innerText;
               }
@@ -292,7 +323,6 @@ module Capybara
           JAVASCRIPT
           text.to_s.scrub.gsub(/\A[[:space:]&&[^\u00a0]]+/, '')
               .gsub(/[[:space:]&&[^\u00a0]]+\z/, '')
-              .gsub(/\n+/, "\n")
               .tr("\u00a0", ' ')
         }
       end
@@ -368,7 +398,9 @@ module Capybara
             end
           end
 
-        settable_class.new(@element, capybara_default_wait_time, @internal_logger).set(value, **options)
+        assert_element_not_stale do
+          settable_class.new(@element, capybara_default_wait_time, @internal_logger).set(value, **options)
+        end
       rescue ::Playwright::TimeoutError => err
         raise NotActionableError.new(err)
       end
@@ -406,6 +438,7 @@ module Capybara
             existing_text.length.times { @element.press('Backspace', timeout: @timeout) }
           when :none
             @element.press('End', timeout: @timeout)
+            ensure_attached
           when Array
             @internal_logger.warn "options { clear: #{options[:clear]} } is ignored"
           end
@@ -417,51 +450,91 @@ module Capybara
             text = text[0...-1]
           end
 
-          set_text(text, append: options[:clear] == :none)
+          keyboard = @element.owner_frame.page.keyboard
+          set_text(text, append: options[:clear] == :none, keyboard: keyboard)
 
-          if press_enter
-            @element.press('Enter', timeout: @timeout)
-          end
+          keyboard.press('Enter') if press_enter
         rescue ::Playwright::TimeoutError
           raise if @element.editable?
 
           @internal_logger.info("Node#set: element is not editable. #{@element}")
         end
 
-        private def set_text(text, append:)
+        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")
+
           if text.include?("\t")
-            type_tab_separated_text(text, append: append)
+            type_tab_separated_text(text, append: append, keyboard: keyboard)
             return
           end
 
-          grapheme_clusters = text.scan(/\X/)
-          fill_text = grapheme_clusters[0...-1].join
-          typed_text = grapheme_clusters[-1].to_s
-
           if append
-            @element.type(fill_text, timeout: @timeout) unless fill_text.empty?
+            type_text(keyboard, text)
+          elsif text.empty?
+            @element.fill('', timeout: @timeout)
           else
-            @element.fill(fill_text, timeout: @timeout)
+            @element.select_text(timeout: @timeout)
+            replace_text(keyboard, text)
           end
-          @element.type(typed_text, timeout: @timeout) unless typed_text.empty?
         end
 
-        private def type_tab_separated_text(text, append:)
-          head, *tail = text.split("\t", -1)
-          set_text(head, append: append)
-          keyboard = @element.owner_frame.page.keyboard
+        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?
+          end
+
+          type_lines(keyboard, tail)
+        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)
+        end
 
-          tail.each do |part|
-            keyboard.press('Tab')
+        private def type_lines(keyboard, parts)
+          parts.each do |part|
+            keyboard.press('Enter')
             keyboard.type(part) unless part.empty?
           end
         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
+        end
+
+        private def ensure_attached
+          # Trigger Playwright's stale-element check without changing focus.
+          @element.enabled?
+        end
       end
 
       class FileUpload < Settable
@@ -570,20 +643,26 @@ module Capybara
       end
 
       def click(keys = [], **options)
-        click_options = ClickOptions.new(@element, keys, options, capybara_default_wait_time)
-        @element.click(**click_options.as_params)
+        assert_element_not_stale do
+          click_options = ClickOptions.new(@element, keys, options, capybara_default_wait_time)
+          @element.click(**click_options.as_params)
+        end
       end
 
       def right_click(keys = [], **options)
-        click_options = ClickOptions.new(@element, keys, options, capybara_default_wait_time)
-        params = click_options.as_params
-        params[:button] = 'right'
-        @element.click(**params)
+        assert_element_not_stale do
+          click_options = ClickOptions.new(@element, keys, options, capybara_default_wait_time)
+          params = click_options.as_params
+          params[:button] = 'right'
+          @element.click(**params)
+        end
       end
 
       def double_click(keys = [], **options)
-        click_options = ClickOptions.new(@element, keys, options, capybara_default_wait_time)
-        @element.dblclick(**click_options.as_params)
+        assert_element_not_stale do
+          click_options = ClickOptions.new(@element, keys, options, capybara_default_wait_time)
+          @element.dblclick(**click_options.as_params)
+        end
       end
 
       class ClickOptions
@@ -653,7 +732,7 @@ module Capybara
 
         private def position
           if @offset_center
-            box = @element.bounding_box
+            box = ElementGeometry.bounding_box(@element)
 
             {
               x: @coords[:x] + box['width'] / 2,
@@ -840,11 +919,17 @@ module Capybara
       end
 
       def hover
-        @element.hover(timeout: capybara_default_wait_time)
+        assert_element_not_stale do
+          @element.hover(timeout: capybara_default_wait_time)
+        end
       end
 
-      def drag_to(element, **options)
-        DragTo.new(@page, @element, element.element, options).execute
+      def drag_to(target, **options)
+        assert_element_not_stale do
+          target.send(:assert_element_not_stale) do
+            DragTo.new(@page, @element, target.element, options, capybara_default_wait_time).execute
+          end
+        end
       end
 
       class DragTo
@@ -861,22 +946,28 @@ module Capybara
         # @param page [Playwright::Page]
         # @param source [Playwright::ElementHandle]
         # @param target [Playwright::ElementHandle]
-        def initialize(page, source, target, options)
+        def initialize(page, source, target, options, timeout)
           @page = page
           @source = source
           @target = target
           @options = options
+          @timeout = timeout
         end
 
         def execute
-          @source.scroll_into_view_if_needed
+          input_started = false
+          mouse_down = false
+          @target.wait_for_element_state('visible', timeout: @timeout)
+          @source.scroll_into_view_if_needed(timeout: @timeout)
 
-          # down
           position_from = center_of(@source)
+          center_of(@target)
           @page.mouse.move(*position_from)
+          input_started = true
+          mouse_down = true
           @page.mouse.down
 
-          @target.scroll_into_view_if_needed
+          @target.scroll_into_view_if_needed(timeout: @timeout)
 
           # move and up
           sleep_delay
@@ -885,20 +976,33 @@ module Capybara
             @page.mouse.move(*position_to, steps: 6)
             sleep_delay
             @page.mouse.up
+            mouse_down = false
           end
           sleep_delay
+        rescue StaleReferenceError, ::Playwright::Error => err
+          raise DragInterruptedError, "Drag was interrupted after input began: #{err.message}" if input_started
+
+          raise
+        ensure
+          @page.mouse.up if mouse_down
         end
 
         # @param element [Playwright::ElementHandle]
         private def center_of(element)
-          box = element.bounding_box
+          box = ElementGeometry.bounding_box(element)
+
           [box["x"] + box["width"] / 2, box["y"] + box["height"] / 2]
         end
 
-        private def with_key_pressing(keys, &block)
-          keys.each { |key| @page.keyboard.down(key) }
-          block.call
-          keys.each { |key| @page.keyboard.up(key) }
+        private def with_key_pressing(keys)
+          pressed_keys = []
+          keys.each do |key|
+            @page.keyboard.down(key)
+            pressed_keys << key
+          end
+          yield
+        ensure
+          pressed_keys.reverse_each { |key| @page.keyboard.up(key) }
         end
 
         # @returns Array<String>
@@ -1078,7 +1182,9 @@ module Capybara
       end
 
       def obscured?
-        @element.capybara_obscured?
+        assert_element_not_stale do
+          @element.capybara_obscured?
+        end
       end
 
       def checked?

data/lib/capybara/playwright/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Playwright
-    VERSION = '0.5.10'
+    VERSION = '0.5.12'
   end
 end

metadata

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