capybara-lockstep 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa8ccde381bb125f66222689d93c93008ec2137cfabc664a6ce83ff0701cd7a8
-  data.tar.gz: 7485b88104f0c4b43387f252e600ad7dc23a917eac28914249b8f279d5ab9df3
+  metadata.gz: 6e993a9ec82edc1bbea78694f16ae5b3e171255db9eb7e14064922b153d1838d
+  data.tar.gz: 1086e7149ca202b105fd0472c839451845079e05c777a0dba839483fe05c473b
 SHA512:
-  metadata.gz: 19f52ab1ca0e9f30fe8be0e791b66bcefe9992d958a104a30c602987e310363587f075f7af19bebf8248e76836a008601c700092bc3b1d53fff3fda5b764dcdc
-  data.tar.gz: e6380494b6940092842f87e54c898e6a2da9311aa2fd1951a602fb193fb44c7ee6f96907704d80382bd1cc2ccc31a7e0b433e27da8906f889aa6f7178fcd2dff
+  metadata.gz: e54e30ae12effa97dcdbd73d0f07b465b90270efc3ddd3ad83fcde7a4d305164ac0380f7ab3128a37870e78862483659eb01ff6bcdf8fade32cd52c3024d5c31
+  data.tar.gz: c067bf3f9e0be7d6a84668ee7412ea7d93d450f109e8018940e72392277bcc0f5d0ef92717a1692dee8e0443509bc9317a7b403620b6eb62bdb78539ac036098

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (0.2.3)
+    capybara-lockstep (0.3.0)
       activesupport (>= 3.2)
       capybara (>= 2.0)
       selenium-webdriver (>= 3)

data/README.md

@@ -220,7 +220,6 @@ ensure
 end
 ```
 
-
 ## Timeout
 
 By default capybara-lockstep will wait up to 10 seconds for the page initialize and for JavaScript and AJAX request to finish.
@@ -231,8 +230,28 @@ You can configure a different timeout:
 Capybara::Lockstep.timeout = 5 # seconds
 ```
 
+## Ruby 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, the DOM has been hydrated and all AJAX requests have concluded:
+
+```ruby
+Capybara::Lockstep.synchronize
+```
 
+An example use case is a Cucumber step that explicitely waits for JavaScript to finish, in the rare occasion where capybara-lockstep hasn't picked up an event or request:
 
+```gherkin
+When 'I wait for the page to load' do
+  Capybara::Lockstep.synchronize
+end
+```
 
 ## JavaScript API
 
@@ -270,55 +289,29 @@ CapybaraLockstep.isIdle() // => true
 
 ### Waiting until the browser is idle
 
-```js
-CapybaraLockstep.awaitIdle(callback)
-```
-
-## Ruby 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:
-
-```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:
+This will run the given callback once the browser is considered to be idle:
 
-```ruby
-Capybara::Lockstep.idle? # => true
-Capybara::Lockstep.busy? # => false
+```js
+CapybaraLockstep.synchronize(callback)
 ```
 
-
 ## 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

@@ -30,6 +30,10 @@ module Capybara
         @enabled = enabled
       end
 
+      def disabled?
+        !enabled?
+      end
+
       private
 
       def javascript_driver?

data/lib/capybara-lockstep/helper.js

@@ -37,7 +37,7 @@ window.CapybaraLockstep = (function() {
 
     if (isIdle()) {
       idleCallbacks.forEach(function(callback) {
-        callback('JavaScript has finished')
+        callback('Finished waiting for JavaScript')
       })
       idleCallbacks = []
     }
@@ -116,7 +116,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)
+    var observer = new MutationObserver(onAnyElementChanged)
     observer.observe(document, { subtree: true, childList: true })
   }
 
@@ -139,6 +139,28 @@ window.CapybaraLockstep = (function() {
     })
   }
 
