capybara-lockstep 2.3.2 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc60ce49170390b7a2160291bcee08a08a22bceacaf58e12b2f2bc5ebadf484e
-  data.tar.gz: dd6c60d318fe9f336462a3dcff507acf0120036d8ea160a97a5125ab94dc4248
+  metadata.gz: eb5ab18d6ec37825a825c3da9fdde70e7203b68609242a8a4738cb3034a0c3b2
+  data.tar.gz: d74acc6c1c2b73bbeea372f91d54068c548723d28e46cf5a4a01520004d4ef1e
 SHA512:
-  metadata.gz: fcf26ef14e209a4fd8f6353c129fe9b88b97feb58dd787ebccddc3e19980802ebec1403a374cf580c1798ecf3bc30e365eba1218f40d3b0af3bbbc6f80ca9904
-  data.tar.gz: f8db9ee7dbc655724cab11b6f2e3a181ae182579ba78b5f193174b7a78951f407275e49dbceec0b10b4f41cb9abbdc28233a271b781ba686f4bc030e2b932c35
+  metadata.gz: d67cc0d38dc1ab56ff728010cfde78016b357ac5964ab70ed18b7d8173599129eb9ff06bfd4a5e84754698cc568bb14e78378334910afcdabb7a1055f8f1f1ea
+  data.tar.gz: 8a8e007d57eb6f2e661a158156aefe4844d26f1de755939040229da146ae32e850b26aacb674cbd02de0ddd196c8e4ee2a39d8b8cb6b526af85ad96eda2d930f

data/CHANGELOG.md

@@ -13,6 +13,13 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 -
 
 
+# 2.4.0 - 2026-10-15
+
+## Compatible changes
+
+- Skip the check for an open alert before synchronizing when the Selenium driver ignores unhandled prompts (`unhandled_prompt_behavior: 'ignore'` or `{ default: 'ignore' }`). Such a driver keeps the alert open while synchronizing, so the check only cost an additional roundtrip to the browser. Configure this with the new option `Capybara::Lockstep.check_alerts` (`true`, `false` or `nil` for auto-detection).
+
+
 # 2.3.2 - 2026-09-11
 
 ## Compatible changes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (2.3.2)
+    capybara-lockstep (2.4.0)
       activesupport (>= 7.0)
       capybara (>= 3.0)
 
@@ -65,7 +65,7 @@ GEM
     mustermann (3.0.0)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.6.1)
-    nokogiri (1.15.5)
+    nokogiri (1.19.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
     ostruct (0.6.3)

data/README.md

@@ -184,7 +184,7 @@ use Capybara::Lockstep::Middleware
 ### Configuring Selenium WebDriver (recommended)
 
 By default, webdrivers will automatically dismiss any user prompts (like alerts) when trying to perform an action.
-While capybara-lockstep carefully detects alerts before synchronizing, and will skip interaction with the browser to avoid accidentally dismissing alerts, it can not synchronize around some rare race conditions.
+With this default, capybara-lockstep checks for an open alert before synchronizing, and will skip interaction with the browser to avoid accidentally dismissing alerts. However, it can not synchronize around some rare race conditions, and the check costs an additional roundtrip to the browser.
 
 [We recommend](https://makandracards.com/makandra/617366-how-to-configure-selenium-webdriver-to-not-automatically-close-alerts-or-other-browser-dialogs) you configure your webdriver to not automatically dismiss user prompts by setting the "unhandled prompt behavior" capability to [`ignore`](https://w3c.github.io/webdriver/#dfn-known-prompt-handling-approaches-table). Using "ignore", errors are raised like with the default behavior, but user prompts are kept open.
 
@@ -199,6 +199,18 @@ Capybara.register_driver(:selenium) do |app|
 end
 ```
 
+When your driver ignores user prompts, capybara-lockstep no longer checks for an open alert before synchronizing. The driver keeps the alert open and capybara-lockstep retries synchronization on the next Capybara command. This also works when you configure the capability by prompt type, e.g. `unhandled_prompt_behavior: { default: 'ignore' }`, as long as alerts, confirms and prompts are all ignored. Note that selenium-webdriver 4.35 and older convert such a map to a string when passed through `Options`. On these versions, pass it as `Selenium::WebDriver::Remote::Capabilities.new(unhandled_prompt_behavior: { default: 'ignore' })` alongside your options.
+
+You can override this detection:
+
+```ruby
+Capybara::Lockstep.check_alerts = true  # always check for an open alert before synchronizing
+Capybara::Lockstep.check_alerts = false # never check for an open alert before synchronizing
+Capybara::Lockstep.check_alerts = nil   # check unless the driver ignores user prompts (default)
+```
+
+Only disable the check if your driver keeps alerts open, otherwise synchronization will dismiss them.
+
 ### Verify successful integration
 
 capybara-lockstep will automatically patch Capybara to wait for the browser after every command.

data/lib/capybara-lockstep/client.rb

@@ -49,9 +49,9 @@ module Capybara
           return
         end
 
-        # Running the synchronization script while an alert is open would close the alert,
-        # most likely causing subsequent expectations to fail.
-        if alert_present?
+        # Unless the driver ignores unhandled prompts, running the synchronization script while an alert
+        # is open would close the alert, most likely causing subsequent expectations to fail.
+        if check_alerts? && alert_present?
           log ERROR_ALERT_OPEN
           # Don't raise an error, this will happen in an innocent test.
           # We will retry on the next Capybara synchronize call.
@@ -110,6 +110,10 @@ module Capybara
         raise e
       end
 
+      def check_alerts?
+        Lockstep.check_alerts?
+      end
+
       def timeout
         Lockstep.timeout
       end

data/lib/capybara-lockstep/configuration.rb

@@ -18,6 +18,16 @@ module Capybara
         @timeout_with = action&.to_sym
       end
 
+      def check_alerts?
+        # A driver that ignores unhandled prompts keeps an alert open while running our synchronization script.
+        # It raises an UnexpectedAlertOpenError instead, which we handle like an open alert.
+        @check_alerts.nil? ? !unhandled_prompts_ignored? : @check_alerts
+      end
+
+      def check_alerts=(value)
+        @check_alerts = value
+      end
+
       def debug
         @debug.nil? ? false : @debug
       end

data/lib/capybara-lockstep/page_access.rb

@@ -25,6 +25,23 @@ module Capybara
         false
       end
 
+      def unhandled_prompts_ignored?
+        return false unless selenium_driver?
+
+        # The capabilities were returned when the session was created, so this does not talk to the browser.
+        # The behavior is either a string ("ignore") or a map by prompt type ({ "default" => "ignore" }).
+        behavior = page.driver.browser.capabilities[:unhandled_prompt_behavior]
+
+        if behavior.is_a?(Hash)
+          # We don't consider "beforeUnload" prompts: the string form doesn't apply to them, WebDriver accepts them instead.
+          %w[alert confirm prompt].all? do |type|
+            behavior.fetch(type) { behavior['default'] } == 'ignore'
+          end
+        else
+          behavior == 'ignore'
+        end
+      end
+
       def selenium_driver?
         defined?(Capybara::Selenium::Driver) && driver.is_a?(Capybara::Selenium::Driver)
       end

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "2.3.2"
+    VERSION = "2.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 2.3.2
+  version: 2.4.0
 platform: ruby
 authors:
 - Henning Koch