capybara-lockstep 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa8ccde381bb125f66222689d93c93008ec2137cfabc664a6ce83ff0701cd7a8
-  data.tar.gz: 7485b88104f0c4b43387f252e600ad7dc23a917eac28914249b8f279d5ab9df3
+  metadata.gz: 783200fa3cbde0166b11c213bb677250021185b7c9898a3fd95594dd8433b89a
+  data.tar.gz: 77efe617f3ce7f138da78e8b9db031b9a8f75f07d3afe8379ae903266a9fa389
 SHA512:
-  metadata.gz: 19f52ab1ca0e9f30fe8be0e791b66bcefe9992d958a104a30c602987e310363587f075f7af19bebf8248e76836a008601c700092bc3b1d53fff3fda5b764dcdc
-  data.tar.gz: e6380494b6940092842f87e54c898e6a2da9311aa2fd1951a602fb193fb44c7ee6f96907704d80382bd1cc2ccc31a7e0b433e27da8906f889aa6f7178fcd2dff
+  metadata.gz: 6ec80d343f193b6b5a166bae1bf5ab6be2e7ae2e3c82d903596e4c604985d96382cce5012df5abdb714da614d8741f062386d60a47a1a3340734c22e46814949
+  data.tar.gz: 02e870bc8b8377be23e0ec97086219c7fd75a098f6f4eeda953dac86b7eb3a957d93984fb26265e8322c21989daa28cf4713ee3dc1772cd652f493e7999b6b57

data/Gemfile

@@ -8,3 +8,5 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
+
+gem 'byebug'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (0.2.3)
+    capybara-lockstep (0.4.0)
       activesupport (>= 3.2)
       capybara (>= 2.0)
       selenium-webdriver (>= 3)
@@ -17,6 +17,7 @@ GEM
       zeitwerk (~> 2.3)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
+    byebug (11.1.3)
     capybara (3.35.3)
       addressable
       mini_mime (>= 0.1.3)
@@ -70,6 +71,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  byebug
   capybara-lockstep!
   rake (~> 13.0)
   rspec (~> 3.0)

data/README.md

