capybara-lockstep 0.3.2 → 0.7.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,58 @@ 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.log "Synchronizing before script: #{script}"
+              Lockstep.synchronize(lazy: !script_may_navigate_away)
+            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 +92,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,7 +142,7 @@ end
 module Capybara
   module Lockstep
     module SynchronizeWithCatchUp
-      def synchronize(*args, &block)
+      ruby2_keywords def synchronize(*args, &block)
         # 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)

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,22 @@ 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
+      def debug=(value)
+        @debug = value
+        if value
+          target_prose = (is_logger?(value) ? 'Ruby logger' : 'STDOUT')
+          log "Logging to #{target_prose} and browser console"
+        end
+
+        send_config_to_browser(<<~JS)
+          CapybaraLockstep.debug = #{value.to_json}
+        JS
+
+        @debug
       end
 
       def enabled?
@@ -30,6 +41,20 @@ module Capybara
         @enabled = enabled
       end
 
+      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
+
       def disabled?
         !enabled?
       end
@@ -40,6 +65,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/helper.js

@@ -1,45 +1,85 @@
 window.CapybaraLockstep = (function() {
-  var count = 0
-  var idleCallbacks = []
+  // 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() {
     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) {
+    jobCount++
+    if (tag) {
+      logNegative('Started work: %s [%d jobs]', tag, jobCount)
+    }
+  }
+
+  function startWorkUntil(promise, tag) {
+    startWork(tag)
+    let taggedStopWork = stopWork.bind(this, tag)
+    promise.then(taggedStopWork, taggedStopWork)
   }
 
-  function stopWork() {
-    count--
+  function stopWork(tag) {
+    let tasksElapsed = 0
 
-    if (isIdle()) {
-      idleCallbacks.forEach(function(callback) {
-        callback('Finished waiting for JavaScript')
-      })
-      idleCallbacks = []
+    let check = function() {
+      if (tasksElapsed < waitTasks) {
+        tasksElapsed++
+        setTimeout(check)
+      } else {
+        stopWorkNow(tag)
+      }
+    }
+
+    check()
+  }
+
+  function stopWorkNow(tag) {
+    jobCount--
+
+    if (tag) {
+      logPositive('Finished work: %s [%d jobs]', tag, jobCount)
+    }
+
+    let idleCallback
+    while (isIdle() && (idleCallback = idleCallbacks.shift())) {
+      idleCallback('Finished waiting for browser')
     }
   }
 
@@ -48,29 +88,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,26 +136,17 @@ window.CapybaraLockstep = (function() {
     })
   }
 
-  function onInteraction() {
-    // 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 onInteraction(event) {
+    startWork()
+    // (1) 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.
+    // (2) For performance reasons we don't wait for `waitTasks` here.
+    //     Whatever was queued by an event handler should call us again, and then
+    //     we do wait for additional tasks.
+    Promise.resolve().then(stopWorkNow)
   }
 
-  function trackDynamicScripts() {
+  function trackRemoteElements() {
     if (!window.MutationObserver) {
       return
     }
@@ -116,40 +154,43 @@ 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(onAnyElementChanged)
+    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.
     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.
-      var oldAjax = jQuery.ajax
-      jQuery.ajax = function () {
-        var promise = oldAjax.apply(this, arguments)
+      //
+      // 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)
         startWorkUntil(promise)
         return promise
       }
     })
   }
 
-  var INITIALIZING_ATTRIBUTE = 'data-initializing'
+  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()
+      stopWorkNow()
       if (document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
-        startWork()
-        var observer = new MutationObserver(onInitializingAttributeChanged)
+        startWork('Page initialization')
+        let observer = new MutationObserver(onInitializingAttributeChanged)
         observer.observe(document.body, { attributes: true, attributeFilter: [INITIALIZING_ATTRIBUTE] })
       }
     })
@@ -157,36 +198,101 @@ window.CapybaraLockstep = (function() {
 
   function onInitializingAttributeChanged() {
     if (!document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
-      stopWork()
+      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')
+  function isRemoteScript(element) {
+    if (element.tagName === 'SCRIPT') {
+      let src = element.getAttribute('src')
+      let type = element.getAttribute('type')
 
-      return (src && (!type || /javascript/i.test(type)))
+      return src && (!type || /javascript/i.test(type))
     }
   }
 
-  function onRemoteScriptAdded(script) {
-    startWork()
-    // Chrome runs a remote <script> *before* the load event fires.
-    script.addEventListener('load', stopWork)
-    script.addEventListener('error', stopWork)
+  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 isRemoteInlineFrame(element) {
+    if (element.tagName === 'IFRAME') {
+      let src = element.getAttribute('src')
+      let localSrcPattern = /^data:/
+      let hasLocalSrc = src && localSrcPattern.test(src)
+      return (src && !hasLocalSrc)
+    }
+  }
+
+  function trackRemoteElement(element, condition, workTag) {
+    if (!condition(element)) {
+      return
+    }
+
+    let stopped = false
+
+    startWork(workTag)
+
+    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
@@ -201,8 +307,7 @@ window.CapybaraLockstep = (function() {
     trackFetch()
     trackXHR()
     trackInteraction()
-    trackHistory()
-    trackDynamicScripts()
+    trackRemoteElements()
     trackJQuery()
     trackHydration()
   }
@@ -217,11 +322,14 @@ window.CapybaraLockstep = (function() {
 
   return {
     track: track,
+    isBusy: isBusy,
+    isIdle: isIdle,
     startWork: startWork,
     stopWork: stopWork,
     synchronize: synchronize,
-    isIdle: isIdle,
-    isBusy: isBusy
+    reset: reset,
+    set debug(value) { debug = value },
+    set waitTasks(value) { waitTasks = value }
   }
 })()