capybara-playwright-driver 0.5.9 → 0.5.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a319465a40c53ac5b47d86ccd4d15136c20dcf7f6dde6fe17b3906d44cb2fd94
-  data.tar.gz: 1e38fb6020a87a07e6eaa8e997084b3abd98a0a8d5cbec4e92819a960c525f62
+  metadata.gz: 4a90dd1edbae8b79e2f4d7eac72dcc8014e8d9e491730cbffa20be906c74ee5c
+  data.tar.gz: 729834c2bd8e56d523230e043f3d148777a89e2870da1624294d109eadd9434a
 SHA512:
-  metadata.gz: 5d1d8aeccb05f0c667c3b1a617cb1d2f19eb7fa096788a46b81985730f1a75b6ee7196ad952d2152c173b7401980090f738db399503b3ddceac097ced637678c
-  data.tar.gz: 141fd5024a9d322faf9031951e0f74a61426af350ed06d73017b2db90ec5b866e1af9b17edd5017e5c35f79f198cfa5916b220afcf621db9a2538c5fb50f443b
+  metadata.gz: 9b674a26ae213904eacec537a259f9111c5c4686d2317691bfe6bd965ad9fe4d57bad3dfb701cb2f456676f7a9d50ed94b50fb94723f83055b1bd79cb2c3d95c
+  data.tar.gz: 350f3c693c186594ccac2aa32e05cfd762f7baa069e01ebd6df8d20c744a3e72dfdfdd03a29728fcce77b5b173bd3bc6a2efcaedb55ca66fde43b8d55340bd9b

data/AGENTS.md

@@ -105,3 +105,16 @@ end
 ## General Guidance
 - 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.
+
+- Do not run the full `spec/capybara/playwright_spec.rb` or full RSpec suite locally; run broad coverage in GitHub Actions.
+- To run a focused Playwright compatibility check locally, use an example filter, for example:
+  `RBENV_VERSION=$(cat .ruby-version) ~/.rbenv/shims/bundle exec rspec spec/capybara/playwright_spec.rb --example fill_in`

data/Gemfile

@@ -15,6 +15,7 @@ gem 'rack-test_server'
 gem 'rake', '~> 13.0.3'
 gem 'rspec', '~> 3.11.0'
 gem 'rubocop-rspec'
+gem 'selenium-webdriver', '~> 4.34.0' if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.2')
 gem 'sinatra', '>= 1.4.0'
 gem 'webrick'
 gem 'websocket-driver'

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

@@ -89,9 +89,29 @@ module Capybara
         }
       end
 
+      private def firefox?
+        @playwright_browser.browser_type.name == 'firefox'
+      end
+
       def refresh
         assert_page_alive {
-          @playwright_page.capybara_current_frame.evaluate('() => { location.reload(true) }')
+          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
 
@@ -255,7 +275,8 @@ module Capybara
           when /Element is not attached to the DOM/,
             /Execution context was destroyed, most likely because of a navigation/,
             /Cannot find context with specified id/,
-            /Unable to adopt element handle from a different document/
+            /Unable to adopt element handle from a different document/,
+            /maybe frame was detached/
             # ignore error for retry
             @internal_logger.warn(err.message)
           else
@@ -318,16 +339,35 @@ module Capybara
 
       def window_size(handle)
         on_window(handle) do |page|
-          page.evaluate('() => [window.innerWidth, window.innerHeight]')
+          outer_window_size(page)
         end
       end
 
       def resize_window_to(handle, width, height)
         on_window(handle) do |page|
-          page.viewport_size = { width: width, height: height }
+          page.viewport_size = viewport_size_for(page, width, height)
         end
       end
 
+      # Capybara follows Selenium's outer window size semantics.
+      private def outer_window_size(page)
+        page.evaluate('() => [window.outerWidth || window.innerWidth, window.outerHeight || window.innerHeight]')
+      end
+
+      private def viewport_size_for(page, width, height)
+        inset_width, inset_height = page.evaluate(<<~JAVASCRIPT)
+          () => [
+            Math.max(0, (window.outerWidth || window.innerWidth) - window.innerWidth),
+            Math.max(0, (window.outerHeight || window.innerHeight) - window.innerHeight)
+          ]
+        JAVASCRIPT
+
+        {
+          width: [width - inset_width, 0].max,
+          height: [height - inset_height, 0].max
+        }
+      end
+
       def maximize_window(handle)
         @internal_logger.warn("maximize_window is not supported in Playwright driver")
         # incomplete in Playwright

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
@@ -258,11 +274,26 @@ module Capybara
       end
 
       private def capybara_default_wait_time
-        Capybara.default_max_wait_time * 1100 # with 10% buffer for allowing overhead.
+        Capybara.default_max_wait_time.to_f * 1100 # with 10% buffer for allowing overhead.
       end
 
       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,28 +438,102 @@ 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
 
           text = value.to_s
-          if press_enter = text.end_with?("\n")
+          if press_enter = text.end_with?("\r\n")
+            text = text[0...-2]
+          elsif press_enter = text.end_with?("\n")
             text = text[0...-1]
           end
 
-          if options[:clear] == :none
-            @element.type(text, timeout: @timeout)
-          else
+          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
+
+        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, keyboard: keyboard)
+            return
           end
 
-          if press_enter
+          if append
+            type_text(keyboard, text)
+          elsif text.empty?
+            @element.fill('', timeout: @timeout)
+          else
+            @element.select_text(timeout: @timeout)
+            replace_text(keyboard, text)
+          end
+        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?
           end
-        rescue ::Playwright::TimeoutError
-          raise if @element.editable?
 
-          @internal_logger.info("Node#set: element is not editable. #{@element}")
+          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
+
+        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
 
@@ -537,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
@@ -620,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,
@@ -807,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
@@ -828,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
@@ -852,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>
@@ -1045,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.9'
+    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.9
+  version: 0.5.12
 platform: ruby
 authors:
 - YusukeIwaki