capybara-lockstep 2.1.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 514789431b5b017176575acd43c1a5b6558040f31cf7cb4ac119cf10e756dbee
-  data.tar.gz: 2945ac3b32b7f83a7bc2bd14848f67950c12e5063033d8dbe2063788dfe8c024
+  metadata.gz: 8bad1a61632d37c5e705b886be4cb840a62923f73887c1443060fb00c6e69aa2
+  data.tar.gz: 9243b559659a33a00e6f803304284aa9cd47e5c2f110a11b47eb2e4e62441537
 SHA512:
-  metadata.gz: b2dac0508c3caaa13fd28fe285c9c3b7d2b796dfba6c2bf788578ffee90135b6504a2e9b731d8bf4496806723d26c28bf5ccb536e5de21c2b5661b354a9e2de1
-  data.tar.gz: 4e80b685b588dfded10cb0783cbe62aceb00517199ef5527ce76fb76a234c96eb913ec0e7d08df2e22a7dd5a2b2d475bed0d4318add6ddee9fd27403afc2e0fe
+  metadata.gz: 9b285d685609f913c92b4b8d5556d34d7d77e2fb6d80e5fac4cda189c81a2b81445fc65a5680726c2d21b16d0bcdcb1fcb35e3a6169b2febca3244eaa555b985
+  data.tar.gz: d598437ffb3eaf066d6cbcb747ac6c5445bed0a2c2cbc5113f42e0d947d4b71fc7bb4752ede4193cca989acafd5d126757c67d3454fbfc226014d7b42056b55f

data/.github/workflows/test.yml

@@ -3,13 +3,13 @@ name: Tests
 on:
   push:
     branches:
-    - master
+    - main
   pull_request:
     branches:
-    - master
+    - main
   workflow_dispatch:
     branches:
-    - master
+    - main
 jobs:
   test:
     runs-on: ubuntu-20.04

data/CHANGELOG.md

@@ -2,6 +2,17 @@ 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.2.1
+
+- Fixed a bug that disabled most functionality for drivers with `browser: :remote`.
+
+
+# 2.2.0
+
+- We now wait for `<video>` and `<audio>` elements to load their metadata. This addresses a race condition where a media element is inserted into the DOM, but another user action deletes or renames the source before the browser could load the initial metadata frames. 
+- We now wait for `<script type="module">`.
+- We no longer wait for `<img loading="lazy">` or `<iframe loading="lazy">`. This prevents a deadlock where we would wait forever for an element that defers loading until it is scrolled into the viewport.
+
 
 # 2.1.0
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (2.1.0)
+    capybara-lockstep (2.2.1)
       activesupport (>= 4.2)
       capybara (>= 3.0)
       ruby2_keywords
@@ -31,7 +31,7 @@ GEM
     childprocess (4.1.0)
     concurrent-ruby (1.1.10)
     daemons (1.4.1)
-    diff-lcs (1.3)
+    diff-lcs (1.5.1)
     eventmachine (1.2.7)
     gemika (0.8.1)
     i18n (1.12.0)
@@ -58,21 +58,21 @@ GEM
     rake (13.1.0)
     regexp_parser (2.8.2)
     rexml (3.2.5)
-    rspec (3.7.0)
-      rspec-core (~> 3.7.0)
-      rspec-expectations (~> 3.7.0)
-      rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.0)
-      rspec-support (~> 3.7.0)
-    rspec-expectations (3.7.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-mocks (3.7.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.1)
       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)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rspec-wait (0.0.10)
+      rspec (>= 3.0)
     ruby2_keywords (0.0.5)
     rubyzip (2.3.2)
     selenium-webdriver (4.1.0)

data/README.md

@@ -2,14 +2,14 @@
 
 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.\
+The next section explains why your test suite is flaky and how capybara-lockstep can help.\
 If you don't care you may **skip to [installation instructions](#installation)**.
 
 
 Why are tests flaky?
 --------------------
 
