capybara-lockstep 2.0.0.rc1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f264c637e6de9b4a6ab18e1e33ebf3c81fe46a9a20173b5c4c8097f5be4d8ae6
-  data.tar.gz: f48886c96cbdfe898d5245a85955b76a5caee1c64662e4e12823427b7cb6c883
+  metadata.gz: a9d5a9ec157f65f4efb9be5ac2b33c5447552eb70e8d118438a7aad763c57492
+  data.tar.gz: 2ddde2a3b51079603d8368f0ebbe81d5205d473beeaf301bb6bdd42c80c968d3
 SHA512:
-  metadata.gz: c959856af42047611c8c90b4b9c2de6a0a201ba9bff3f5ae9f2bc0a1e32026999283253c6d7ace66305364c57550dc20b5ee131251dcbf80cec707b47994bb30
-  data.tar.gz: be4f33cb2e453d1bf830a75d70a55ffdb43c243ccf0f9d0513bf578b88d0aec6fca135cb4c16f6f13096edd52d44c190794f480ba35140ec965c32e09ddafa6f
+  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

@@ -3,14 +3,18 @@ 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-rc1
+# 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 to Capybara, e.g. by accessing the database or global state variables.
+- 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, 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, 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.
+- 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

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 (2.0.0.rc1)
-      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/configuration.rb

@@ -53,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

data/lib/capybara-lockstep/helper.js

@@ -284,7 +284,7 @@ window.CapybaraLockstep = (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 + ' listeners'
+        let tag = eventType
         startWork(tag)
         stopWork(tag)
       }
@@ -301,6 +301,10 @@ window.CapybaraLockstep = (function() {
     trackInteraction('mousedown')
     trackInteraction('click')
     trackInteraction('keydown')
+    trackInteraction('focusin')
+    trackInteraction('focusout')
+    trackInteraction('input')
+    trackInteraction('change')
   }
 
   function synchronize(callback) {

data/lib/capybara-lockstep/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 2.0.0.rc1
+  version: 2.0.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-19 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
@@ -120,9 +120,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.4.3
 signing_key: