capybara-lockstep 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86fa6ca6223224f8ac4b53c973cf961287964d11b129d8aa89b7b4dc81d4bba4
-  data.tar.gz: f250e201b8ef467fd46d1e30654d8e2c88366c23ad8cb314e1031cb44268dcd7
+  metadata.gz: 783200fa3cbde0166b11c213bb677250021185b7c9898a3fd95594dd8433b89a
+  data.tar.gz: 77efe617f3ce7f138da78e8b9db031b9a8f75f07d3afe8379ae903266a9fa389
 SHA512:
-  metadata.gz: 846816f82797d02dc81869e449afaf99c3fdfe89682d6584a56b3416cbb5942138a38ae457dfebcbb4fc7f20ed2673766a02287911b258445c5a9b800d613f9c
-  data.tar.gz: 30064e290e2caed298e5868b0f1cb9c1f5aa34444895fa8cefd4d283b0433528dd1ee7793526f0652fbc11511ed3e50e9a6eb999b00f6a898411480616422199
+  metadata.gz: 6ec80d343f193b6b5a166bae1bf5ab6be2e7ae2e3c82d903596e4c604985d96382cce5012df5abdb714da614d8741f062386d60a47a1a3340734c22e46814949
+  data.tar.gz: 02e870bc8b8377be23e0ec97086219c7fd75a098f6f4eeda953dac86b7eb3a957d93984fb26265e8322c21989daa28cf4713ee3dc1772cd652f493e7999b6b57

data/Gemfile.lock

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

data/README.md

@@ -192,13 +192,15 @@ 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
@@ -206,6 +208,16 @@ You should now see messages like this during your test runs:
 [capybara-lockstep] Synchronized successfully
 ```
 
+You should also see messages like this in your browser's JavaScript console:
+
+```
+[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
@@ -215,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
@@ -226,9 +240,11 @@ ensure
 end
 ```
 
-## Timeout
+## Synchronization 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:
 
@@ -236,69 +252,58 @@ You can configure a different timeout:
 Capybara::Lockstep.timeout = 5 # seconds
 ```
 
-## Ruby API
+To revert to defaulting to `Capybara.default_max_wait_time`, set the timeout to `nil`:
 
-capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
+```ruby
+Capybara::Lockstep.timeout = nil
+```
 
-For additional edge cases you may interact with capybara-lockstep from your Ruby code.
 
+## Manual synchronization
 
-### Waiting until the browser is idle
+capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
 
-This will block until the document was loaded, the DOM has been hydrated and all AJAX requests have concluded:
+For additional edge cases you may manually tell capybara-lockstep to wait. The following Ruby method will block until the browser is idle:
 
 ```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
-
-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**.
-
-For additional edge cases you may interact with capybara-lockstep from your own JavaScripts.
-
-Note that when you only load the JavaScript snippet in tests you need check before calling any API functions:
+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
+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:
 
-You can query capybara-lockstep whether it considers the browser to be busy or idle:
-
-```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.
 
-This will run the given callback once the browser is considered to be idle:
 
-```js
-CapybaraLockstep.synchronize(callback)
+## Note on interacting with the JavaScript API
+
+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.
+
+```
+if (window.CapybaraLockstep) {
+  // interact with CapybaraLockstep
+}
 ```
 
 ## Development

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?

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,28 +14,48 @@ 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 startWorkUntil(promise, tag) {
+    startWork(tag)
+    promise.then(stopWork, stopWork)
+  }
+
+  function startWorkForMicrotask(tag) {
+    startWork(tag)
+    Promise.resolve().then(stopWork.bind(this, tag))
   }
 
-  function stopWork() {
+  function stopWork(tag) {
     count--
 
+    if (tag) {
+      logPositive('Finished work: %s [%d jobs]', tag, count)
+    }
+
     if (isIdle()) {
       idleCallbacks.forEach(function(callback) {
         callback('Finished waiting for JavaScript')
@@ -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,7 +117,7 @@ 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()
@@ -103,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(onAnyElementChanged)
+    let observer = new MutationObserver(onAnyElementChanged)
     observer.observe(document, { subtree: true, childList: true })
   }
 
@@ -117,16 +145,16 @@ 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
       }
     })
   }
 
-  var INITIALIZING_ATTRIBUTE = 'data-initializing'
+  let INITIALIZING_ATTRIBUTE = 'data-initializing'
 
   function trackHydration() {
     // Until we have a body on which we can observe [data-initializing]
@@ -135,8 +163,8 @@ window.CapybaraLockstep = (function() {
     whenReady(function() {
       stopWork()
       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] })
       }
     })
@@ -144,24 +172,26 @@ 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')
+      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 onAnyElementChanged(changes) {
@@ -206,8 +236,9 @@ window.CapybaraLockstep = (function() {
     startWork: startWork,
     stopWork: stopWork,
     synchronize: synchronize,
-    isIdle: isIdle,
-    isBusy: isBusy
+    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

@@ -71,6 +71,10 @@ module Capybara
               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.

data/lib/capybara-lockstep/logging.rb

@@ -4,7 +4,7 @@ module Capybara
       def log(message)
         if debug? && message.present?
           message = "[capybara-lockstep] #{message}"
-          if @debug.respond_to?(:debug)
+          if is_logger?(@debug)
             # If someone set Capybara::Lockstep to a logger, use that
             @debug.debug(message)
           else
@@ -13,6 +13,12 @@ module Capybara
           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.3.3"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Henning Koch