-A naively written E2E test will have [race conditions](https://makandracards.com/makandra/47336-fixing-flaky-integration-tests) between the test script and the controlled browser. How often these timing issues will fail your test depends on luck and your machine's performance. You may not see these issues for years until a colleague runs your suite on their new laptop.
+A naively written E2E test will have [race conditions](https://makandracards.com/makandra/47336-fixing-flaky-integration-tests) between the test script and the controlled browser. How often these timing issues will cause your tests to fail depends on luck and your machine's performance. You may not see these issues for years until a colleague runs your suite on their new laptop.
 
 Here is a typical example for a test that will fail with unlucky timing:
 
@@ -26,10 +26,10 @@ end
 
 This test has four timing issues that may cause it to fail:
 
-1. We click on the *New tweet* button, but the the JS event handler to open the tweet form wasn't registered yet.
-2. We start filling in the form, but it wasn't loaded yet.
+1. We click on the *New tweet* button, but the JS event handler to open the tweet form hasn't been registered yet.
+2. We start filling in the form, but it hasn't been loaded yet.
 3. After sending the tweet we immediately navigate away, killing the form submission request that is still in flight. Hence the tweet will never appear in the next step.
-4. We look for the new tweet, but the timeline wasn't loaded yet.
+4. We look for the new tweet, but the timeline hasn't been loaded yet.
 
 [Capybara will retry](https://github.com/teamcapybara/capybara#asynchronous-javascript-ajax-and-friends) individual commands or expectations when they fail.\
 However, only issues **2** and **4** can be healed by retrying.
@@ -71,9 +71,10 @@ When capybara-lockstep synchronizes it will:
 - 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.
 - 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.
+- wait for dynamically inserted `<img>` or `<iframe>` elements to load (ignoring [lazy-loaded](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#lazy) elements).
+- wait for dynamically inserted `<audio>` and `<video>` elements to load their [metadata](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadedmetadata_event)
 
-In summary Capybara can no longer observe or interact with 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.
 
 
@@ -83,7 +84,6 @@ Async work not synchronized by capybara-lockstep includes:
 
 - Animations
 - Websocket connections
-- Media elements (`<video>`, `<audio>`)
 - Service workers
 - Work scheduled via `setTimeout()` or `setInterval()`.
 
@@ -99,13 +99,14 @@ 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.
+  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 Rails, but there's no Rails dependency.
 
 
 ### Installing the Ruby gem
 
-Assuming that you're using Rails Add this line to your application's `Gemfile`:
+Assuming that you're using Rails, add this to your application's `Gemfile`:
 
 ```ruby
 group :test do
@@ -141,9 +142,9 @@ Ideally the snippet should be included in the `<head>` before any other `<script
 
 ### Including the middleware (optional)
 
-This gem provides a Rack middleware to block Capybara while your Rails (or Rack) backend is busy.
+This gem provides 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.
+Using the middleware is optional, as the [JavaScript snippet](#including-the-javascript-snippet-required) already waits for asynchronous work 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`:
 
@@ -158,7 +159,23 @@ use Capybara::Lockstep::Middleware
 # Other middleware here
 ```
 
+### 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.
+
+[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.
+
+For example, the Chrome driver can be configured like this:
+```ruby
+Capybara.register_driver(:selenium) do |app|
+  options = Selenium::WebDriver::Chrome::Options.new(
+    unhandled_prompt_behavior: 'ignore',
+    # ...
+  )
+  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
+end
+```
 
 ### Verify successful integration
 

data/capybara-lockstep.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = spec.homepage
 
   spec.metadata["bug_tracker_uri"] = "https://github.com/makandra/capybara-lockstep/issues"
-  spec.metadata["changelog_uri"] = "https://github.com/makandra/capybara-lockstep/blob/master/CHANGELOG.md"
+  spec.metadata["changelog_uri"] = "https://github.com/makandra/capybara-lockstep/blob/main/CHANGELOG.md"
   spec.metadata["rubygems_mfa_required"] = 'true'
 
   # Specify which files should be added to the gem when it is released.

data/lib/capybara-lockstep/capybara_ext.rb

@@ -3,36 +3,46 @@ require 'ruby2_keywords'
 module Capybara
   module Lockstep
     module SynchronizeMacros
+      def self.extended(by)
+        by.instance_eval do
+          prepend(@synchronize_before_module = Module.new)
+          prepend(@synchronize_after_module = Module.new)
+          prepend(@unsynchronize_after_module = Module.new)
+        end
+      end
 
       def synchronize_before(meth, lazy:)
-        mod = Module.new do
+        @synchronize_before_module.module_eval do
           define_method meth do |*args, &block|
-            Lockstep.auto_synchronize(lazy: lazy, log: "Synchronizing before ##{meth}")
+            @synchronize_before_count ||= 0
+            @synchronize_before_count += 1
+            Lockstep.auto_synchronize(lazy: lazy, log: "Synchronizing before ##{meth}") if @synchronize_before_count == 1
             super(*args, &block)
+          ensure
+            @synchronize_before_count -= 1
           end
 
           ruby2_keywords meth
         end
-
-        prepend(mod)
       end
 
       def synchronize_after(meth)
-        mod = Module.new do
+        @synchronize_after_module.module_eval do
           define_method meth do |*args, &block|
+            @synchronize_after_count ||= 0
+            @synchronize_after_count += 1
             super(*args, &block)
           ensure
-            Lockstep.auto_synchronize
+            Lockstep.auto_synchronize(log: "Synchronizing after ##{meth}") if @synchronize_after_count == 1
+            @synchronize_after_count -= 1
           end
 
           ruby2_keywords meth
         end
-
-        prepend(mod)
       end
 
       def unsynchronize_after(meth)
-        mod = Module.new do
+        @unsynchronize_after_module.module_eval do
           define_method meth do |*args, &block|
             super(*args, &block)
           ensure
@@ -41,10 +51,7 @@ module Capybara
 
           ruby2_keywords meth
         end
-
-        prepend(mod)
       end
-
     end
   end
 end
@@ -158,23 +165,23 @@ Capybara::Session.class_eval do
   synchronize_around_script_method :evaluate_async_script
 end
 
-# Capybara 3 has driver-specific Node classes which sometimes
-# super to Capybara::Selenium::Node, but not always.
-node_classes = [
+# In Capybara 3 there are the specialized classes for nodes for most browers.
+# We need to patch relevant methods on all of these.
+driver_specific_node_classes = [
   (Capybara::Selenium::ChromeNode  if defined?(Capybara::Selenium::ChromeNode)),
   (Capybara::Selenium::FirefoxNode if defined?(Capybara::Selenium::FirefoxNode)),
   (Capybara::Selenium::SafariNode  if defined?(Capybara::Selenium::SafariNode)),
   (Capybara::Selenium::EdgeNode    if defined?(Capybara::Selenium::EdgeNode)),
   (Capybara::Selenium::IENode      if defined?(Capybara::Selenium::IENode)),
-].compact
+].compact.freeze
 
-if node_classes.empty?
-  # Capybara 2 has no driver-specific Node implementations,
-  # so we patch the shared base class.
-  node_classes = [Capybara::Selenium::Node]
-end
+# For other browsers (like the :remote browser) we instead get a generic node class.
+# This is also the case for Capybara 2.
+generic_node_classes = [
+  Capybara::Selenium::Node,
+].freeze
 
-node_classes.each do |node_class|
+[*driver_specific_node_classes, *generic_node_classes].each do |node_class|
   node_class.class_eval do
     extend Capybara::Lockstep::SynchronizeMacros
 

data/lib/capybara-lockstep/helper.js

@@ -177,39 +177,47 @@ window.CapybaraLockstep = (function() {
   }
 
   function isRemoteScript(element) {
-    if (element.tagName === 'SCRIPT') {
-      let src = element.getAttribute('src')
-      let type = element.getAttribute('type')
+    return element.matches('script[src]') && !hasDataSource(element)
+  }
 
-      return src && (!type || /javascript/i.test(type))
-    }
+  function isTrackableImage(element) {
+    return element.matches('img') &&
+      !element.complete &&
+      !hasDataSource(element) &&
+      element.getAttribute('loading') !== 'lazy'
   }
 
-  function isRemoteImage(element) {
-    if (element.tagName === 'IMG' && !element.complete) {
-      let src = element.getAttribute('src')
-      let srcSet = element.getAttribute('srcset')
+  function isTrackableIFrame(element) {
+    return element.matches('iframe') &&
+      !hasDataSource(element) &&
+      element.getAttribute('loading') !== 'lazy'
+  }
+
+  function hasDataSource(element) {
+    // <img> can have <img src> and <img srcset>
+    // <video> can have <video src> or <video><source src>
+    // <audio> can have <audio src> or <audio><source src>
+    return element.matches('[src*="data:"], [srcset*="data:"]') ||
+      !!element.querySelector('source [src*="data:"], source [srcset*="data:"]')
+  }
 
-      let localSrcPattern = /^data:/
-      let localSrcSetPattern = /(^|\s)data:/
+  function isTrackableMediaElement(element) {
+    return element.matches('audio, video') &&
+      element.readyState === 0 && // no metadata known
+      !hasDataSource(element) &&
+      element.getAttribute('preload') !== 'none'
+  }
 
-      let hasLocalSrc = src && localSrcPattern.test(src)
-      let hasLocalSrcSet = srcSet && localSrcSetPattern.test(srcSet)
+  function trackRemoteElement(element, condition, workTag) {
+    trackLoadingElement(element, condition, workTag, 'load', 'error')
 
-      return (src && !hasLocalSrc) || (srcSet && !hasLocalSrcSet)
-    }
   }
 
-  function isRemoteInlineFrame(element) {
-    if (element.tagName === 'IFRAME') {
-      let src = element.getAttribute('src')
-      let localSrcPattern = /^data:/
-      let hasLocalSrc = src && localSrcPattern.test(src)
-      return (src && !hasLocalSrc)
-    }
+  function trackMediaElement(element, condition, workTag) {
+    trackLoadingElement(element, condition, workTag, 'loadedmetadata', 'error')
   }
 
-  function trackRemoteElement(element, condition, workTag) {
+  function trackLoadingElement(element, condition, workTag, loadEvent, errorEvent) {
     if (!condition(element)) {
       return
     }
@@ -220,8 +228,8 @@ window.CapybaraLockstep = (function() {
 
     let doStop = function() {
       stopped = true
-      element.removeEventListener('load', doStop)
-      element.removeEventListener('error', doStop)
+      element.removeEventListener(loadEvent, doStop)
+      element.removeEventListener(errorEvent, doStop)
       stopWork(workTag)
     }
 
@@ -240,11 +248,11 @@ window.CapybaraLockstep = (function() {
     }
 
     let scheduleCheckCondition = function() {
-      setTimeout(checkCondition, 200)
+      setTimeout(checkCondition, 150)
     }
 
-    element.addEventListener('load', doStop)
-    element.addEventListener('error', doStop)
+    element.addEventListener(loadEvent, doStop)
+    element.addEventListener(errorEvent, doStop)
 
     // We periodically check whether we still think the element will
     // produce a `load` or `error` event.
@@ -256,8 +264,9 @@ window.CapybaraLockstep = (function() {
       change.addedNodes.forEach(function(addedNode) {
         if (addedNode.nodeType === Node.ELEMENT_NODE) {
           trackRemoteElement(addedNode, isRemoteScript, 'Script')
-          trackRemoteElement(addedNode, isRemoteImage, 'Image')
-          trackRemoteElement(addedNode, isRemoteInlineFrame, 'Inline frame')
+          trackRemoteElement(addedNode, isTrackableImage, 'Image')
+          trackRemoteElement(addedNode, isTrackableIFrame, 'Inline frame')
+          trackMediaElement(addedNode, isTrackableMediaElement, 'Media element')
         }
       })
     })

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "2.1.0"
+    VERSION = "2.2.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-10 00:00:00.000000000 Z
+date: 2024-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -107,7 +107,7 @@ metadata:
   homepage_uri: https://github.com/makandra/capybara-lockstep
   source_code_uri: https://github.com/makandra/capybara-lockstep
   bug_tracker_uri: https://github.com/makandra/capybara-lockstep/issues
-  changelog_uri: https://github.com/makandra/capybara-lockstep/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/makandra/capybara-lockstep/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
@@ -124,7 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
+rubygems_version: 3.4.1
 signing_key: 
 specification_version: 4
 summary: Synchronize Capybara commands with client-side JavaScript and AJAX requests