capybara-lockstep 2.2.3 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09d7ce0bf2ef366b5839f874f614e6ddee1f71bb8ab38f7d4f42340b8d832bf5'
-  data.tar.gz: 538d699762cdb5c1d547c2feccdccbabc1d07582f32f6b6fb0b4a52b8b9b99f6
+  metadata.gz: a4d067d73940b41b147af2e4acfba7ec42258be32c9a953178a6566b2ea02d47
+  data.tar.gz: b5acd048164fa863786b6b3f60695877d7052f87a14207f9d4e851c5334cca13
 SHA512:
-  metadata.gz: 3c12ea7389c84bd96e19aa109df3065d3bc3491dccc757194d0de67396cd4a267c4cef4bcb6a5f9ac55452ece41ff2a593cd4263639c1eae033ec96d9931c84b
-  data.tar.gz: 6f53dc9d09ef6923add0774bad4dc80ab5f5da9d16ed0d8ec5fbe3fb6121963e64beec4ff4f733f2381d2c1d5a46b4e4466c3cc7f108538456b2a98be9974ef9
+  metadata.gz: a3181f8725182d43722551b220759f705742b0d2e88bea4b244fae812a3ab2390465adb62b07c8a3e59f9c3959a635ca286825d4c6dc5eae4db35101e0635221
+  data.tar.gz: 64dd439ed268526b97543ccab8f64396a3ea83a6cd4eb39ba9e55b04155c69d1029afe5761bba27c7fe04bc8f62e59ff157527ce02f1b492aae432f70e2e071a

data/.github/workflows/test.yml

@@ -12,7 +12,7 @@ on:
     - main
 jobs:
   test:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 3
     strategy:
       fail-fast: false
@@ -20,12 +20,22 @@ jobs:
         include:
         - ruby: 2.7.2
           gemfile: Gemfile
+          capybara_driver: selenium
+        - ruby: 2.7.2
+          gemfile: Gemfile
+          capybara_driver: cuprite
         - ruby: 3.2.0
           gemfile: Gemfile
+          capybara_driver: selenium
+        - ruby: 3.4.1
+          gemfile: Gemfile
+          capybara_driver: selenium
         - ruby: 3.4.1
           gemfile: Gemfile
+          capybara_driver: cuprite
     env:
       BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
+      CAPYBARA_DRIVER: "${{ matrix.capybara_driver }}"
     steps:
     - uses: actions/checkout@v3
     - name: Install Chrome
@@ -34,6 +44,7 @@ jobs:
       run: chrome --version
     - name: Install ChromeDriver
       uses: nanasess/setup-chromedriver@master
+      if: "${{ matrix.capybara_driver == 'selenium' }}"
     - name: Install ruby
       uses: ruby/setup-ruby@v1
       with:

data/.gitignore

@@ -11,3 +11,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+.byebug_history

data/CHANGELOG.md

@@ -12,6 +12,9 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 -
 
+# 2.3.0
+
+- Added support for cuprite as the capybara driver
 
 # 2.2.3
 

data/Gemfile

@@ -17,6 +17,7 @@ gem 'byebug'
 gem 'gemika', '>= 0.8.1'
 gem 'capybara', '>= 3'
 gem 'selenium-webdriver', '>= 4'
+gem 'cuprite'
 
 # The following gems were previously "default gems" (always available) and are now
 # "bundled gems" (need to be explicitly required). Not all gems in our Gemfile.lock (dev only) do that yet.

data/Gemfile.lock

@@ -1,11 +1,10 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (2.2.3)
+    capybara-lockstep (2.3.0)
       activesupport (>= 4.2)
       capybara (>= 3.0)
       ruby2_keywords
-      selenium-webdriver (>= 4.0)
 
 GEM
   remote: https://rubygems.org/
@@ -32,9 +31,18 @@ GEM
       xpath (~> 3.2)
     childprocess (4.1.0)
     concurrent-ruby (1.1.10)
+    cuprite (0.17)
+      capybara (~> 3.0)
+      ferrum (~> 0.17.0)
     daemons (1.4.1)
     diff-lcs (1.5.1)
     eventmachine (1.2.7)
+    ferrum (0.17.1)
+      addressable (~> 2.5)
+      base64 (~> 0.2)
+      concurrent-ruby (~> 1.1)
+      webrick (~> 1.7)
+      websocket-driver (~> 0.7)
     gemika (0.8.1)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
@@ -93,6 +101,11 @@ GEM
     tilt (2.3.0)
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
+    webrick (1.9.1)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
     zeitwerk (2.6.0)
@@ -107,6 +120,7 @@ DEPENDENCIES
   byebug
   capybara (>= 3)
   capybara-lockstep!
+  cuprite
   gemika (>= 0.8.1)
   puma
   rake (~> 13.0)

data/README.md

@@ -120,9 +120,9 @@ Installation
 Check if your application satisfies all requirements for capybara-lockstep:
 
 - Capybara 2.0 or higher.
-- Your Capybara driver must use [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver/) 3.0 or higher. capybara-lockstep deactivates itself for any other driver.
+- Your Capybara driver must use [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver/) (>3.0) or [cuprite](https://github.com/rubycdp/cuprite). capybara-lockstep deactivates itself for any other driver.
   There is a [fork](https://github.com/Skalar/capybara-lockstep/tree/playwright-driver) with support for [capybara-playwright-driver](https://github.com/YusukeIwaki/capybara-playwright-driver).
-- This gem was only tested with a Selenium-controlled Chrome browser. [Chrome in headless mode](https://makandracards.com/makandra/492109-running-capybara-tests-in-headless-chrome) is recommended, but not required.
+- This gem was only tested with a Chrome browser. [Chrome in headless mode](https://makandracards.com/makandra/492109-running-capybara-tests-in-headless-chrome) is recommended, but not required.
 - This gem was only tested with Rails, but there's no Rails dependency.
 
 
@@ -460,10 +460,20 @@ Pull requests are welcome on GitHub at <https://github.com/makandra/capybara-loc
 
 After checking out the repo, run `bin/setup` to install dependencies.
 
-Then, run `rake spec` to run the tests.
+For running tests see [Running tests locally](#running-tests-locally) below
 
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Running tests locally
+
+capybara-lockstep supports both the `selenium-webdriver` and `cuprite` as drivers for capybara.
+
+To run all the tests for all supported drivers, run `rake spec:all`.
+
+To run all the tests for a specific driver, run `rake spec:selenium` or `rake spec:cuprite`.
+
+The driver can also be specified by setting `CAPYBARA_DRIVER`, so if you want to run a single test for cuprite you can run `CAPYBARA_DRIVER=cuprite bundle exec rspec "spec/features/spec_spec.rb[1]"`.
+
 ### Manually testing a change
 
 To test an unrelased change with a test suite, we recommend to temporarily link the local repository from your test suites's `Gemfile`:
@@ -476,9 +486,12 @@ As an alternative you may also install this gem onto your local machine by runni
 
 ### Releasing a new version
 
-- Update the version number in `version.rb`
- - Run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
- - If RubyGems publishing seems to freeze, try entering your OTP code.
+- Update the version number in `version.rb`. Use Semantic Versioning.
+- Run `bundle install` so our `Gemfile.lock` (for development) gets the new version.
+- Update `CHANGELOG.md`.
+- Commit and push your changes.
+- Run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- If RubyGems publishing seems to freeze, try entering your OTP code.
 
 
 ## License

data/Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require_relative "tasks/spec_tasks"
 
 RSpec::Core::RakeTask.new(:spec)
 

data/capybara-lockstep.gemspec

@@ -29,7 +29,6 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   spec.add_dependency "capybara", ">= 3.0"
-  spec.add_dependency "selenium-webdriver", ">= 4.0"
   spec.add_dependency "activesupport", ">= 4.2"
   spec.add_dependency "ruby2_keywords"
 

data/lib/capybara-lockstep/capybara_ext.rb

@@ -176,6 +176,7 @@ driver_specific_node_classes = [
   (Capybara::Selenium::SafariNode  if defined?(Capybara::Selenium::SafariNode)),
   (Capybara::Selenium::EdgeNode    if defined?(Capybara::Selenium::EdgeNode)),
   (Capybara::Selenium::IENode      if defined?(Capybara::Selenium::IENode)),
+  (Capybara::Cuprite::Node         if defined?(Capybara::Cuprite::Node)),
 ].compact.freeze
 
 # For other browsers (like the :remote browser) we instead get a generic node class.

data/lib/capybara-lockstep/client/cuprite.rb

@@ -0,0 +1,39 @@
+module Capybara
+  module Lockstep
+    class Client::Cuprite < Client
+
+      def with_synchronization_error_handling
+        yield
+
+      rescue ::Ferrum::ScriptTimeoutError
+        timeout_message = "Could not synchronize client within #{timeout} seconds"
+        log timeout_message
+        if timeout_with == :error
+          raise Timeout, timeout_message
+        else
+          # Don't raise an error, this may happen if the server is slow to respond.
+          # We will retry on the next Capybara synchronize call.
+        end
+
+      rescue ::Ferrum::JavaScriptError => e
+        if e.message.include?('unload')
+          log ERROR_NAVIGATED_AWAY
+        else
+          unhandled_synchronize_error(e)
+        end
+
+      rescue ::Ferrum::BrowserError => e
+        if e.message.include?('Session with given id not found.')
+          log ERROR_WINDOW_CLOSED
+          # Don't raise an error, this will happen in an innocent test where a click closes a window.
+          # We will retry on the next Capybara synchronize call.
+        else
+          unhandled_synchronize_error(e)
+        end
+      rescue StandardError => e
+        unhandled_synchronize_error(e)
+      end
+
+    end
+  end
+end

data/lib/capybara-lockstep/client/selenium.rb

@@ -0,0 +1,41 @@
+module Capybara
+  module Lockstep
+    class Client::Selenium < Client
+
+      def with_synchronization_error_handling
+        yield
+      rescue ::Selenium::WebDriver::Error::ScriptTimeoutError
+        timeout_message = "Could not synchronize client within #{timeout} seconds"
+        log timeout_message
+        if timeout_with == :error
+          raise Timeout, timeout_message
+        else
+          # Don't raise an error, this may happen if the server is slow to respond.
+          # We will retry on the next Capybara synchronize call.
+        end
+      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
+        log ERROR_ALERT_OPEN
+        # Don't raise an error, this will happen in an innocent test where a click opens an alert.
+        # We will retry on the next Capybara synchronize call.
+      rescue ::Selenium::WebDriver::Error::NoSuchWindowError
+        log ERROR_WINDOW_CLOSED
+        # Don't raise an error, this will happen in an innocent test where a click closes a window.
+        # We will retry on the next Capybara synchronize call.
+      rescue ::Selenium::WebDriver::Error::JavascriptError => e
+        # When the URL changes while a script is running, my current selenium-webdriver
+        # raises a Selenium::WebDriver::Error::JavascriptError with the message:
+        # "javascript error: document unloaded while waiting for result".
+        # We will retry on the next Capybara synchronize call, by then we should see
+        # the new page.
+        if e.message.include?('unload')
+          log ERROR_NAVIGATED_AWAY
+        else
+          unhandled_synchronize_error(e)
+        end
+      rescue StandardError => e
+        unhandled_synchronize_error(e)
+      end
+
+    end
+  end
+end

data/lib/capybara-lockstep/client.rb

@@ -48,7 +48,7 @@ module Capybara
 
         start_time = Util.current_seconds
 
-        begin
+        with_synchronization_error_handling do
           Util.with_max_wait_time(timeout) do
             message_from_js = evaluate_async_script(<<~JS)
               let done = arguments[0]
@@ -84,41 +84,15 @@ module Capybara
               self.synchronized = true
             end
           end
-        rescue ::Selenium::WebDriver::Error::ScriptTimeoutError
-          timeout_message = "Could not synchronize client within #{timeout} seconds"
-          log timeout_message
-          if timeout_with == :error
-            raise Timeout, timeout_message
-          else
-            # Don't raise an error, this may happen if the server is slow to respond.
-            # We will retry on the next Capybara synchronize call.
-          end
-        rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
-          log ERROR_ALERT_OPEN
-          # Don't raise an error, this will happen in an innocent test where a click opens an alert.
-          # We will retry on the next Capybara synchronize call.
-        rescue ::Selenium::WebDriver::Error::NoSuchWindowError
-          log ERROR_WINDOW_CLOSED
-          # Don't raise an error, this will happen in an innocent test where a click closes a window.
-          # We will retry on the next Capybara synchronize call.
-        rescue ::Selenium::WebDriver::Error::JavascriptError => e
-          # When the URL changes while a script is running, my current selenium-webdriver
-          # raises a Selenium::WebDriver::Error::JavascriptError with the message:
-          # "javascript error: document unloaded while waiting for result".
-          # We will retry on the next Capybara synchronize call, by then we should see
-          # the new page.
-          if e.message.include?('unload')
-            log ERROR_NAVIGATED_AWAY
-          else
-            unhandled_synchronize_error(e)
-          end
-        rescue StandardError => e
-          unhandled_synchronize_error(e)
         end
       end
 
       private
 
+      def with_synchronization_error_handling
+        raise NoMethodError, "Implement in a driver specific subclass"
+      end
+
       def unhandled_synchronize_error(e)
         Lockstep.log "#{e.class.name} while synchronizing: #{e.message}"
         raise e
@@ -135,4 +109,3 @@ module Capybara
     end
   end
 end
-

data/lib/capybara-lockstep/configuration.rb

@@ -42,7 +42,7 @@ module Capybara
       end
 
       def mode
-        if javascript_driver?
+        if supported_driver?
           @mode.nil? ? :auto : @mode
         else
           :off
@@ -106,7 +106,7 @@ module Capybara
       end
 
       def send_config_to_browser(js)
-        return unless javascript_driver?
+        return unless supported_driver?
 
         begin
           Util.with_max_wait_time(2) do

data/lib/capybara-lockstep/errors.rb

@@ -2,5 +2,6 @@ module Capybara
   module Lockstep
     class Error < StandardError; end
     class Timeout < Error; end
+    class DriverNotSupportedError < StandardError; end
   end
 end

data/lib/capybara-lockstep/lockstep.rb

@@ -9,6 +9,8 @@ module Capybara
       alias synchronizing? synchronizing
 
       def unsynchronize
+        return if mode == :off
+
         client.synchronized = false
       end
 
@@ -28,7 +30,7 @@ module Capybara
 
         # The { lazy } option is a performance optimization that will prevent capybara-lockstep
         # from synchronizing multiple times in expressions like `page.find('.foo').find('.bar')`.
-        # The { lazy } option has nothing todo with :auto mode.
+        # The { lazy } option has nothing to do with :auto mode.
         #
         # With { lazy: true } we only synchronize when the Ruby-side thinks we're out of sync.
         # This saves us an expensive execute_script() roundtrip that goes to the browser and back.
@@ -69,7 +71,24 @@ module Capybara
       end
 
       def client
-        @client ||= Client.new
+        if @client.nil? || !@client.is_a?(client_class)
+          # (Re-)Initialize client if missing or the current driver changes
+          @client = client_class.new
+        end
+
+        @client
+      end
+
+      def client_class
+        if selenium_driver?
+          Client::Selenium
+        elsif cuprite_driver?
+          Client::Cuprite
+        else
+          # This should never raise, as capybara lockstep should disable itself for any unsupported driver.
+          # When it still does, there is probably a bug within capybara lockstep.
+          raise DriverNotSupportedError, "The driver #{driver.class.name} is not supported by capybara-lockstep."
+        end
       end
 
     end

data/lib/capybara-lockstep/page_access.rb

@@ -7,8 +7,8 @@ module Capybara
 
       delegate :evaluate_script, :evaluate_async_script, :execute_script, :driver, to: :page
 
-      def javascript_driver?
-        driver.is_a?(Capybara::Selenium::Driver)
+      def supported_driver?
+        selenium_driver? || cuprite_driver?
       end
 
       def alert_present?
@@ -17,12 +17,25 @@ module Capybara
         #
         # Apparently, while an alert/confirm is open, Chrome will block any requests
         # to its `getLog` API. This causes Selenium to time out with a `Net::ReadTimeout` error
+        return false unless selenium_driver? # This issue is selenium-specific.
+
         page.driver.browser.switch_to.alert
         true
       rescue Capybara::NotSupportedByDriverError, ::Selenium::WebDriver::Error::NoSuchAlertError, ::Selenium::WebDriver::Error::NoSuchWindowError
         false
       end
 
+      private
+
+      def selenium_driver?
+        defined?(Capybara::Selenium::Driver) && driver.is_a?(Capybara::Selenium::Driver)
+      end
+
+      def cuprite_driver?
+        defined?(Capybara::Cuprite::Driver) && driver.is_a?(Capybara::Cuprite::Driver)
+      end
+
+
     end
   end
 end

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "2.2.3"
+    VERSION = "2.3.0"
   end
 end

data/lib/capybara-lockstep.rb

@@ -1,5 +1,21 @@
 require 'capybara'
-require 'selenium-webdriver'
+
+selenium_loaded = begin
+  require 'selenium-webdriver'
+  true
+rescue LoadError
+  false
+end
+
+cuprite_loaded = begin
+  require 'capybara/cuprite'
+  true
+rescue LoadError
+  false
+end
+
+raise LoadError, "capybara-lockstep requires either selenium-webdriver or cuprite" unless selenium_loaded || cuprite_loaded
+
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/module/delegation'
 require 'active_support/lazy_load_hooks'
@@ -20,4 +36,6 @@ require_relative 'capybara-lockstep/capybara_ext'
 require_relative 'capybara-lockstep/helper'
 require_relative 'capybara-lockstep/server'
 require_relative 'capybara-lockstep/client'
+require_relative 'capybara-lockstep/client/selenium'
+require_relative 'capybara-lockstep/client/cuprite'
 require_relative 'capybara-lockstep/middleware'

data/tasks/spec_tasks.rb

@@ -0,0 +1,22 @@
+namespace :spec do
+  CAPYBARA_DRIVERS = %w[selenium cuprite]
+
+  desc "Run all tests for all drivers"
+  task :all do
+    CAPYBARA_DRIVERS.each do |driver|
+      run_specs driver
+    end
+  end
+
+  CAPYBARA_DRIVERS.each do |driver|
+    task driver do
+      run_specs driver
+    end
+  end
+
+  def run_specs(driver)
+    puts "Running specs using #{driver} as the capybara driver:\n"
+    sh "CAPYBARA_DRIVER=#{driver} bundle exec rake spec"
+  end
+
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 2.2.3
+  version: 2.3.0
 platform: ruby
 authors:
 - Henning Koch
 bindir: exe
 cert_chain: []
-date: 2025-03-17 00:00:00.000000000 Z
+date: 2025-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -23,20 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: selenium-webdriver
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -87,6 +73,8 @@ files:
 - lib/capybara-lockstep.rb
 - lib/capybara-lockstep/capybara_ext.rb
 - lib/capybara-lockstep/client.rb
+- lib/capybara-lockstep/client/cuprite.rb
+- lib/capybara-lockstep/client/selenium.rb
 - lib/capybara-lockstep/configuration.rb
 - lib/capybara-lockstep/errors.rb
 - lib/capybara-lockstep/helper.js
@@ -104,6 +92,7 @@ files:
 - media/logo.light.text.svg
 - media/makandra-with-bottom-margin.dark.svg
 - media/makandra-with-bottom-margin.light.svg
+- tasks/spec_tasks.rb
 homepage: https://github.com/makandra/capybara-lockstep
 licenses:
 - MIT