@@ -170,9 +170,13 @@ app.directive('body', function() {
 
 capybara-lockstep will automatically patch Capybara to wait for the browser after every command.
 
-Run your test suite to see if integration was successful and whether stability improves.
+Run your test suite to see if integration was successful and whether stability improves. During validation we recommend to activate `Capybara::Lockstep.debug = true` in your `spec_helper.rb` (RSpec) or `env.rb` (Cucumber). You should see messages like this in your console:
 
-When you run into issues or don't see an effect, try activating `Capybara::Lockstep.debug = true` in your `spec_helper.rb` (RSpec) or `env.rb` (Cucumber).
+```text
+[capybara-lockstep] Synchronizing
+[capybara-lockstep] Finished waiting for JavaScript
+[capybara-lockstep] Synchronized successfully
+```
 
 Note that you may see some failures from tests with wrong assertions, which sometimes passed due to lucky timing.
 
@@ -183,23 +187,37 @@ capybara-lockstep may or may not impact the runtime of your test suite. It depen
 
 While waiting for the browser to be idle does take a few milliseconds, Capybara no longer needs to retry failed commands. You will also save time from not needing to re-run failed tests.
 
-In casual testing I experienced a negative performance impact between 0% and 10%.
+In casual testing I experienced a performance impact between +/- 10%.
 
 
 ## Debugging log
 
-capybara-lockstep can print to the console whenever it waits for the browser. To enable the log:
+You can enable extensive logging. This is useful to see whether capybara-lockstep has an effect on your tests, or to debug why synchronization is taking too long.
+
+To enable the log, say this before or during a test:
 
 ```ruby
 Capybara::Lockstep.debug = true
 ```
 
-You should now see messages like this during your test runs:
+You should now see messages like this on your standard output:
+
+```
+[capybara-lockstep] Synchronizing
+[capybara-lockstep] Finished waiting for JavaScript
+[capybara-lockstep] Synchronized successfully
+```
+
+You should also see messages like this in your browser's JavaScript console:
 
 ```
-[Capybara::Lockstep] JavaScript or AJAX requests are running
+[capybara-lockstep] Started work: fetch /path [3 jobs]
+[capybara-lockstep] Finished work: fetch /path [2 jobs]
 ```
 
+
+### Using a logger
+
 You may also configure logging to an existing logger object:
 
 ```ruby
@@ -209,7 +227,9 @@ Capybara::Lockstep.debug = Rails.logger
 
 ## Disabling synchronization
 
-If for some reason you want to disable browser synchronization for a while, you can do it like this:
+Sometimes you want to disable browser synchronization, e.g. to observe a loading spinner during a long-running request.
+
+To disable synchronization:
 
 ```ruby
 begin
@@ -220,10 +240,11 @@ ensure
 end
 ```
 
+## Synchronization timeout
 
-## Timeout
+By default capybara-lockstep will wait `Capybara.default_max_wait_time` seconds for the page initialize and for JavaScript and AJAX request to finish.
 
-By default capybara-lockstep will wait up to 10 seconds for the page initialize and for JavaScript and AJAX request to finish.
+When synchronization times out, capybara-lockstep will log but not raise an error.
 
 You can configure a different timeout:
 
@@ -231,94 +252,77 @@ You can configure a different timeout:
 Capybara::Lockstep.timeout = 5 # seconds
 ```
 
+To revert to defaulting to `Capybara.default_max_wait_time`, set the timeout to `nil`:
 
+```ruby
+Capybara::Lockstep.timeout = nil
+```
 
 
-## JavaScript API
+## Manual synchronization
 
-capybara-lockstep already hooks into [many JavaScript APIs](#how-capybara-lockstep-helps) like `XMLHttpRequest` or `fetch()` to mark the browser as "busy" until their work finishes. **This should be enough for most test suites**.
+capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
 
-For additional edge cases you may interact with capybara-lockstep from your own JavaScripts.
+For additional edge cases you may manually tell capybara-lockstep to wait. The following Ruby method will block until the browser is idle:
 
-Note that when you only load the JavaScript snippet in tests you need check before calling any API functions:
+```ruby
+Capybara::Lockstep.synchronize
+```
+
+You may also synchronize from your client-side JavaScript. The following will run the given callback once the browser is idle:
 
 ```js
-if (window.CapybaraLockstep) {
-  CapybaraLockstep.startWork()
-}
+CapybaraLockstep.synchronize(callback)
 ```
 
-### Signaling asynchronous work
+## Signaling asynchronous work
 
 If for some reason you want capybara-lockstep to consider additional asynchronous work as "busy", you can do so:
 
 ```js
-CapybaraLockstep.startWork()
+CapybaraLockstep.startWork('Eject warp core')
 doAsynchronousWork().then(function() {
-  CapybaraLockstep.stopWork()
+  CapybaraLockstep.stopWork('Eject warp core')
 })
 ```
 
-### Checking if the browser is busy
-
-You can query capybara-lockstep whether it considers the browser to be busy or idle:
+The string argument is used for logging (when logging is enabled). In this case you should see messages like this in your browser's JavaScript console:
 
-```js
-CapybaraLockstep.isBusy() // => false
-CapybaraLockstep.isIdle() // => true
+```text
+[capybara-lockstep] Started work: Eject warp core [1 jobs]
+[capybara-lockstep] Finished work: Eject warp core [0 jobs]
 ```
 
-### Waiting until the browser is idle
+You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
 
-```js
-CapybaraLockstep.awaitIdle(callback)
-```
 
-## Ruby API
+## Note on interacting with the JavaScript API
 
-capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
-
-For additional edge cases you may interact with capybara-lockstep from your Ruby code.
-
-
-### Waiting until the browser is idle
-
-This will block until the document was loaded and the DOM has been hydrated:
+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.
 
-```ruby
-Capybara::Lockstep.await_initialized
-```
-
-This will block while the browser is busy with JavaScript and AJAX requests:
-
-```ruby
-Capybara::Lockstep.await_idle
 ```
-
-### Checking if the browser is busy
-
-You can query capybara-lockstep whether it considers the browser to be busy or idle:
-
-```ruby
-Capybara::Lockstep.idle? # => true
-Capybara::Lockstep.busy? # => false
+if (window.CapybaraLockstep) {
+  // interact with CapybaraLockstep
+}
 ```
 
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+
 ## Contributing
 
 Pull requests are welcome on GitHub at <https://github.com/makandra/capybara-lockstep>.
 
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+
 ## Credits
 
 Henning Koch ([@triskweline](https://twitter.com/triskweline)) from [makandra](https://makandra.com).

data/lib/capybara-lockstep.rb

@@ -10,8 +10,8 @@ end
 
 require_relative 'capybara-lockstep/version'
 require_relative 'capybara-lockstep/errors'
-require_relative 'capybara-lockstep/patiently'
 require_relative 'capybara-lockstep/configuration'
+require_relative 'capybara-lockstep/logging'
 require_relative 'capybara-lockstep/lockstep'
 require_relative 'capybara-lockstep/capybara_ext'
 require_relative 'capybara-lockstep/helper'

data/lib/capybara-lockstep/capybara_ext.rb

@@ -2,18 +2,23 @@ module Capybara
   module Lockstep
     module VisitWithWaiting
       def visit(*args, &block)
-        visiting_remote_url = !args[0].start_with?('data:')
+        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:'))
 
-        Capybara::Lockstep.catch_up
+        if visiting_remote_url
+          # We're about to leave this screen, killing all in-flight requests.
+          Capybara::Lockstep.synchronize
+        end
 
         super(*args, &block).tap do
-          # There is a 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.
           if visiting_remote_url
-            Capybara::Lockstep.await_initialized
+            # puts "After visit: unsynchronizing"
+            Capybara::Lockstep.synchronized = false
           end
         end
       end
@@ -28,13 +33,12 @@ end
 
 module Capybara
   module Lockstep
-    module AwaitIdle
-      def await_idle(meth)
+    module UnsychronizeAfter
+      def unsychronize_after(meth)
         mod = Module.new do
           define_method meth do |*args, &block|
-            Capybara::Lockstep.catch_up
             super(*args, &block).tap do
-              Capybara::Lockstep.await_idle
+              Capybara::Lockstep.synchronized = false
             end
           end
         end
@@ -62,21 +66,21 @@ end
 
 node_classes.each do |node_class|
   node_class.class_eval do
-    extend Capybara::Lockstep::AwaitIdle
+    extend Capybara::Lockstep::UnsychronizeAfter
 
-    await_idle :set
-    await_idle :select_option
-    await_idle :unselect_option
-    await_idle :click
-    await_idle :right_click
-    await_idle :double_click
-    await_idle :send_keys
-    await_idle :hover
-    await_idle :drag_to
-    await_idle :drop
-    await_idle :scroll_by
-    await_idle :scroll_to
-    await_idle :trigger
+    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
   end
 end
 
@@ -84,7 +88,9 @@ module Capybara
   module Lockstep
     module SynchronizeWithCatchUp
       def synchronize(*args, &block)
-        Capybara::Lockstep.catch_up
+        # This method is called very frequently by capybara.
+        # We use the { lazy } option to only synchronize when we're out of sync.
+        Capybara::Lockstep.synchronize(lazy: true)
 
         super(*args, &block)
       end

data/lib/capybara-lockstep/configuration.rb

@@ -3,7 +3,7 @@ module Capybara
     module Configuration
 
       def timeout
-        @timeout || 10
+        @timeout.nil? ? Capybara.default_max_wait_time : @timeout
       end
 
       def timeout=(seconds)
@@ -11,11 +11,31 @@ module Capybara
       end
 
       def debug?
-        @debug.nil? ? false : @debug
+        # @debug may also be a Logger object, so convert it to a boolean
+        @debug.nil? ? false : !!@debug
       end
 
       def debug=(debug)
         @debug = debug
+        if debug
+          target_prose = (is_logger?(debug) ? 'Ruby logger' : 'STDOUT')
+          log "Logging to #{target_prose} and browser console"
+        end
+
+        begin
+          with_max_wait_time(2) do
+            page.execute_script(<<~JS)
+              if (window.CapybaraLockstep) {
+                CapybaraLockstep.setDebug(#{debug.to_json})
+              }
+            JS
+          end
+        rescue StandardError => e
+          log "#{e.class.name} while enabling logs in browser: #{e.message}"
+          # Don't fail. The next page load will include the snippet with debugging enabled.
+        end
+
+        @debug
       end
 
       def enabled?
@@ -30,6 +50,10 @@ module Capybara
         @enabled = enabled
       end
 
+      def disabled?
+        !enabled?
+      end
+
       private
 
       def javascript_driver?

data/lib/capybara-lockstep/helper.js

@@ -1,6 +1,7 @@
 window.CapybaraLockstep = (function() {
-  var count = 0
-  var idleCallbacks = []
+  let count = 0
+  let idleCallbacks = []
+  let debug = false
 
   function isIdle() {
     // Can't check for document.readyState or body.initializing here,
@@ -13,31 +14,51 @@ window.CapybaraLockstep = (function() {
     return !isIdle()
   }
 
-  function startWork() {
-    count++
+  function log(...args) {
+    if (debug) {
+      args[0] = '%c[capybara-lockstep] ' + args[0]
+      args.splice(1, 0, 'color: #666666')
+      console.log.apply(console, args)
+    }
   }
 
-  function startWorkUntil(promise) {
-    startWork()
-    promise.then(stopWork, stopWork)
+  function logPositive(...args) {
+    args[0] = '%c' + args[0]
+    log(args[0], 'color: #117722', ...args.slice(1))
   }
 
-  function startWorkForTime(time) {
-    startWork()
-    setTimeout(stopWork, time)
+  function logNegative(...args) {
+    args[0] = '%c' + args[0]
+    log(args[0], 'color: #cc3311', ...args.slice(1))
   }
 
-  function startWorkForMicrotask() {
-    startWork()
-    Promise.resolve().then(stopWork)
+  function startWork(tag) {
+    count++
+    if (tag) {
+      logNegative('Started work: %s [%d jobs]', tag, count)
+    }
   }
 
-  function stopWork() {
+  function startWorkUntil(promise, tag) {
+    startWork(tag)
+    promise.then(stopWork, stopWork)
+  }
+
+  function startWorkForMicrotask(tag) {
+    startWork(tag)
+    Promise.resolve().then(stopWork.bind(this, tag))
+  }
+
+  function stopWork(tag) {
     count--
 
+    if (tag) {
+      logPositive('Finished work: %s [%d jobs]', tag, count)
+    }
+
     if (isIdle()) {
       idleCallbacks.forEach(function(callback) {
-        callback('JavaScript has finished')
+        callback('Finished waiting for JavaScript')
       })
       idleCallbacks = []
     }
@@ -48,29 +69,36 @@ window.CapybaraLockstep = (function() {
       return
     }
 
-    var oldFetch = window.fetch
+    let oldFetch = window.fetch
     window.fetch = function() {
-      var promise = oldFetch.apply(this, arguments)
-      startWorkUntil(promise)
+      let promise = oldFetch.apply(this, arguments)
+      startWorkUntil(promise, 'fetch ' + arguments[0])
       return promise
     }
   }
 
   function trackXHR() {
-    var oldSend = XMLHttpRequest.prototype.send
+    let oldOpen = XMLHttpRequest.prototype.open
+    let oldSend = XMLHttpRequest.prototype.send
+
+    XMLHttpRequest.prototype.open = function() {
+      this.capybaraLockstepURL = arguments[1]
+      return oldOpen.apply(this, arguments)
+    }
 
     XMLHttpRequest.prototype.send = function() {
-      startWork()
+      let workTag = 'XHR to '+ this.capybaraLockstepURL
+      startWork(workTag)
 
       try {
         this.addEventListener('readystatechange', function(event) {
-          if (this.readyState === 4) { stopWork() }
+          if (this.readyState === 4) { stopWork(workTag) }
         }.bind(this))
         return oldSend.apply(this, arguments)
       } catch (e) {
         // If we get a sync exception during request dispatch
         // we assume the request never went out.
-        stopWork()
+        stopWork(workTag)
         throw e
       }
     }
@@ -89,25 +117,12 @@ window.CapybaraLockstep = (function() {
     })
   }
 
-  function onInteraction() {
+  function onInteraction(event) {
     // We wait until the end of this microtask, assuming that any callback that
     // would queue an AJAX request or load additional scripts will run by then.
     startWorkForMicrotask()
   }
 
-  function trackHistory() {
-    ['popstate'].forEach(function(eventType) {
-      document.addEventListener(eventType, onHistoryEvent)
-    })
-  }
-
-  function onHistoryEvent() {
-    // After calling history.back() or history.forward() the popstate event will *not*
-    // fire synchronously. It will also not fire in the next task. Chrome sometimes fires
-    // it after 10ms, but sometimes it takes longer.
-    startWorkForTime(100)
-  }
-
   function trackDynamicScripts() {
     if (!window.MutationObserver) {
       return
@@ -116,7 +131,7 @@ window.CapybaraLockstep = (function() {
     // Dynamic imports or analytics snippets may insert a <script src>
     // tag that loads and executes additional JavaScript. We want to be isBusy()
     // until such scripts have loaded or errored.
-    var observer = new MutationObserver(onMutated)
+    let observer = new MutationObserver(onAnyElementChanged)
     observer.observe(document, { subtree: true, childList: true })
   }
 
@@ -130,32 +145,56 @@ window.CapybaraLockstep = (function() {
       // Although $.ajax() uses XHR internally, it also uses $.Deferred() which does
       // not resolve in the next microtask but in the next *task* (it makes itself
       // async using setTimoeut()). Hence we need to wait for it in addition to XHR.
-      var oldAjax = jQuery.ajax
-      jQuery.ajax = function () {
-        var promise = oldAjax.apply(this, arguments)
+      let oldAjax = window.jQuery.ajax
+      window.jQuery.ajax = function() {
+        let promise = oldAjax.apply(this, arguments)
         startWorkUntil(promise)
         return promise
       }
     })
   }
 
+  let INITIALIZING_ATTRIBUTE = 'data-initializing'
+
+  function trackHydration() {
+    // Until we have a body on which we can observe [data-initializing]
+    // we consider ourselves busy.
+    startWork()
+    whenReady(function() {
+      stopWork()
+      if (document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
+        startWork('Page initialization')
+        let observer = new MutationObserver(onInitializingAttributeChanged)
+        observer.observe(document.body, { attributes: true, attributeFilter: [INITIALIZING_ATTRIBUTE] })
+      }
+    })
+  }
+
+  function onInitializingAttributeChanged() {
+    if (!document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
+      stopWork('Page initialization')
+    }
+  }
+
   function isRemoteScript(node) {
     if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'SCRIPT') {
-      var src = node.getAttribute('src')
-      var type = node.getAttribute('type')
+      let src = node.getAttribute('src')
+      let type = node.getAttribute('type')
 
       return (src && (!type || /javascript/i.test(type)))
     }
   }
 
   function onRemoteScriptAdded(script) {
-    startWork()
+    let workTag = 'Remote script ' + script.getAttribute('src')
+    startWork(workTag)
+    let taggedStopWork = stopWork.bind(this, workTag)
     // Chrome runs a remote <script> *before* the load event fires.
-    script.addEventListener('load', stopWork)
-    script.addEventListener('error', stopWork)
+    script.addEventListener('load', taggedStopWork)
+    script.addEventListener('error', taggedStopWork)
   }
 
-  function onMutated(changes) {
+  function onAnyElementChanged(changes) {
     changes.forEach(function(change) {
       change.addedNodes.forEach(function(addedNode) {
         if (isRemoteScript(addedNode)) {
@@ -168,7 +207,7 @@ window.CapybaraLockstep = (function() {
   function whenReady(callback) {
     // Values are "loading", "interactive" and "completed".
     // https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState
-    if (document.readyState != 'loading') {
+    if (document.readyState !== 'loading') {
       callback()
     } else {
       document.addEventListener('DOMContentLoaded', callback)
@@ -179,12 +218,12 @@ window.CapybaraLockstep = (function() {
     trackFetch()
     trackXHR()
     trackInteraction()
-    trackHistory()
     trackDynamicScripts()
     trackJQuery()
+    trackHydration()
   }
 
-  function awaitIdle(callback) {
+  function synchronize(callback) {
     if (isIdle()) {
       callback()
     } else {
@@ -196,9 +235,10 @@ window.CapybaraLockstep = (function() {
     track: track,
     startWork: startWork,
     stopWork: stopWork,
-    awaitIdle: awaitIdle,
-    isIdle: isIdle,
-    isBusy: isBusy
+    synchronize: synchronize,
+    set debug(newDebug) {
+      debug = newDebug
+    }
   }
 })()
 

data/lib/capybara-lockstep/helper.rb

@@ -17,7 +17,13 @@ module Capybara
           tag_options[:nonce] = options.fetch(:nonce, true)
         end
 
-        javascript_tag(capybara_lockstep_js, tag_options)
+        full_js = capybara_lockstep_js
+
+        if (debug = options.fetch(:debug, Lockstep.debug?))
+          full_js += "\nCapybaraLockstep.debug = #{debug.to_json}"
+        end
+
+        javascript_tag(full_js, tag_options)
       end
 
     end

data/lib/capybara-lockstep/lockstep.rb

@@ -1,131 +1,105 @@
 module Capybara
   module Lockstep
+    ERROR_SNIPPET_MISSING = 'Cannot synchronize: capybara-lockstep JavaScript snippet is missing'
+    ERROR_PAGE_MISSING = 'Cannot synchronize before initial Capybara visit'
+    ERROR_ALERT_OPEN = 'Cannot synchronize while an alert is open'
+    ERROR_NAVIGATED_AWAY = "Browser navigated away while synchronizing"
+
     class << self
-      include Patiently
       include Configuration
+      include Logging
 
-      def await_idle
-        @delay_await_idle = false
-        return unless enabled?
-
-        with_max_wait_time(timeout) do
-          message_from_js = evaluate_async_script(<<~JS)
-            let done = arguments[0]
-            if (window.CapybaraLockstep) {
-              CapybaraLockstep.awaitIdle(done)
-            } else {
-              done('Cannot synchronize: Capybara::Lockstep was not included in page')
-            }
-          JS
-          log(message_from_js)
-        end
-      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
-        log 'Cannot synchronize: Alert is open'
-        @delay_await_idle = true
-      end
-
-      def await_initialized
-        @delay_await_initialized = false
-        @delay_await_idle = false # since we're also waiting for idle
-        return unless enabled?
-
-        # We're retrying the initialize check every few ms.
-        # Don't clutter the log with dozens of identical messages.
-        last_logged_reason = nil
-
-        patiently(timeout) do
-          if (reason = initialize_reason)
-            if reason != last_logged_reason
-              log(reason)
-              last_logged_reason = reason
-            end
+      attr_accessor :synchronizing
+      alias synchronizing? synchronizing
 
-            # Raise an exception that will be retried by `patiently`
-            raise Busy, reason
-          end
-        end
-      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
-        log 'Cannot synchronize: Alert is open'
-        @delay_await_initialized = true
+      def synchronized?
+        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
       end
 
-      def catch_up
-        return if @catching_up
-
-        begin
-          @catching_up = true
-          if @delay_await_initialized
-            log 'Retrying synchronization'
-            await_initialized
-          # elsif browser_made_full_page_load?
-          #   log 'Browser loaded new page'
-          #   await_initialized
-          elsif @delay_await_idle
-            log 'Retrying synchronization'
-            await_idle
-          end
-        ensure
-          @catching_up = false
-        end
+      def synchronized=(value)
+        page.instance_variable_set(:@lockstep_synchronized, value)
       end
 
-      def idle?
-        unless enabled?
-          return true
+      def synchronize(lazy: false)
+        if (lazy && synchronized?) || synchronizing? || disabled?
+          return
         end
 
-        result = execute_script(<<~JS)
-          if (window.CapybaraLockstep) {
-            return CapybaraLockstep.isIdle()
-          } else {
-            return 'Cannot check busy state: Capybara::Lockstep was not included in page'
-          }
-        JS
-
-        if result.is_a?(String)
-          log(result)
-          # When the snippet is missing we assume that the browser is idle.
-          # Otherwise we would wait forever.
-          true
-        else
-          result
-        end
-      end
-
-      def busy?
-        !idle?
+        synchronize_now
       end
 
       private
 
-      def browser_made_full_page_load?
-        # Page change without visit()
-        page.has_css?('body[data-hydrating]')
+      def synchronize_now
+        self.synchronizing = true
+        self.synchronized = false
+
+        log 'Synchronizing'
+
+        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})
+                }
+              }
+              let protocol = location.protocol
+              if (protocol === 'data:' || protocol == 'about:') {
+                done(#{ERROR_PAGE_MISSING.to_json})
+              } else if (document.readyState === 'complete') {
+                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
+              log "Synchronized successfully"
+              self.synchronized = true
+            end
+          end
+        rescue ::Selenium::WebDriver::Error::ScriptTimeoutError
+          log "Could not synchronize within #{timeout} seconds"
+          # Don't raise an error, this may happen if the server is slow to respond.
+          # We will retry on the next Capybara synchronize call.
+        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
       end
 
-      def initialize_reason
-        execute_script(<<~JS)
-          if (location.href.indexOf('data:') == 0) {
-            return 'Requesting initial page'
-          }
-
-          if (document.readyState !== "complete") {
-            return 'Document is loading'
-          }
-
-          // The application layouts render a <body data-initializing>.
-          // The [data-initializing] attribute is removed by an Angular directive or Unpoly compiler (frontend).
-          // to signal that all elements have been activated.
-          if (document.querySelector('body[data-initializing]')) {
-            return 'DOM is being hydrated'
-          }
-
-          if (window.CapybaraLockstep && CapybaraLockstep.isBusy()) {
-            return 'JavaScript or AJAX requests are running'
-          }
-
-          return false
-        JS
+      def unhandled_synchronize_error(e)
+        log "#{e.class.name} while synchronizing: #{e.message}"
+        raise e
       end
 
       def page
@@ -144,17 +118,10 @@ module Capybara
         end
       end
 
-      def log(message)
-        if debug? && message.present?
-          message = "[Capybara::Lockstep] #{message}"
-          if @debug.respond_to?(:debug)
-            # If someone set Capybara::Lockstep to a logger, use that
-            @debug.debug(message)
-          else
-            # Otherwise print to STDOUT
-            puts message
-          end
-        end
+      def ignoring_alerts(&block)
+        block.call
+      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
+        # no-op
       end
 
     end

data/lib/capybara-lockstep/logging.rb

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

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "0.2.3"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-03 00:00:00.000000000 Z
+date: 2021-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -77,7 +77,7 @@ files:
 - lib/capybara-lockstep/helper.js
 - lib/capybara-lockstep/helper.rb
 - lib/capybara-lockstep/lockstep.rb
-- lib/capybara-lockstep/patiently.rb
+- lib/capybara-lockstep/logging.rb
 - lib/capybara-lockstep/version.rb
 homepage: https://github.com/makandra/capybara-lockstep
 licenses:

data/lib/capybara-lockstep/patiently.rb

@@ -1,58 +0,0 @@
-module Capybara
-  module Lockstep
-    # Ported from https://github.com/makandra/spreewald/blob/master/lib/spreewald_support/tolerance_for_selenium_sync_issues.rb
-    module Patiently
-
-      RETRY_ERRORS = %w[
-        Capybara::Lockstep::Busy
-        Capybara::ElementNotFound
-        Spec::Expectations::ExpectationNotMetError
-        RSpec::Expectations::ExpectationNotMetError
-        Minitest::Assertion
-        Capybara::Poltergeist::ClickFailed
-        Capybara::ExpectationNotMet
-        Selenium::WebDriver::Error::StaleElementReferenceError
-        Selenium::WebDriver::Error::NoAlertPresentError
-        Selenium::WebDriver::Error::ElementNotVisibleError
-        Selenium::WebDriver::Error::NoSuchFrameError
-        Selenium::WebDriver::Error::NoAlertPresentError
-        Selenium::WebDriver::Error::JavascriptError
-        Selenium::WebDriver::Error::UnknownError
-        Selenium::WebDriver::Error::NoSuchAlertError
-      ]
-
-      # evaluate_script latency is ~ 0.025s
-      WAIT_PERIOD = 0.03
-
-      def patiently(timeout = Capybara.default_max_wait_time, &block)
-        started = monotonic_time
-        tries = 0
-        begin
-          tries += 1
-          block.call
-        rescue Exception => e
-          raise e unless retryable_error?(e)
-          raise e if (monotonic_time - started > timeout && tries >= 2)
-          sleep(WAIT_PERIOD)
-          if monotonic_time == started
-            raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead"
-          end
-          retry
-        end
-      end
-
-      private
-
-      def monotonic_time
-        # We use the system clock (i.e. seconds since boot) to calculate the time,
-        # because Time.now may be frozen
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-
-      def retryable_error?(e)
-        RETRY_ERRORS.include?(e.class.name)
-      end
-
-    end
-  end
-end