capybara-lockstep 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 271ed22154f61a70a3961eb2bd2a8a7d29430dfb37107b9f1176257e8efab320
-  data.tar.gz: 6ba0d7a5c7e8bff779ee2a9ac2d6d32829374041dff41d7bddd9cbd19627a468
+  metadata.gz: ec0d3874212ec29a338fa16ef831e76c0b8dc65b4a200f3a305b7ce41bd76957
+  data.tar.gz: b5d48346fb7224b2154512534757ef96638f1df9cc62f9d0f911aac8d6a5f846
 SHA512:
-  metadata.gz: 24f098f75fc9093065cf4210eed7fab3b8f1ea69d49d6e328f195f92affe41c262fa92daecbf1ee8247dba8bcad1d3d5c0941766bd3889416be6aedf79f3e354
-  data.tar.gz: ea3debf0f2e4178dbc200c84a98aae87a614914de889769d10ed1cc2e311f83e93de460e2b1a4c163b756dc331838164bfe7ae8f77f676833df93a984a2fda49
+  metadata.gz: 4d44c17fa50ca0fd386b34ecea302148989f4d48d63c48820bcfff75bcd51c63cfbacea0053e63fc1c27f6347fbe252f14be83372aed123a6a1c2574328fe42e
+  data.tar.gz: 9e7f5cfcbb6b3750277bc55c37484e17859aa4d96f1b8f7b6c1865f4467ae00fad5311e11ea0bfc73d5b8ec5c925df5c8ec6bb2473da6b431296736c89972794

data/CHANGELOG.md

@@ -2,6 +2,39 @@ 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).
 
+## 1.2.0 - 2022-09-12
+
+### Synchronization around history navigation
+
+We now synchronize before and after history navigation using the following Capybara methods:
+
+- `page.refresh`
+- `page.go_back`
+- `page.go_forward`
+
+We also synchronize before `current_url` in case running a JavaScript task wants to update the URL when done.
+
+### Support for tests with multiple tabs or frames
+
+capybara-lockstep now supports test that work with [multiple frames](https://makandracards.com/makandra/34015-use-capybara-commands-inside-an-iframe) or [multiple tabs or windows](https://github.com/teamcapybara/capybara#working-with-windows).
+We now synchronize before and after the following Capybara methods:
+
+- `switch_to_frame`
+- `within_frame`
+- `switch_to_window`
+- `within_window`
+
+### Improved logging
+
+- Only log when we're actually synchronizing
+- Log the reason why we're synchronizing (e.g. before node access)
+- Log which browser work we're waiting for (e.g. XHR request, image load)
+
+### Various changes
+
+- Synchronize before accessing `page.html`.
+
+
 ## 1.1.1 - 2022-03-16
 
 - Activate rubygems MFA

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (1.1.1)
+    capybara-lockstep (1.2.0)
       activesupport (>= 3.2)
       capybara (>= 2.0)
       ruby2_keywords
@@ -10,32 +10,32 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.3.1)
+    activesupport (7.0.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
-      zeitwerk (~> 2.3)
-    addressable (2.7.0)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     byebug (11.1.3)
-    capybara (3.35.3)
+    capybara (3.36.0)
       addressable
+      matrix
       mini_mime (>= 0.1.3)
       nokogiri (~> 1.8)
       rack (>= 1.6.0)
       rack-test (>= 0.6.3)
       regexp_parser (>= 1.5, < 3.0)
       xpath (~> 3.2)
-    childprocess (3.0.0)
+    childprocess (4.1.0)
     chrome_remote (0.3.0)
       websocket-driver (~> 0.6)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.10)
     daemons (1.3.1)
     diff-lcs (1.3)
     eventmachine (1.2.7)
     gemika (0.6.0)
-    i18n (1.8.10)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
     jasmine (3.6.0)
       jasmine-core (~> 3.6.0)
@@ -43,18 +43,20 @@ GEM
       rack (>= 1.2.1)
       rake
     jasmine-core (3.6.0)
-    mini_mime (1.1.0)
-    minitest (5.14.4)
-    nokogiri (1.11.3-x86_64-linux)
+    matrix (0.4.2)
+    mini_mime (1.1.2)
+    minitest (5.15.0)
+    nokogiri (1.13.0-x86_64-linux)
       racc (~> 1.4)
     phantomjs (2.1.1.0)
     public_suffix (4.0.6)
-    racc (1.5.2)
+    racc (1.6.0)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rake (13.0.1)
-    regexp_parser (2.1.1)
+    regexp_parser (2.2.0)
+    rexml (3.2.5)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
@@ -68,10 +70,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.0)
-    ruby2_keywords (0.0.4)
-    rubyzip (2.3.0)
-    selenium-webdriver (3.142.7)
-      childprocess (>= 0.5, < 4.0)
+    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)
       daemons (~> 1.0, >= 1.0.9)
@@ -84,7 +87,6 @@ GEM
     websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
-    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
@@ -100,4 +102,4 @@ DEPENDENCIES
   thin
 
 BUNDLED WITH
-   2.2.15
+   2.2.32

data/README.md

@@ -309,7 +309,7 @@ end
 
 In the `:manual` mode you may still force synchronization by calling `Capybara::Lockstep.synchronize` manually.
 
-To completely disable synchronization:
+To completely disable synchronization, even when `Capybara::Lockstep.synchronize` is called:
 
 ```ruby
 Capybara::Lockstep.mode = :off

data/lib/capybara-lockstep/capybara_ext.rb

@@ -1,34 +1,99 @@
 require 'ruby2_keywords'
 
+module Capybara
+  module Lockstep
+    module UnsychronizeAfter
+      def unsychronize_after(meth)
+        mod = Module.new do
+          define_method meth do |*args, &block|
+            super(*args, &block)
+          ensure
+            Lockstep.synchronized = false
+          end
+
+          ruby2_keywords meth
+        end
+
+        prepend(mod)
+      end
+    end
+  end
+end
+
+module Capybara
+  module Lockstep
+    module SynchronizeBefore
+      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
+    end
+  end
+end
+
+Capybara::Session.class_eval do
+  extend Capybara::Lockstep::SynchronizeBefore
+  extend Capybara::Lockstep::UnsychronizeAfter
+
+  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
+
+  synchronize_before :go_back, lazy: false # wait until running JavaScript has updated the URL
+  unsychronize_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
+
+  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.
+
+  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.
+end
+
 module Capybara
   module Lockstep
     module VisitWithWaiting
-      ruby2_keywords def visit(*args, &block)
+      def visit(*args, &block)
         url = args[0]
         # Some of our apps have a Cucumber step that changes drivers mid-scenario.
         # It works by creating a new Capybara session and re-visits the URL from the
         # previous session. If this happens before a URL is ever loaded,
         # it re-visits the URL "data:", which will never "finish" initializing.
         # Also when opening a new tab via Capybara, the initial URL is about:blank.
-        visiting_remote_url = !(url.start_with?('data:') || url.start_with?('about:'))
+        visiting_real_url = !(url.start_with?('data:') || url.start_with?('about:'))
 
-        if visiting_remote_url
+        if visiting_real_url
           # We're about to leave this screen, killing all in-flight requests.
           # Give pending form submissions etc. a chance to finish before we tear down
           # the browser environment.
           #
           # We force a non-lazy synchronization so we pick up all client-side changes
           # that have not been caused by Capybara commands.
-          Lockstep.synchronize(lazy: false)
+          Lockstep.auto_synchronize(lazy: false, log: "Synchronizing before visiting #{url}")
         end
 
         super(*args, &block).tap do
-          if visiting_remote_url
+          if visiting_real_url
             # We haven't yet synchronized the new screen.
             Lockstep.synchronized = false
           end
         end
       end
+
+      ruby2_keywords :visit
     end
   end
 end
@@ -58,14 +123,15 @@ module Capybara
               Lockstep.auto_synchronize(lazy: !script_may_navigate_away, log: "Synchronizing before script: #{script}")
             end
 
-            super(script, *args, &block).tap do
-              if !Lockstep.synchronizing?
-                # We haven't yet synchronized with whatever changes the JavaScript
-                # did on the frontend.
-                Lockstep.synchronized = false
-              end
+            super(script, *args, &block)
+          ensure
+            if !Lockstep.synchronizing?
+              # We haven't yet synchronized with whatever changes the JavaScript
+              # did on the frontend.
+              Lockstep.synchronized = false
             end
           end
+
           ruby2_keywords meth
         end
         prepend(mod)
@@ -84,24 +150,6 @@ Capybara::Session.class_eval do
   # internally and we don't want to synchronize multiple times.
 end
 
-module Capybara
-  module Lockstep
-    module UnsychronizeAfter
-      def unsychronize_after(meth)
-        mod = Module.new do
-          define_method meth do |*args, &block|
-            super(*args, &block).tap do
-              Lockstep.synchronized = false
-            end
-          end
-          ruby2_keywords meth
-        end
-        prepend(mod)
-      end
-    end
-  end
-end
-
 # Capybara 3 has driver-specific Node classes which sometimes
 # super to Capybara::Selenium::Node, but not always.
 node_classes = [
@@ -141,14 +189,16 @@ end
 module Capybara
   module Lockstep
     module SynchronizeWithCatchUp
-      ruby2_keywords def synchronize(*args, &block)
+      def synchronize(*args, &block)
         # This method is called by Capybara before most interactions with
         # the browser. It is a different method than Capybara::Lockstep.synchronize!
         # We use the { lazy } option to only synchronize when we're out of sync.
-        Capybara::Lockstep.auto_synchronize(lazy: true)
+        Lockstep.auto_synchronize(lazy: true, log: 'Synchronizing before node access')
 
         super(*args, &block)
       end
+
+      ruby2_keywords :synchronize
     end
   end
 end

data/lib/capybara-lockstep/helper.js

@@ -3,12 +3,14 @@ window.CapybaraLockstep = (function() {
   let debug
   let jobCount
   let idleCallbacks
+  let finishedWorkTags
   let waitTasks
   reset()
 
   function reset() {
     jobCount = 0
     idleCallbacks = []
+    finishedWorkTags = []
     waitTasks = 0
     debug = false
   }
@@ -74,12 +76,17 @@ window.CapybaraLockstep = (function() {
     jobCount--
 
     if (tag) {
+      finishedWorkTags.push(tag)
       logPositive('Finished work: %s [%d jobs]', tag, jobCount)
     }
 
-    let idleCallback
-    while (isIdle() && (idleCallback = idleCallbacks.shift())) {
-      idleCallback('Finished waiting for browser')
+    if (isIdle()) {
+      let idleCallback
+      while ((idleCallback = idleCallbacks.shift())) {
+        idleCallback("Finished waiting for " + finishedWorkTags.join(', '))
+      }
+
+      finishedWorkTags = []
     }
   }
 

data/lib/capybara-lockstep/lockstep.rb

@@ -13,7 +13,17 @@ module Capybara
       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
@@ -24,19 +34,30 @@ module Capybara
       end
 
       def synchronize(lazy: false, log: nil)
+        # 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.
+        #
+        # 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.
+        # However the knowledge of the Ruby-side is limited: We only assume that we're out of sync
+        # after a page load or after a Capybara command. There may be additional client-side work
+        # that the Ruby-side is not aware of, e.g. an AJAX call scheduled by a timeout.
+        #
+        # With { lazy: false } we force synchronization with the browser, whether the Ruby-side
+        # 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
 
-        # Allow passing a log message that is only logged
-        # when we're actually synchronizing.
-        if log
-          self.log(log)
-        end
-
-        synchronize_now
+        synchronize_now(log: log)
       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)
@@ -45,11 +66,11 @@ module Capybara
 
       private
 
-      def synchronize_now
+      def synchronize_now(log: 'Synchronizing')
         self.synchronizing = true
         self.synchronized = false
 
-        log 'Synchronizing'
+        self.log(log)
 
         start_time = current_seconds
 

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "1.1.1"
+    VERSION = "1.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-16 00:00:00.000000000 Z
+date: 2022-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.6
 signing_key: 
 specification_version: 4
 summary: Synchronize Capybara commands with client-side JavaScript and AJAX requests