capybara-lockstep 1.3.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 963aaa637f5f364f53f2a16087accf68035381e260aa4f7b0b2703d9a00a8abb
-  data.tar.gz: a48cdd51fc2fcf9e6d87d0d692e1448c90a639d36695b38e97d4a1183a44043c
+  metadata.gz: a9d5a9ec157f65f4efb9be5ac2b33c5447552eb70e8d118438a7aad763c57492
+  data.tar.gz: 2ddde2a3b51079603d8368f0ebbe81d5205d473beeaf301bb6bdd42c80c968d3
 SHA512:
-  metadata.gz: 8e2ab4e0227f8f3511e40b82ba0dfe80df61615547c6291db4f0d16bfa097a1863e612d57bd6d16c86bd5e5a4a9cd8be3f6040cdf3138071d487311dcfbb5b1f
-  data.tar.gz: 0060560ae282df788924891c6fff31cdf27491e79468f6c172154667466f66784bce54920e31d0838b96ad91d84904f8cb859573c390a5a327b8e4c40351d2f5
+  metadata.gz: b7d8723fe020460efad2e46555be0cf50d38e7398103e7462b8d0c21ac8260ee312bd8f7987e1a04ca471d6acb167b6b1e21565ef5ba73b19d021711bbb8743a
+  data.tar.gz: e364cdf67046d885d2f3b27404e258a37388cba10edb1f1f83f286fbc7023ff73f872558dfb33862e95ff6df2f3516bcd687a78094b27a4468ec86cc55a6032a

data/.github/workflows/test.yml

@@ -9,7 +9,7 @@ on:
     - master
   workflow_dispatch:
     branches:
-    - master  
+    - master
 jobs:
   test:
     runs-on: ubuntu-20.04
@@ -18,8 +18,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-        - ruby: 2.6.6
-          gemfile: Gemfile
         - ruby: 2.7.2
           gemfile: Gemfile
         - ruby: 3.2.0

data/.gitignore

@@ -1,3 +1,4 @@
+/todo.txt
 /.bundle/
 /.yardoc
 /_yardoc/

data/CHANGELOG.md

@@ -2,6 +2,21 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+
+# 2.0.0
+
+This major release detects many additional sources of flaky tests: 
+ 
+- We now synchronize before a user interaction. Previously we only synchronized before an observation. This could lead to race conditions when a test chained multiple interactions without [making an observation in between](https://makandracards.com/makandra/47336-fixing-flaky-e2e-tests#section-interleave-actions-and-expectations).
+- We now synchronize after a user interaction (e.g. after a click). Previously we only synchronized before an observation. This could lead to race conditions when a test made assertions without going through Capybara, e.g. by accessing the database or global state variables.
+- When a job ends (e.g. an AJAX request finishes) we now wait for one [JavaScript task](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/). This gives event listeners more time to schedule new async work.
+- We now wait one JavaScript task after `touchstart`, `mousedown`, `click` and `keydown` events. This gives event listeners more time to schedule async work after a user interaction.
+- You can now [wait while the backend server is busy](https://github.com/makandra/capybara-lockstep/#including-the-middleware-optional), by using `Capybara::Lockstep::Middleware` in your Rails or Rack app. We previously only waited for AJAX requests on the client, but using the middleware addresses some additional edge cases. For example, the middleware detects requests that were aborted on the frontend, but are still being processed by the backend.
+- You can [signal async work from the backend](https://github.com/makandra/capybara-lockstep/#on-the-backend), e.g. for background jobs. Note that you don't need to signal work for the regular request/response cycle, as this is detected automatically.
+
+Although we now cover a lot more edge cases, this releases will not slow down your test suite considerably.
+
+
 ## 1.3.1 - 2023-10-25
 
 Now synchronizes before and after `evaluate_script`.

data/Gemfile

@@ -5,17 +5,15 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in capybara-lockstep.gemspec
 gemspec
 
+gem 'activesupport', '~> 6.0'
 gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
-gem 'jasmine'
+gem "rspec-wait"
+gem 'sinatra'
 gem 'thin' # ruby 3 does not include a webserver
-gem 'chrome_remote'
-
+gem 'puma'
 gem 'byebug'
 gem 'gemika', '>= 0.8.1'
-
-gem 'activesupport', '~> 6.0'
-
-gem 'capybara', '= 3.36.0' # last version compatible with Ruby < 2.7, which is in our test matrix
-gem 'selenium-webdriver', '=4.1.0' # last version compatible with Ruby < 2.7, which is in our test matrix
+gem 'capybara', '>= 3'
+gem 'selenium-webdriver', '>= 4'

data/Gemfile.lock

@@ -1,11 +1,11 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (1.3.1)
-      activesupport (>= 3.2)
-      capybara (>= 2.0)
+    capybara-lockstep (2.0.0)
+      activesupport (>= 4.2)
+      capybara (>= 3.0)
       ruby2_keywords
-      selenium-webdriver (>= 3)
+      selenium-webdriver (>= 4.0)
 
 GEM
   remote: https://rubygems.org/
@@ -16,10 +16,10 @@ GEM
       minitest (>= 5.1)
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
-    addressable (2.8.1)
+    addressable (2.8.5)
       public_suffix (>= 2.0.2, < 6.0)
     byebug (11.1.3)
-    capybara (3.36.0)
+    capybara (3.39.2)
       addressable
       matrix
       mini_mime (>= 0.1.3)
@@ -29,36 +29,34 @@ GEM
       regexp_parser (>= 1.5, < 3.0)
       xpath (~> 3.2)
     childprocess (4.1.0)
-    chrome_remote (0.3.0)
-      websocket-driver (~> 0.6)
     concurrent-ruby (1.1.10)
-    daemons (1.3.1)
+    daemons (1.4.1)
     diff-lcs (1.3)
     eventmachine (1.2.7)
     gemika (0.8.1)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
-    jasmine (3.6.0)
-      jasmine-core (~> 3.6.0)
-      phantomjs
-      rack (>= 1.2.1)
-      rake
-    jasmine-core (3.6.0)
     matrix (0.4.2)
-    mini_mime (1.1.2)
-    mini_portile2 (2.8.1)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.5)
     minitest (5.16.3)
-    nokogiri (1.13.8)
-      mini_portile2 (~> 2.8.0)
+    mustermann (3.0.0)
+      ruby2_keywords (~> 0.0.1)
+    nio4r (2.6.1)
+    nokogiri (1.15.5)
+      mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    phantomjs (2.1.1.0)
-    public_suffix (5.0.0)
-    racc (1.6.0)
-    rack (2.2.3)
-    rack-test (2.0.2)
+    public_suffix (5.0.4)
+    puma (6.4.0)
+      nio4r (~> 2.0)
+    racc (1.7.3)
+    rack (2.2.8)
+    rack-protection (3.1.0)
+      rack (~> 2.2, >= 2.2.4)
+    rack-test (2.1.0)
       rack (>= 1.3)
-    rake (13.0.1)
-    regexp_parser (2.5.0)
+    rake (13.1.0)
+    regexp_parser (2.8.2)
     rexml (3.2.5)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
@@ -73,21 +71,26 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.0)
+    rspec-wait (0.0.9)
+      rspec (>= 3, < 4)
     ruby2_keywords (0.0.5)
     rubyzip (2.3.2)
     selenium-webdriver (4.1.0)
       childprocess (>= 0.5, < 5.0)
       rexml (~> 3.2, >= 3.2.5)
       rubyzip (>= 1.2.2)
-    thin (1.8.0)
+    sinatra (3.1.0)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.1.0)
+      tilt (~> 2.0)
+    thin (1.8.2)
       daemons (~> 1.0, >= 1.0.9)
       eventmachine (~> 1.0, >= 1.0.4)
       rack (>= 1, < 3)
