capybara-lockstep 0.4.0 → 1.1.0

data/Rakefile

@@ -6,3 +6,11 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+require 'jasmine'
+load 'jasmine/tasks/jasmine.rake'
+
+begin
+  require 'gemika/tasks'
+rescue LoadError
+  puts 'Run `gem install gemika` for additional tasks'
+end

data/capybara-lockstep.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "capybara", ">= 2.0"
   spec.add_dependency "selenium-webdriver", ">= 3"
   spec.add_dependency "activesupport", ">= 3.2"
+  spec.add_dependency "ruby2_keywords"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/capybara-lockstep/capybara_ext.rb

@@ -1,7 +1,9 @@
+require 'ruby2_keywords'
+
 module Capybara
   module Lockstep
     module VisitWithWaiting
-      def visit(*args, &block)
+      ruby2_keywords 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
@@ -12,13 +14,18 @@ module Capybara
 
         if visiting_remote_url
           # We're about to leave this screen, killing all in-flight requests.
-          Capybara::Lockstep.synchronize
+          # 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)
         end
 
         super(*args, &block).tap do
           if visiting_remote_url
-            # puts "After visit: unsynchronizing"
-            Capybara::Lockstep.synchronized = false
+            # We haven't yet synchronized the new screen.
+            Lockstep.synchronized = false
           end
         end
       end
@@ -26,11 +33,57 @@ module Capybara
   end
 end
 
-
 Capybara::Session.class_eval do
   prepend Capybara::Lockstep::VisitWithWaiting
 end
 
+module Capybara
+  module Lockstep
+    module SynchronizeAroundScriptMethod
+
+      def synchronize_around_script_method(meth)
+        mod = Module.new do
+          define_method meth do |script, *args, &block|
+            # Synchronization uses execute_script itself, so don't synchronize when
+            # we're already synchronizing.
+            if !Lockstep.synchronizing?
+              # It's generally a good idea to synchronize before a JavaScript wants
+              # to access or observe an earlier state change.
+              #
+              # In case the given script navigates away (with `location.href = url`,
+              # `history.back()`, etc.) we would kill all in-flight requests. For this case
+              # we force a non-lazy synchronization so we pick up all client-side changes
+              # that have not been caused by Capybara commands.
+              script_may_navigate_away = script =~ /\b(location|history)\b/
+              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
+            end
+          end
+          ruby2_keywords meth
+        end
+        prepend(mod)
+      end
+
+    end
+  end
+end
+
+Capybara::Session.class_eval do
+  extend Capybara::Lockstep::SynchronizeAroundScriptMethod
+
+  synchronize_around_script_method :execute_script
+  synchronize_around_script_method :evaluate_async_script
+  # Don't synchronize around evaluate_script. It calls execute_script
+  # internally and we don't want to synchronize multiple times.
+end
+
 module Capybara
   module Lockstep
     module UnsychronizeAfter
@@ -38,9 +91,10 @@ module Capybara
         mod = Module.new do
           define_method meth do |*args, &block|
             super(*args, &block).tap do
-              Capybara::Lockstep.synchronized = false
+              Lockstep.synchronized = false
             end
           end
+          ruby2_keywords meth
         end
         prepend(mod)
       end
@@ -87,10 +141,11 @@ end
 module Capybara
   module Lockstep
     module SynchronizeWithCatchUp
-      def synchronize(*args, &block)
-        # This method is called very frequently by capybara.
+      ruby2_keywords 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.synchronize(lazy: true)
+        Capybara::Lockstep.auto_synchronize(lazy: true)
 
         super(*args, &block)
       end

data/lib/capybara-lockstep/configuration.rb

@@ -10,48 +10,71 @@ module Capybara
         @timeout = seconds
       end
 
+      def timeout_with
+        @timeout_with.nil? ? :log : @timeout_with
+      end
+
+      def timeout_with=(action)
+        @timeout_with = action&.to_sym
+      end
+
       def 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')
+      def debug=(value)
+        @debug = value
+        if value
+          target_prose = (is_logger?(value) ? '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
+        send_config_to_browser(<<~JS)
+          CapybaraLockstep.debug = #{value.to_json}
+        JS
 
         @debug
       end
 
-      def enabled?
+      def mode
         if javascript_driver?
-          @enabled.nil? ? true : @enabled
+          @mode.nil? ? :auto : @mode
         else
-          false
+          :off
         end
       end
 
+      def mode=(mode)
+        @mode = mode&.to_sym
+      end
+
       def enabled=(enabled)
-        @enabled = enabled
+        case enabled
+        when true
+          log "Setting `Capybara::Lockstep.enabled = true` is deprecated. Set `Capybara::Lockstep.mode = :auto` instead."
+          self.mode = :auto
+        when false
+          log "Setting `Capybara::Lockstep.enabled = false` is deprecated. Set `Capybara::Lockstep.mode = :manual` or `Capybara::Lockstep.mode = :off` instead."
+          self.mode = :manual
+        when nil
+          # Reset to default
+          self.mode = nil
+        end
       end
 
-      def disabled?
-        !enabled?
+      def wait_tasks
+        @wait_tasks
+      end
+
+      def wait_tasks=(value)
+        @wait_tasks = value
+
+        send_config_to_browser(<<~JS)
+          CapybaraLockstep.waitTasks = #{value.to_json}
+        JS
+
+        @wait_tasks
       end
 
       private
@@ -60,6 +83,21 @@ module Capybara
         driver.is_a?(Capybara::Selenium::Driver)
       end
 
+      def send_config_to_browser(js)
+        begin
+          with_max_wait_time(2) do
+            page.execute_script(<<~JS)
+              if (window.CapybaraLockstep) {
+                #{js}
+              }
+            JS
+          end
+        rescue StandardError => e
+          log "#{e.class.name} while configuring capybara-lockstep in browser: #{e.message}"
+          # Don't fail. The next page load will include the snippet with the new config.
+        end
+      end
+
     end
   end
 end

data/lib/capybara-lockstep/errors.rb

@@ -1,6 +1,6 @@
 module Capybara
   module Lockstep
     class Error < StandardError; end
-    class Busy < Error; end
+    class Timeout < Error; end
   end
 end

data/lib/capybara-lockstep/helper.js

@@ -1,13 +1,23 @@
 window.CapybaraLockstep = (function() {
-  let count = 0
-  let idleCallbacks = []
-  let debug = false
+  // State and configuration
+  let debug
+  let jobCount
+  let idleCallbacks
+  let waitTasks
+  reset()
+
+  function reset() {
+    jobCount = 0
+    idleCallbacks = []
+    waitTasks = 0
+    debug = false
+  }
 
   function isIdle() {
     // Can't check for document.readyState or body.initializing here,
     // since the user might navigate away from the page before it finishes
     // initializing.
-    return count === 0
+    return jobCount === 0
   }
 
   function isBusy() {
@@ -33,34 +43,43 @@ window.CapybaraLockstep = (function() {
   }
 
   function startWork(tag) {
-    count++
+    jobCount++
     if (tag) {
-      logNegative('Started work: %s [%d jobs]', tag, count)
+      logNegative('Started work: %s [%d jobs]', tag, jobCount)
     }
   }
 
   function startWorkUntil(promise, tag) {
     startWork(tag)
-    promise.then(stopWork, stopWork)
+    let taggedStopWork = stopWork.bind(this, tag)
+    promise.then(taggedStopWork, taggedStopWork)
   }
 
-  function startWorkForMicrotask(tag) {
-    startWork(tag)
-    Promise.resolve().then(stopWork.bind(this, tag))
+  function stopWork(tag) {
+    let tasksElapsed = 0
+
+    let check = function() {
+      if (tasksElapsed < waitTasks) {
+        tasksElapsed++
+        setTimeout(check)
+      } else {
+        stopWorkNow(tag)
+      }
+    }
+
+    check()
   }
 
-  function stopWork(tag) {
-    count--
+  function stopWorkNow(tag) {
+    jobCount--
 
     if (tag) {
-      logPositive('Finished work: %s [%d jobs]', tag, count)
+      logPositive('Finished work: %s [%d jobs]', tag, jobCount)
     }
 
-    if (isIdle()) {
-      idleCallbacks.forEach(function(callback) {
-        callback('Finished waiting for JavaScript')
-      })
-      idleCallbacks = []
+    let idleCallback
+    while (isIdle() && (idleCallback = idleCallbacks.shift())) {
+      idleCallback('Finished waiting for browser')
     }
   }
 
@@ -104,47 +123,32 @@ window.CapybaraLockstep = (function() {
     }
   }
 
-  function trackInteraction() {
-    // We already override all interaction methods in the Selenium browser nodes, so they
-    // wait for an idle frame afterwards. However a test script might also dispatch synthetic
-    // events with executate_script() to manipulate the browser in ways that are not possible
-    // with the Capybara API. When we observe such an event we wait until the end of the microtask,
-    // assuming any busy action will be queued by then.
-    ['click',  'mousedown', 'keydown', 'change', 'input', 'submit', 'focusin', 'focusout', 'scroll'].forEach(function(eventType) {
-      // Use { useCapture: true } so we get the event before another listener
-      // can prevent it from bubbling up to the document.
-      document.addEventListener(eventType, onInteraction, { capture: true, passive: true })
-    })
-  }
-
-  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 trackDynamicScripts() {
+  function trackRemoteElements() {
     if (!window.MutationObserver) {
       return
     }
 
-    // Dynamic imports or analytics snippets may insert a <script src>
-    // tag that loads and executes additional JavaScript. We want to be isBusy()
+    // Dynamic imports or analytics snippets may insert a script element
+    // that loads and executes additional JavaScript. We want to be isBusy()
     // until such scripts have loaded or errored.
     let observer = new MutationObserver(onAnyElementChanged)
     observer.observe(document, { subtree: true, childList: true })
   }
 
   function trackJQuery() {
-    // jQuery may be loaded after us, so we wait until DOMContentReady.
+    // CapybaraLockstep.track() is called as the first script in the head.
+    // jQuery will be loaded after us, so we wait until DOMContentReady.
     whenReady(function() {
-      if (!window.jQuery) {
+      if (!window.jQuery || waitTasks > 0) {
         return
       }
 
       // 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.
+      //
+      // If user code also uses $.Deferred(), it is also recommended to set
+      // CapybaraLockdown.waitTasks = 1 or higher.
       let oldAjax = window.jQuery.ajax
       window.jQuery.ajax = function() {
         let promise = oldAjax.apply(this, arguments)
@@ -154,56 +158,97 @@ window.CapybaraLockstep = (function() {
     })
   }
 
-  let INITIALIZING_ATTRIBUTE = 'data-initializing'
+  function isRemoteScript(element) {
+    if (element.tagName === 'SCRIPT') {
+      let src = element.getAttribute('src')
+      let type = element.getAttribute('type')
 
-  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] })
-      }
-    })
+      return src && (!type || /javascript/i.test(type))
+    }
   }
 
-  function onInitializingAttributeChanged() {
-    if (!document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
-      stopWork('Page initialization')
+  function isRemoteImage(element) {
+    if (element.tagName === 'IMG' && !element.complete) {
+      let src = element.getAttribute('src')
+      let srcSet = element.getAttribute('srcset')
+
+      let localSrcPattern = /^data:/
+      let localSrcSetPattern = /(^|\s)data:/
+
+      let hasLocalSrc = src && localSrcPattern.test(src)
+      let hasLocalSrcSet = srcSet && localSrcSetPattern.test(srcSet)
+
+      return (src && !hasLocalSrc) || (srcSet && !hasLocalSrcSet)
     }
   }
 
-  function isRemoteScript(node) {
-    if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'SCRIPT') {
-      let src = node.getAttribute('src')
-      let type = node.getAttribute('type')
-
-      return (src && (!type || /javascript/i.test(type)))
+  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 onRemoteScriptAdded(script) {
-    let workTag = 'Remote script ' + script.getAttribute('src')
+  function trackRemoteElement(element, condition, workTag) {
+    if (!condition(element)) {
+      return
+    }
+
+    let stopped = false
+
     startWork(workTag)
-    let taggedStopWork = stopWork.bind(this, workTag)
-    // Chrome runs a remote <script> *before* the load event fires.
-    script.addEventListener('load', taggedStopWork)
-    script.addEventListener('error', taggedStopWork)
+
+    let doStop = function() {
+      stopped = true
+      element.removeEventListener('load', doStop)
+      element.removeEventListener('error', doStop)
+      stopWork(workTag)
+    }
+
+    let checkCondition = function() {
+      if (stopped) {
+        // A `load` or `error` event has fired.
+        // We can stop here. No need to schedule another check.
+        return
+      } else if (isDetached(element) || !condition(element)) {
+        // If it is detached or if its `[src]` attribute changes to a data: URL
+        // we may never get a `load` or `error` event.
+        doStop()
+      } else {
+        scheduleCheckCondition()
+      }
+    }
+
+    let scheduleCheckCondition = function() {
+      setTimeout(checkCondition, 200)
+    }
+
+    element.addEventListener('load', doStop)
+    element.addEventListener('error', doStop)
+
+    // We periodically check whether we still think the element will
+    // produce a `load` or `error` event.
+    scheduleCheckCondition()
   }
 
   function onAnyElementChanged(changes) {
     changes.forEach(function(change) {
       change.addedNodes.forEach(function(addedNode) {
-        if (isRemoteScript(addedNode)) {
-          onRemoteScriptAdded(addedNode)
+        if (addedNode.nodeType === Node.ELEMENT_NODE) {
+          trackRemoteElement(addedNode, isRemoteScript, 'Script')
+          trackRemoteElement(addedNode, isRemoteImage, 'Image')
+          trackRemoteElement(addedNode, isRemoteInlineFrame, 'Inline frame')
         }
       })
     })
   }
 
+  function isDetached(element) {
+    return !document.contains(element)
+  }
+
   function whenReady(callback) {
     // Values are "loading", "interactive" and "completed".
     // https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState
@@ -214,13 +259,28 @@ window.CapybaraLockstep = (function() {
     }
   }
 
+  function trackOldUnpoly() {
+    // CapybaraLockstep.track() is called as the first script in the head.
+    // Unpoly will be loaded after us, so we wait until DOMContentReady.
+    whenReady(function() {
+      // Unpoly 0.x would wait one task after DOMContentLoaded before booting.
+      // There's a slim chance that Capybara can observe the page before compilers have run.
+      // Unpoly 1.0+ runs compilers on DOMContentLoaded, so there's no issue.
+      if (window.up?.version?.startsWith('0.')) {
+        startWork('Old Unpoly')
+        setTimeout(function () {
+          stopWork('Old Unpoly')
+        })
+      }
+    })
+  }
+
   function track() {
+    trackOldUnpoly()
     trackFetch()
     trackXHR()
-    trackInteraction()
-    trackDynamicScripts()
+    trackRemoteElements()
     trackJQuery()
-    trackHydration()
   }
 
   function synchronize(callback) {
@@ -233,12 +293,14 @@ window.CapybaraLockstep = (function() {
 
   return {
     track: track,
+    isBusy: isBusy,
+    isIdle: isIdle,
     startWork: startWork,
     stopWork: stopWork,
     synchronize: synchronize,
-    set debug(newDebug) {
-      debug = newDebug
-    }
+    reset: reset,
+    set debug(value) { debug = value },
+    set waitTasks(value) { waitTasks = value }
   }
 })()