+  var 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()
+        var observer = new MutationObserver(onInitializingAttributeChanged)
+        observer.observe(document.body, { attributes: true, attributeFilter: [INITIALIZING_ATTRIBUTE] })
+      }
+    })
+  }
+
+  function onInitializingAttributeChanged() {
+    if (!document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
+      stopWork()
+    }
+  }
+
   function isRemoteScript(node) {
     if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'SCRIPT') {
       var src = node.getAttribute('src')
@@ -155,7 +177,7 @@ window.CapybaraLockstep = (function() {
     script.addEventListener('error', stopWork)
   }
 
-  function onMutated(changes) {
+  function onAnyElementChanged(changes) {
     changes.forEach(function(change) {
       change.addedNodes.forEach(function(addedNode) {
         if (isRemoteScript(addedNode)) {
@@ -168,7 +190,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)
@@ -182,9 +204,10 @@ window.CapybaraLockstep = (function() {
     trackHistory()
     trackDynamicScripts()
     trackJQuery()
+    trackHydration()
   }
 
-  function awaitIdle(callback) {
+  function synchronize(callback) {
     if (isIdle()) {
       callback()
     } else {
@@ -196,7 +219,7 @@ window.CapybaraLockstep = (function() {
     track: track,
     startWork: startWork,
     stopWork: stopWork,
-    awaitIdle: awaitIdle,
+    synchronize: synchronize,
     isIdle: isIdle,
     isBusy: isBusy
   }

data/lib/capybara-lockstep/lockstep.rb

@@ -1,133 +1,79 @@
 module Capybara
   module Lockstep
     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
+      attr_accessor :synchronized
 
-      def await_initialized
-        @delay_await_initialized = false
-        @delay_await_idle = false # since we're also waiting for idle
-        return unless enabled?
+      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
 
-        # We're retrying the initialize check every few ms.
-        # Don't clutter the log with dozens of identical messages.
-        last_logged_reason = nil
+      def synchronized=(value)
+        page.instance_variable_set(:@lockstep_synchronized, value)
+      end
 
-        patiently(timeout) do
-          if (reason = initialize_reason)
-            if reason != last_logged_reason
-              log(reason)
-              last_logged_reason = reason
-            end
+      ERROR_SNIPPET_MISSING = 'Cannot synchronize: Capybara::Lockstep JavaScript snippet is missing on page'
+      ERROR_PAGE_MISSING = 'Cannot synchronize before initial Capybara visit'
 
-            # Raise an exception that will be retried by `patiently`
-            raise Busy, reason
-          end
+      def synchronize(lazy: false)
+        if (lazy && synchronized?) || @synchronizing || disabled?
+          return
         end
-      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
-        log 'Cannot synchronize: Alert is open'
-        @delay_await_initialized = true
-      end
 
-      def catch_up
-        return if @catching_up
+        @synchronizing = true
+
+        log 'Synchronizing'
 
         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
+          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)
+              self.synchronized = false
+            when ERROR_SNIPPET_MISSING
+              log(message_from_js)
+              self.synchronized = false
+            else
+              log message_from_js
+              log "Synchronized sucessfully"
+              self.synchronized = true
+            end
           end
+        rescue StandardError => e
+          log "#{e.class.name} while synchronizing: #{e.message}"
+          @synchronized = false
+          raise e
         ensure
-          @catching_up = false
+          @synchronizing = false
         end
       end
 
-      def idle?
-        unless enabled?
-          return true
-        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?
-      end
-
       private
 
-      def browser_made_full_page_load?
-        # Page change without visit()
-        page.has_css?('body[data-hydrating]')
-      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
-      end
-
       def page
         Capybara.current_session
       end
@@ -144,17 +90,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,18 @@
+module Capybara
+  module Lockstep
+    module Logging
+      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
+      end
+    end
+  end
+end

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "0.2.3"
+    VERSION = "0.3.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.3.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-03 00:00:00.000000000 Z
+date: 2021-03-04 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