+    tilt (2.3.0)
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
-    websocket-driver (0.7.3)
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
     zeitwerk (2.6.0)
@@ -98,14 +101,15 @@ PLATFORMS
 DEPENDENCIES
   activesupport (~> 6.0)
   byebug
-  capybara (= 3.36.0)
+  capybara (>= 3)
   capybara-lockstep!
-  chrome_remote
   gemika (>= 0.8.1)
-  jasmine
+  puma
   rake (~> 13.0)
   rspec (~> 3.0)
-  selenium-webdriver (= 4.1.0)
+  rspec-wait
+  selenium-webdriver (>= 4)
+  sinatra
   thin
 
 BUNDLED WITH

data/README.md

@@ -3,7 +3,7 @@
 This Ruby gem synchronizes [Capybara](https://github.com/teamcapybara/capybara) commands with client-side JavaScript and AJAX requests. This greatly improves the stability of an end-to-end ("E2E") test suite, even if that suite has timing issues.
 
 The next section explain why your test suite is flaky and how capybara-lockstep can help.\
-If you don't care you may skip to [installation instructions](#installation).
+If you don't care you may **skip to [installation instructions](#installation)**.
 
 
 Why are tests flaky?
@@ -58,8 +58,9 @@ How capybara-lockstep helps
 
 capybara-lockstep waits until the browser is idle before moving on to the next Capybara command. This greatly relieves the pressure on [Capybara's retry logic](https://github.com/teamcapybara/capybara#asynchronous-javascript-ajax-and-friends).
 
-capybara-lockstep synchronizes before:
+capybara-lockstep synchronizes when one of the following occurs:
 
+- Capybara looks up an element
 - Capybara simulates a user interaction (clicking, typing, etc.)
 - Capybara visits a new URL
 - Capybara executes JavaScript
@@ -69,13 +70,24 @@ When capybara-lockstep synchronizes it will:
 - wait for all document resources to load (images, CSS, fonts, frames).
 - wait for client-side JavaScript to render or hydrate DOM elements.
 - wait for any pending AJAX requests to finish and their callbacks to be called.
-- capybara-lockstep waits for dynamically inserted `<script>`s to load (e.g. from [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or Analytics snippets).
-- capybara-lockstep waits for dynamically inserted `<img>` or `<iframe>` elements to load.
+- wait for dynamically inserted `<script>`s to load (e.g. from [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or Analytics snippets).
+- waits for dynamically inserted `<img>` or `<iframe>` elements to load.
 
-In summary Capybara can no longer observe the page while HTTP requests are in flight.
+In summary Capybara can no longer observe or interact with the page while HTTP requests are in flight.
 This covers most async work that causes flaky tests.
 
-You can also configure capybara-lockstep to [wait for other async work](#signaling-asynchronous-work) that does not involve the network, like animations.
+
+### Limitations
+
+Async work not synchronized by capybara-lockstep includes:
+
+- Animations
+- Websocket connections
+- Media elements (`<video>`, `<audio>`)
+- Service workers
+- Work scheduled via `setTimeout()` or `setInterval()`.
+
+You can configure capybara-lockstep to [wait for additional async work](#signaling-asynchronous-work).
 
 
 Installation
@@ -85,8 +97,8 @@ Installation
 
 Check if your application satisfies all requirements for capybara-lockstep:
 
-- Capybara 2 or higher.
-- Your Capybara driver must use [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver/). capybara-lockstep deactivates itself for any other driver.
+- 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.
 - 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 Rails, but there's no Rails dependency.
 
@@ -110,7 +122,7 @@ $ bundle install
 If you're not using Rails you should also `require 'capybara-lockstep'` in your `spec_helper.rb` (RSpec), `test_helper.rb` (Minitest) or `env.rb` (Cucumber).
 
 
-### Including the JavaScript snippet
+### Including the JavaScript snippet (required)
 
 capybara-lockstep requires a JavaScript snippet to be embedded by the application under test. If that snippet is missing on a screen, capybara-lockstep will not be able to synchronize with the browser. In that case the test will continue without synchronization.
 
@@ -122,11 +134,31 @@ capybara-lockstep requires a JavaScript snippet to be embedded by the applicatio
 
 Ideally the snippet should be included in the `<head>` before any other `<script>` tags.
 
-**If you're not using Rails** you can `include Capybara::Lockstep::Helper` and access the JavaScript with `capybara_lockstep_script`.
+**If you're not using Rails** you can `include Capybara::Lockstep::Helper` and access the JavaScript code with `capybara_lockstep_js`.
 
 **If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)** the `capybara_lockstep` Rails helper will insert a CSP nonce by default. You can also pass an explicit nonce string using the `:nonce` option.
 
 
+### Including the middleware (optional)
+
+This gem provides a Rack middleware to block Capybara while your Rails (or Rack) backend is busy.
+
+Using the middleware is optional, as the [JavaScript snippet](#including-the-javascript-snippet-required) already for AJAX requests on the client. However, using the middleware covers some additional edge cases. For example, the middleware detects requests that were aborted on the frontend, but are still being processed by the backend.
+
+To include the middleware in a Rails application, add the following line to `config/environments/test.rb`:
+
+```ruby
+config.middleware.insert_before 0, Capybara::Lockstep::Middleware
+```
+
+In a **non-Rails** application you should include the middleware as high up in your middleware stack as possible:
+
+```ruby
+use Capybara::Lockstep::Middleware
+# Other middleware here
+```
+
+
 
 ### Verify successful integration
 
@@ -152,16 +184,22 @@ Note that you may see some failures from tests with wrong assertions, which prev
 
 ## Signaling asynchronous work
 
-By default capybara-lockstep waits until resources have loaded, AJAX requests have finished and their callbacks have been called.
+[By default](#how-capybara-lockstep-helps) capybara-lockstep waits until resources have loaded, AJAX requests have finished and their callbacks have been called.
+There are also some [limitations](#limitations).
+
+You can configure capybara-lockstep to wait for other async work.
 
-You can configure capybara-lockstep to wait for other async work that does not involve the network. Let's say we have an animation that fades in a new element over 2 seconds. The following will prevent Capybara from observing the page while the animation is running:
+
+### On the frontend
+
+Let's say we have an animation that fades in a new element over 2 seconds. The following will block Capybara while the animation is running:
 
 ```js
 async function fadeIn(element) {
-  CapybaraLockstep.startWork('Animation')
+  CapybaraLockstep?.startWork('Animation')
   startAnimation(element, 'fade-in')
   await waitForAnimationEnd(element)
-  CapybaraLockstep.stopWork('Animation')
+  CapybaraLockstep?.stopWork('Animation')
 }
 ```
 
@@ -175,20 +213,24 @@ The string argument is used for logging (when logging is enabled). It does **not
 You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
 
 
-## Note on interacting with the JavaScript API
+### On the backend
 
-If you only load capybara-lockstep in tests you, should check for the `CapybaraLockstep` global to be defined before you interact with the JavaScript API.
+You don't need to signal work within the regular request/response cycle, as this is detected automatically. You can however signal
+work that happens outside a request, e.g. in a background job or WebSocket handler.
 
-```js
-if (window.CapybaraLockstep) {
-  // interact with CapybaraLockstep
-}
-```
-
-If you can use ES6 you may also use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) to only call a function if `window.CapybaraLockstep` is defined:
+The following will block Capybara while a [Sidekiq](https://sidekiq.org/) job is running:
 
-```js
-window.CapybaraLockstep?.startWork('Work')
+```ruby
+class HardJob
+  include Sidekiq::Job
+
+  def perform(name, count)
+    Capybara::Lockstep.start_work('HardJob') if defined?(Capybara::Lockstep)
+    # do something
+  ensure
+    Capybara::Lockstep.stop_work('StopWork') if defined?(Capybara::Lockstep)
+  end
+end
 ```
 
 
@@ -335,14 +377,13 @@ It is theoretically possible that your test will observe the browser in that win
 Any issues caused by this will usually be mitigated by Capybara's retry logic. **If** you think that this is an issue for your test suite, you can configure capybara-headless to wait additional tasks before it considers the browser to be idle:
 
 ```ruby
-Capybara::Lockstep.wait_tasks = 1
+Capybara::Lockstep.wait_tasks = 2 // default is 1
 ```
 
 If you see longer chains of `then()` or nested `setTimeout()` calls in your code, you may need to configure a higher number of tasks to wait.
 
 Waiting additional tasks will have a negative performance impact on your test suite.
 
-> **Note:** When capybara-lockstep detects jQuery on the page, it will automatically patch [`$.ajax()`](https://api.jquery.com/jQuery.ajax/) to wait an additional task after the response was received. If your only concern is callbacks to `$.ajax()` you do not need so set `Capybara::Lockstep.wait_tasks`.
 
 
 ## Running code after synchronization

data/Rakefile

@@ -6,8 +6,6 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
-require 'jasmine'
-load 'jasmine/tasks/jasmine.rake'
 
 begin
   require 'gemika/tasks'

data/capybara-lockstep.gemspec

@@ -28,9 +28,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "capybara", ">= 2.0"
-  spec.add_dependency "selenium-webdriver", ">= 3"
-  spec.add_dependency "activesupport", ">= 3.2"
+  spec.add_dependency "capybara", ">= 3.0"
+  spec.add_dependency "selenium-webdriver", ">= 4.0"
+  spec.add_dependency "activesupport", ">= 4.2"
   spec.add_dependency "ruby2_keywords"
 
   # For more information and examples about making a new gem, checkout our

data/lib/capybara-lockstep/capybara_ext.rb

@@ -2,13 +2,27 @@ require 'ruby2_keywords'
 
 module Capybara
   module Lockstep
-    module UnsychronizeAfter
-      def unsychronize_after(meth)
+    module SynchronizeMacros
+
+      def synchronize_before(meth, lazy:)
+        mod = Module.new do
+          define_method meth do |*args, &block|
+            Lockstep.auto_synchronize(lazy: lazy, log: "Synchronizing before ##{meth}")
+            super(*args, &block)
+          end
+
+          ruby2_keywords meth
+        end
+
+        prepend(mod)
+      end
+
+      def synchronize_after(meth)
         mod = Module.new do
           define_method meth do |*args, &block|
             super(*args, &block)
           ensure
-            Lockstep.synchronized = false
+            Lockstep.auto_synchronize
           end
 
           ruby2_keywords meth
@@ -16,18 +30,13 @@ module Capybara
 
         prepend(mod)
       end
-    end
-  end
-end
 
-module Capybara
-  module Lockstep
-    module SynchronizeBefore
-      def synchronize_before(meth, lazy:)
+      def unsynchronize_after(meth)
         mod = Module.new do
           define_method meth do |*args, &block|
-            Lockstep.auto_synchronize(lazy: lazy, log: "Synchronizing before ##{meth}")
             super(*args, &block)
+          ensure
+            Lockstep.unsynchronize
           end
 
           ruby2_keywords meth
@@ -35,32 +44,32 @@ module Capybara
 
         prepend(mod)
       end
+
     end
   end
 end
 
 Capybara::Session.class_eval do
-  extend Capybara::Lockstep::SynchronizeBefore
-  extend Capybara::Lockstep::UnsychronizeAfter
+  extend Capybara::Lockstep::SynchronizeMacros
 
   synchronize_before :html, lazy: true # wait until running JavaScript has updated the DOM
 
   synchronize_before :current_url, lazy: true # wait until running JavaScript has updated the URL
 
   synchronize_before :refresh, lazy: false # wait until running JavaScript has updated the URL
-  unsychronize_after :refresh # new document is no longer synchronized
+  unsynchronize_after :refresh # new document is no longer synchronized
 
   synchronize_before :go_back, lazy: false # wait until running JavaScript has updated the URL
-  unsychronize_after :go_back # new document is no longer synchronized
+  unsynchronize_after :go_back # new document is no longer synchronized
 
   synchronize_before :go_forward, lazy: false # wait until running JavaScript has updated the URL
-  unsychronize_after :go_forward # new document is no longer synchronized
+  unsynchronize_after :go_forward # new document is no longer synchronized
 
   synchronize_before :switch_to_frame, lazy: true # wait until the current frame is done processing
-  unsychronize_after :switch_to_frame # now that we've switched into the new frame, we don't know the document's synchronization state.
+  unsynchronize_after :switch_to_frame # now that we've switched into the new frame, we don't know the document's synchronization state.
 
   synchronize_before :switch_to_window, lazy: true # wait until the current frame is done processing
-  unsychronize_after :switch_to_window # now that we've switched to the new window, we don't know the document's synchronization state.
+  unsynchronize_after :switch_to_window # now that we've switched to the new window, we don't know the document's synchronization state.
 end
 
 module Capybara
@@ -88,7 +97,7 @@ module Capybara
         super(*args, &block).tap do
           if visiting_real_url
             # We haven't yet synchronized the new screen.
-            Lockstep.synchronized = false
+            Lockstep.unsynchronize
           end
         end
       end
@@ -128,7 +137,7 @@ module Capybara
             if !Lockstep.synchronizing?
               # We haven't yet synchronized with whatever changes the JavaScript
               # did on the frontend.
-              Lockstep.synchronized = false
+              Lockstep.unsynchronize
             end
           end
 
@@ -167,21 +176,59 @@ end
 
 node_classes.each do |node_class|
   node_class.class_eval do
-    extend Capybara::Lockstep::UnsychronizeAfter
-
-    unsychronize_after :set
-    unsychronize_after :select_option
-    unsychronize_after :unselect_option
-    unsychronize_after :click
-    unsychronize_after :right_click
-    unsychronize_after :double_click
-    unsychronize_after :send_keys
-    unsychronize_after :hover
-    unsychronize_after :drag_to
-    unsychronize_after :drop
-    unsychronize_after :scroll_by
-    unsychronize_after :scroll_to
-    unsychronize_after :trigger
+    extend Capybara::Lockstep::SynchronizeMacros
+
+    synchronize_before :set, lazy: true
+    unsynchronize_after :set
+    synchronize_after :set
+
+    synchronize_before :select_option, lazy: true
+    unsynchronize_after :select_option
+    synchronize_after :select_option
+
+    synchronize_before :unselect_option, lazy: true
+    unsynchronize_after :unselect_option
+    synchronize_after :unselect_option
+
+    synchronize_before :click, lazy: true
+    unsynchronize_after :click
+    synchronize_after :click
+
+    synchronize_before :right_click, lazy: true
+    unsynchronize_after :right_click
+    synchronize_after :right_click
+
+    synchronize_before :double_click, lazy: true
+    unsynchronize_after :double_click
+    synchronize_after :double_click
+
+    synchronize_before :send_keys, lazy: true
+    unsynchronize_after :send_keys
+    synchronize_after :send_keys
+
+    synchronize_before :hover, lazy: true
+    unsynchronize_after :hover
+    synchronize_after :hover
+
+    synchronize_before :drag_to, lazy: true
+    unsynchronize_after :drag_to
+    synchronize_after :drag_to
+
+    synchronize_before :drop, lazy: true
+    unsynchronize_after :drop
+    synchronize_after :drop
+
+    synchronize_before :scroll_by, lazy: true
+    unsynchronize_after :scroll_by
+    synchronize_after :scroll_by
+
+    synchronize_before :scroll_to, lazy: true
+    unsynchronize_after :scroll_to
+    synchronize_after :scroll_to
+
+    synchronize_before :trigger, lazy: true
+    unsynchronize_after :trigger
+    synchronize_after :trigger
   end
 end
 

data/lib/capybara-lockstep/client.rb

@@ -0,0 +1,133 @@
+module Capybara
+  module Lockstep
+    class Client
+      include Logging
+      include PageAccess
+
+      ERROR_SNIPPET_MISSING = 'Cannot synchronize: capybara-lockstep JavaScript snippet is missing'
+      ERROR_PAGE_MISSING = 'Cannot synchronize with empty page'
+      ERROR_ALERT_OPEN = 'Cannot synchronize while an alert is open'
+      ERROR_NAVIGATED_AWAY = "Browser navigated away while synchronizing"
+
+      SYNCHRONIZED_IVAR = :@lockstep_synchronized_client
+
+      def synchronized?
+        # The synchronized flag is per-session (page == Capybara.current_session).
+        # This enables tests that use more than one browser, e.g. to test multi-user interaction:
+        # https://makandracards.com/makandra/474480-how-to-make-a-cucumber-test-work-with-multiple-browser-sessions
+        #
+        # Ideally the synchronized flag would also be per-tab, per-frame and per-document.
+        # We haven't found a way to patch this into Capybara, as there does not seem to be
+        # a persistent object representing a document. Capybara::Node::Document just seems to
+        # be a proxy accessing whatever is the current document. The way we work around this
+        # is that we synchronize before switching tabs or frames.
+        value = page.instance_variable_get(SYNCHRONIZED_IVAR)
+
+        # We consider a new Capybara session to be synchronized.
+        # This will be set to false after our first visit().
+        value.nil? ? true : value
+      end
+
+      def synchronized=(value)
+        page.instance_variable_set(SYNCHRONIZED_IVAR, value)
+      end
+
+      def synchronize
+        # If synchronization fails below we consider us unsynchronized after.
+        self.synchronized = false
+
+        # Running the synchronization script while an alert is open would close the alert,
+        # most likely causing subsequent expectations to fail.
+        if 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.
+          return
+        end
+
+        start_time = Util.current_seconds
+
+        begin
+          Util.with_max_wait_time(timeout) do
+            message_from_js = evaluate_async_script(<<~JS)
+              let done = arguments[0]
+              let synchronize = () => {
+                if (window.CapybaraLockstep) {
+                  CapybaraLockstep.synchronize(done)
+                } else {
+                  done(#{ERROR_SNIPPET_MISSING.to_json})
+                }
+              }
+              const emptyDataURL = /^data:[^,]*,?$/
+              if (emptyDataURL.test(location.href) || location.protocol === 'about:') {
+                done(#{ERROR_PAGE_MISSING.to_json})
+              } else if (document.readyState === 'complete') {
+                // WebDriver always waits for the `load` event after a visit(),
+                // unless a different page load strategy was configured.
+                synchronize()
+              } else {
+                window.addEventListener('load', synchronize)
+              }
+            JS
+
+            case message_from_js
+            when ERROR_PAGE_MISSING
+              log(message_from_js)
+            when ERROR_SNIPPET_MISSING
+              log(message_from_js)
+            else
+              log message_from_js
+              end_time = Util.current_seconds
+              ms_elapsed = ((end_time.to_f - start_time) * 1000).round
+              log "Synchronized client successfully [#{ms_elapsed} ms]"
+              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.
+          # 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 unhandled_synchronize_error(e)
+        Lockstep.log "#{e.class.name} while synchronizing: #{e.message}"
+        raise e
+      end
+
+      def timeout
+        Lockstep.timeout
+      end
+
+      def timeout_with
+        Lockstep.timeout_with
+      end
+
+    end
+  end
+end
+

data/lib/capybara-lockstep/configuration.rb

@@ -18,9 +18,13 @@ module Capybara
         @timeout_with = action&.to_sym
       end
 
+      def debug
+        @debug.nil? ? false : @debug
+      end
+
       def debug?
         # @debug may also be a Logger object, so convert it to a boolean
-        @debug.nil? ? false : !!@debug
+        !!debug
       end
 
       def debug=(value)
@@ -49,6 +53,14 @@ module Capybara
         @mode = mode&.to_sym
       end
 
+      def with_mode(temporary_mode, &block)
+        old_mode = mode
+        self.mode = temporary_mode
+        block.call
+      ensure
+        self.mode = temporary_mode
+      end
+
       def enabled=(enabled)
         case enabled
         when true
@@ -93,13 +105,11 @@ module Capybara
         end
       end
 
-      def javascript_driver?
-        driver.is_a?(Capybara::Selenium::Driver)
-      end
-
       def send_config_to_browser(js)
+        return unless javascript_driver?
+
         begin
-          with_max_wait_time(2) do
+          Util.with_max_wait_time(2) do
             page.execute_script(<<~JS)
               if (window.CapybaraLockstep) {
                 #{js}

data/lib/capybara-lockstep/helper.js

@@ -11,7 +11,7 @@ window.CapybaraLockstep = (function() {
     jobCount = 0
     idleCallbacks = []
     finishedWorkTags = []
-    waitTasks = 0
+    waitTasks = 1
     debug = false
   }
 
@@ -58,18 +58,7 @@ window.CapybaraLockstep = (function() {
   }
 
   function stopWork(tag) {
-    let tasksElapsed = 0
-
-    let check = function() {
-      if (tasksElapsed < waitTasks) {
-        tasksElapsed++
-        setTimeout(check)
-      } else {
-        stopWorkNow(tag)
-      }
-    }
-
-    check()
+    afterWaitTasks(stopWorkNow.bind(this, tag))
   }
 
   function stopWorkNow(tag) {
@@ -266,6 +255,14 @@ window.CapybaraLockstep = (function() {
     }
   }
 
+  function afterWaitTasks(fn, tasksLeft = waitTasks) {
+    if (tasksLeft > 0) {
+      afterWaitTasks(fn, tasksLeft - 1)
+    } else {
+      fn()
+    }
+  }
+
   function trackOldUnpoly() {
     // CapybaraLockstep.track() is called as the first script in the head.
     // Unpoly will be loaded after us, so we wait until DOMContentReady.
@@ -282,12 +279,32 @@ window.CapybaraLockstep = (function() {
     })
   }
 
+  function trackInteraction(eventType) {
+    document.addEventListener(eventType, function() {
+      // Only litter the log with interaction events if we're actually going
+      // to be busy for at least 1 task.
+      if (waitTasks > 0) {
+        let tag = eventType
+        startWork(tag)
+        stopWork(tag)
+      }
+    })
+  }
+
   function track() {
     trackOldUnpoly()
     trackFetch()
     trackXHR()
     trackRemoteElements()
     trackJQuery()
+    trackInteraction('touchstart')
+    trackInteraction('mousedown')
+    trackInteraction('click')
+    trackInteraction('keydown')
+    trackInteraction('focusin')
+    trackInteraction('focusout')
+    trackInteraction('input')
+    trackInteraction('change')
   }
 
   function synchronize(callback) {

data/lib/capybara-lockstep/lockstep.rb

@@ -1,39 +1,31 @@
 module Capybara
   module Lockstep
-    ERROR_SNIPPET_MISSING = 'Cannot synchronize: capybara-lockstep JavaScript snippet is missing'
-    ERROR_PAGE_MISSING = 'Cannot synchronize with empty page'
-    ERROR_ALERT_OPEN = 'Cannot synchronize while an alert is open'
-    ERROR_NAVIGATED_AWAY = "Browser navigated away while synchronizing"
-
     class << self
       include Configuration
       include Logging
+      include PageAccess
 
       attr_accessor :synchronizing
       alias synchronizing? synchronizing
 
-      def synchronized?
-        # The synchronized flag is per-session (page == Capybara.current_session).
-        # This enables tests that use more than one browser, e.g. to test multi-user interaction:
-        # https://makandracards.com/makandra/474480-how-to-make-a-cucumber-test-work-with-multiple-browser-sessions
-        #
-        # Ideally the synchronized flag would also be per-tab, per-frame and per-document.
-        # We haven't found a way to patch this into Capybara, as there does not seem to be
-        # a persistent object representing a document. Capybara::Node::Document just seems to
-        # be a proxy accessing whatever is the current document. The way we work around this
-        # is that we synchronize before switching tabs or frames.
-        value = page.instance_variable_get(:@lockstep_synchronized)
-
-        # We consider a new Capybara session to be synchronized.
-        # This will be set to false after our first visit().
-        value.nil? ? true : value
+      def unsynchronize
+        client.synchronized = false
       end
 
-      def synchronized=(value)
-        page.instance_variable_set(:@lockstep_synchronized, value)
+      # Automatic synchronization from within the capybara-lockstep should always call #auto_synchronize.
+      # This only synchronizes IFF in :auto mode, i.e. the user has not explicitly disabled automatic syncing.
+      # The :auto mode has nothing to do with the { lazy } option.
+      def auto_synchronize(**options)
+        if mode == :auto
+          synchronize(**options)
+        end
       end
 
-      def synchronize(lazy: false, log: nil)
+      def synchronize(lazy: false, log: 'Synchronizing')
+        if synchronizing? || mode == :off
+          return
+        end
+
         # 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.
@@ -48,135 +40,38 @@ module Capybara
         # thinks we're in sync or not. This always makes an execute_script() rountrip, but picks up
         # non-lazy synchronization so we pick up client-side work that have not been caused
         # by Capybara commands.
-        if (lazy && synchronized?) || synchronizing? || mode == :off
-          return
-        end
-
-        synchronize_now(log: log)
-
-        run_after_synchronize_callbacks
-      end
-
-      # Automatic synchronization from within the capybara-lockstep should always call #auto_synchronize.
-      # This only synchronizes IFF in :auto mode, i.e. the user has not explicitly disabled automatic syncing.
-      # The :auto mode has nothing to do with the { lazy } option.
-      def auto_synchronize(**options)
-        if mode == :auto
-          synchronize(**options)
-        end
-      end
-
-      private
-
-      def synchronize_now(log: 'Synchronizing')
-        self.synchronizing = true
-        self.synchronized = false
-
-        self.log(log)
-
-        start_time = current_seconds
+        will_synchronize_client = !(lazy && client.synchronized?)
 
         begin
-          with_max_wait_time(timeout) do
-            message_from_js = evaluate_async_script(<<~JS)
-              let done = arguments[0]
-              let synchronize = () => {
-                if (window.CapybaraLockstep) {
-                  CapybaraLockstep.synchronize(done)
-                } else {
-                  done(#{ERROR_SNIPPET_MISSING.to_json})
-                }
-              }
-              const emptyDataURL = /^data:[^,]*,?$/
-              if (emptyDataURL.test(location.href) || location.protocol === 'about:') {
-                done(#{ERROR_PAGE_MISSING.to_json})
-              } else if (document.readyState === 'complete') {
-                // WebDriver always waits for the `load` event after a visit(),
-                // unless a different page load strategy was configured.
-                synchronize()
-              } else {
-                window.addEventListener('load', synchronize)
-              }
-            JS
-
-            case message_from_js
-            when ERROR_PAGE_MISSING
-              log(message_from_js)
-            when ERROR_SNIPPET_MISSING
-              log(message_from_js)
-            else
-              log message_from_js
-              end_time = current_seconds
-              ms_elapsed = ((end_time.to_f - start_time) * 1000).round
-              log "Synchronized successfully [#{ms_elapsed} ms]"
-              self.synchronized = true
-            end
-          end
-        rescue ::Selenium::WebDriver::Error::ScriptTimeoutError
-          timeout_message = "Could not synchronize 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.
+          # Synchronizing the server is free, so we ignore { lazy } and do it every time.
+          server.synchronize
+
+          if will_synchronize_client
+            self.log(log)
+            self.synchronizing = true
+            client.synchronize
+            # Synchronizing the server is free, so we ignore { lazy } and do it every time.
+            server.synchronize
           end
-        rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
-          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.
-        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)
+        ensure
+          self.synchronizing = false
         end
 
-      ensure
-        self.synchronizing = false
-      end
-
-      def unhandled_synchronize_error(e)
-        log "#{e.class.name} while synchronizing: #{e.message}"
-        raise e
-      end
-
-      def page
-        Capybara.current_session
-      end
-
-      delegate :evaluate_script, :evaluate_async_script, :execute_script, :driver, to: :page
-
-      def with_max_wait_time(seconds, &block)
-        old_max_wait_time = Capybara.default_max_wait_time
-        Capybara.default_max_wait_time = seconds
-        begin
-          block.call
-        ensure
-          Capybara.default_max_wait_time = old_max_wait_time
+        if will_synchronize_client
+          run_after_synchronize_callbacks
         end
       end
 
-      def ignoring_alerts(&block)
-        block.call
-      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
-        # no-op
+      delegate :start_work, :stop_work, to: :server
+
+      def server
+        @server ||= Server.new
       end
 
-      def current_seconds
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      def client
+        @client ||= Client.new
       end
 
     end
-
   end
 end
-

data/lib/capybara-lockstep/logging.rb

@@ -2,11 +2,11 @@ module Capybara
   module Lockstep
     module Logging
       def log(message)
-        if debug? && message.present?
+        if Lockstep.debug? && message.present?
           message = "[capybara-lockstep] #{message}"
-          if is_logger?(@debug)
-            # If someone set Capybara::Lockstep to a logger, use that
-            @debug.debug(message)
+          if is_logger?(Lockstep.debug)
+            # If someone set Capybara::Lockstep.debug to a logger, use that
+            Lockstep.debug(message)
           else
             # Otherwise print to STDOUT
             puts message
@@ -17,8 +17,8 @@ module Capybara
       private
 
       def is_logger?(object)
-        @debug.respond_to?(:debug)
+        object.respond_to?(:debug)
       end
     end
   end
-end
+end

data/lib/capybara-lockstep/middleware.rb

@@ -0,0 +1,22 @@
+module Capybara
+  module Lockstep
+    class Middleware
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        tag = "Server request for #{env['PATH_INFO'] || 'unknown path'}"
+        Lockstep.start_work(tag)
+
+        begin
+          @app.call(env)
+        ensure
+          Lockstep.stop_work(tag)
+        end
+      end
+
+    end
+  end
+end

data/lib/capybara-lockstep/page_access.rb

@@ -0,0 +1,28 @@
+module Capybara
+  module Lockstep
+    module PageAccess
+      def page
+        Capybara.current_session
+      end
+
+      delegate :evaluate_script, :evaluate_async_script, :execute_script, :driver, to: :page
+
+      def javascript_driver?
+        driver.is_a?(Capybara::Selenium::Driver)
+      end
+
+      def alert_present?
+        # Chrome 54 and/or Chromedriver 2.24 introduced a breaking change on how
+        # accessing browser logs work.
+        #
+        # 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
+        page.driver.browser.switch_to.alert
+        true
+      rescue Capybara::NotSupportedByDriverError, ::Selenium::WebDriver::Error::NoSuchAlertError
+        false
+      end
+
+    end
+  end
+end

data/lib/capybara-lockstep/server.rb

@@ -0,0 +1,46 @@
+module Capybara
+  module Lockstep
+    class Server
+      include Logging
+
+      def initialize
+        @job_count = 0
+        @job_count_mutex = Mutex.new
+        @idle_condition = ConditionVariable.new
+      end
+
+      attr_accessor :job_count
+
+      def start_work(tag)
+        job_count_mutex.synchronize do
+          self.job_count += 1
+          log("Started server work: #{tag} [#{job_count} server jobs]") if tag
+        end
+      end
+
+      def stop_work(tag)
+        job_count_mutex.synchronize do
+          self.job_count -= 1
+          log("Stopped server work: #{tag} [#{job_count} server jobs]") if tag
+
+          if job_count == 0
+            idle_condition.broadcast
+          end
+        end
+      end
+
+      def synchronize
+        job_count_mutex.synchronize do
+          if job_count > 0
+            idle_condition.wait(job_count_mutex)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :job_count_mutex, :idle_condition
+
+    end
+  end
+end

data/lib/capybara-lockstep/util.rb

@@ -0,0 +1,21 @@
+module Capybara
+  module Lockstep
+    module Util
+      class << self
+        def with_max_wait_time(seconds, &block)
+          old_max_wait_time = Capybara.default_max_wait_time
+          Capybara.default_max_wait_time = seconds
+          begin
+            block.call
+          ensure
+            Capybara.default_max_wait_time = old_max_wait_time
+          end
+        end
+
+        def current_seconds
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "1.3.1"
+    VERSION = "2.0.0"
   end
 end

data/lib/capybara-lockstep.rb

@@ -10,8 +10,13 @@ end
 
 require_relative 'capybara-lockstep/version'
 require_relative 'capybara-lockstep/errors'
+require_relative 'capybara-lockstep/util'
 require_relative 'capybara-lockstep/configuration'
 require_relative 'capybara-lockstep/logging'
+require_relative 'capybara-lockstep/page_access'
 require_relative 'capybara-lockstep/lockstep'
 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/middleware'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-25 00:00:00.000000000 Z
+date: 2023-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -16,42 +16,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.2'
 - !ruby/object:Gem::Dependency
   name: ruby2_keywords
   requirement: !ruby/object:Gem::Requirement
@@ -88,12 +88,17 @@ files:
 - capybara-lockstep.gemspec
 - lib/capybara-lockstep.rb
 - lib/capybara-lockstep/capybara_ext.rb
+- lib/capybara-lockstep/client.rb
 - lib/capybara-lockstep/configuration.rb
 - lib/capybara-lockstep/errors.rb
 - lib/capybara-lockstep/helper.js
 - lib/capybara-lockstep/helper.rb
 - lib/capybara-lockstep/lockstep.rb
 - lib/capybara-lockstep/logging.rb
+- lib/capybara-lockstep/middleware.rb
+- lib/capybara-lockstep/page_access.rb
+- lib/capybara-lockstep/server.rb
+- lib/capybara-lockstep/util.rb
 - lib/capybara-lockstep/version.rb
 homepage: https://github.com/makandra/capybara-lockstep
 licenses: