capybara-lockstep 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e993a9ec82edc1bbea78694f16ae5b3e171255db9eb7e14064922b153d1838d
-  data.tar.gz: 1086e7149ca202b105fd0472c839451845079e05c777a0dba839483fe05c473b
+  metadata.gz: 29e90825f3d0526be3d7780f7a291eddb9094b271f53ea5dcd4331a4123cda01
+  data.tar.gz: 1985baa9704e28b4a0b8a38c53af53b133adc68db14b5ec1fc613cd2adc0f21c
 SHA512:
-  metadata.gz: e54e30ae12effa97dcdbd73d0f07b465b90270efc3ddd3ad83fcde7a4d305164ac0380f7ab3128a37870e78862483659eb01ff6bcdf8fade32cd52c3024d5c31
-  data.tar.gz: c067bf3f9e0be7d6a84668ee7412ea7d93d450f109e8018940e72392277bcc0f5d0ef92717a1692dee8e0443509bc9317a7b403620b6eb62bdb78539ac036098
+  metadata.gz: 761be246131d0fce67dd2fb4d3ac8c7bddb0775e477ebe02b7c36139dc7e6152c0dea579cd02343b2e7f5ba3dd85ce2127fc21b323e1216584e3ebd16867a145
+  data.tar.gz: c0c4ad6b8bb83bf6493276bc2388446a3f6ff07b6ae8c924189851e77e9f767a551ce85ba9f04c6ebe285c0904fe3eb44ed1761f704e0ebaee1a7a638c49e26e

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.3.0)
+    capybara-lockstep (0.5.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)
@@ -31,10 +32,8 @@ GEM
     i18n (1.8.9)
       concurrent-ruby (~> 1.0)
     mini_mime (1.0.2)
-    mini_portile2 (2.5.0)
     minitest (5.14.4)
-    nokogiri (1.11.1)
-      mini_portile2 (~> 2.5.0)
+    nokogiri (1.11.1-x86_64-linux)
       racc (~> 1.4)
     public_suffix (4.0.6)
     racc (1.5.2)
@@ -70,6 +69,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  byebug
   capybara-lockstep!
   rake (~> 13.0)
   rspec (~> 3.0)

data/README.md

@@ -38,17 +38,13 @@ How capybara-lockstep helps
 
 capybara-lockstep waits until the browser is idle before moving on to the next Capybara command. This greatly relieves the pressure on Capybara's retry logic.
 
-Whenever Capybara visits a new URL:
+Whenever Capybara visits a new URL or simulates a user interaction (clicking, typing, etc.):
 
 - capybara-lockstep waits for all document resources to load.
 - capybara-lockstep waits for client-side JavaScript to render or hydrate DOM elements.
 - capybara-lockstep waits for any AJAX requests.
 - capybara-lockstep waits for dynamically inserted `<script>`s to load (e.g. from [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or Analytics snippets).
-
-Whenever Capybara simulates a user interaction (clicking, typing, etc.):
-
-- capybara-lockstep waits for any AJAX requests.
-- capybara-lockstep waits for dynamically inserted `<script>`s to load (e.g. from [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or Analytics snippets).
+- capybara-lockstep waits for dynamically `<img>` or `<iframe>` elements to load.
 
 
 Installation
@@ -102,9 +98,9 @@ If you're not using Rails you can `include Capybara::Lockstep::Helper` and acces
 
 ### Signaling the end of page initialization
 
-Most web applications run some JavaScript after the document was loaded. This JavaScript enhances existing DOM elements ("hydration") or renders additional element into the DOM.
+Most web applications run some JavaScript after a document has initially loaded. Such JavaScript usually enhances existing DOM elements ("hydration") or renders additional element into the DOM.
 
-capybara-lockstep needs to know when your JavaScript is done hydrating and rendering, so it can automatically wait for initialization after every Capybara `visit()`.
+capybara-lockstep will synchronize more reliably if you signal when your JavaScript is done rendering the initial document. After the initial rendering, capybara-lockstep will automatically detect when the browser is busy, even if content is changed dynamically later.
 
 To signal that JavaScript is still initializing, your application layouts should render the `<body>` element with an `[data-initializing]` attribute:
 
@@ -112,10 +108,14 @@ To signal that JavaScript is still initializing, your application layouts should
 <body data-initializing>
 ```
 
-Your application JavaScript should remove the `[data-initializing]` attribute when it is done hydrating and rendering.
+Your application JavaScript should remove the `[data-initializing]` attribute when it is done rendering the initial page.
 
 More precisely, the attribute should be removed in the same [JavaScript task](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/) ("tick") that will finish initializing. capybara-lockstep will assume that the page will be initialized by the end of this task.
 
+**After the initial rendering, capybara-lockstep will automatically detect when the browser is busy, even if content is changed dynamically later. After the initial page load you no longer need to add or remove the `[data-initializing]` attribute.**
+
+#### Example: Vanilla JS
+
 If all your initializing JavaScript runs synchronously on `DOMContentLoaded`, you can remove `[data-initializing]` in an event handler:
 
 ```js
@@ -125,26 +125,42 @@ document.addEventListener('DOMContentLoaded', function() {
 })
 ```
 
-If you do any asynchronous initialization work (like lazy-loading another script) you should only remove `[data-initializing]` once that is done:
+If you call libraries during initialization, you may need to check the library code to see whether it finishes synchronously or asynchronously. Ideally a library offers a callback to notify you when it is done rendering:
 
 ```js
 document.addEventListener('DOMContentLoaded', function() {
-  import('huge-library').then(function({ hugeLibrary }) {
-    hugeLibrary.initialize()
-    document.body.removeAttribute('data-initializing')
+  Libary.initialize({
+    onFinished: function() {
+      document.body.removeAttribute('data-initializing')
+    })
   })
+  setTimeout(function() { document.body.removeAttribute('data-initializing') })
 })
 ```
 
-If you call libraries during initialization, you may need to check the library code to see whether it finishes synchronously or asynchronously. E.g. if you discover that a library delays work for a task, you must also wait another task to remove `[data-initializing]`:
+When a library offers no such callback, but you see in its code that the library delays work for a task, you must also wait another task to remove `[data-initializing]`:
 
 ```js
 document.addEventListener('DOMContentLoaded', function() {
-  Libary.doWorkInNextTask()
+  Libary.initialize()
   setTimeout(function() { document.body.removeAttribute('data-initializing') })
 })
 ```
 
+If your initialization code lazy-loads another script, you should only remove `[data-initializing]` once that is done:
+
+```js
+document.addEventListener('DOMContentLoaded', function() {
+  import('huge-library').then(function({ HugeLibrary }) {
+    HugeLibrary.initialize()
+    document.body.removeAttribute('data-initializing')
+  })
+})
+```
+
+
+#### Example: Unpoly
+
 When you're using [Unpoly](https://unpoly.com/) initializing will usually happen synchronously in [compilers](https://unpoly.com/up.compiler). Hence a compiler is a good place to remove `[data-initializing]`:
 
 ```js
@@ -153,6 +169,8 @@ up.compiler('body', function(body) {
 })
 ```
 
+#### Example: AngularJS 1
+
 When you're using [AngularJS 1](https://unpoly.com/) initializing will usually happen synchronously in [directives](https://docs.angularjs.org/guide/directive). Hence a directive is a good place to remove `[data-initializing]`:
 
 ```js
@@ -170,9 +188,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,33 +205,57 @@ 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] JavaScript or AJAX requests are running
+[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] 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
 Capybara::Lockstep.debug = Rails.logger
 ```
 
+### Logging in the browser only
+
+To enable logging in the browser console (but not STDOUT), include the snippet with `{ debug: true }`:
+
+```
+capybara_lockstep(debug: true)
+```
+
 
 ## 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,9 +266,11 @@ ensure
 end
 ```
 
-## Timeout
+## Synchronization timeout
 
-By default capybara-lockstep will wait up to 10 seconds for the page initialize and for JavaScript and AJAX request to finish.
+By default capybara-lockstep will wait `Capybara.default_max_wait_time` 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:
 
@@ -230,70 +278,82 @@ 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:
+You may also synchronize from your client-side JavaScript. The following will run the given callback once the browser is idle:
 
-```gherkin
-When 'I wait for the page to load' do
-  Capybara::Lockstep.synchronize
-end
+```js
+CapybaraLockstep.synchronize(callback)
+```
+
+## 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('Eject warp core')
+doAsynchronousWork().then(function() {
+  CapybaraLockstep.stopWork('Eject warp core')
+})
+```
+
+The string argument is used for logging (when logging is enabled). It does **not** need to be unique per job. In this case you should see messages like this in your browser's JavaScript console:
+
+```text
+[capybara-lockstep] Started work: Eject warp core [1 jobs]
+[capybara-lockstep] Finished work: Eject warp core [0 jobs]
 ```
 
-## JavaScript API
+You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
 
-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 on interacting with the JavaScript API
 
-Note that when you only load the JavaScript snippet in tests you need check before calling any API functions:
+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.
 
 ```js
 if (window.CapybaraLockstep) {
-  CapybaraLockstep.startWork()
+  // interact with CapybaraLockstep
 }
 ```
 
-### Signaling asynchronous work
+## Handling legacy promises
 
-If for some reason you want capybara-lockstep to consider additional asynchronous work as "busy", you can do so:
+Legacy promise implementations (like jQuery's `$.Deferred` and AngularJS' `$q`) work using tasks instead of microtasks. Their AJAX implementations (like `$.ajax()` and `$http`) use these promises to signal that a request is done.
+
+This means there is a time window in which all AJAX requests have finished, but their callbacks have not yet run:
 
 ```js
-CapybaraLockstep.startWork()
-doAsynchronousWork().then(function() {
-  CapybaraLockstep.stopWork()
+$.ajax('/foo').then(function() {
+  // This callback runs one task after the response was received
 })
 ```
 
-### Checking if the browser is busy
-
-You can query capybara-lockstep whether it considers the browser to be busy or idle:
+It is theoretically possible that your test will observe the browser in that window, and expect content that has not been rendered yet. This will usually be mitigated by Capybara's retry logic. **If** you think that this is an issue for your test suite, you can configure capybara-headless to wait additional tasks before it considers the browser to be idle:
 
 ```js
-CapybaraLockstep.isBusy() // => false
-CapybaraLockstep.isIdle() // => true
+Capybara:Lockstep.wait_tasks = 1
 ```
 
-### Waiting until the browser is idle
+If you see longer `then()` chains in your code, you may need to configure a higher number of tasks to wait.
 
-This will run the given callback once the browser is considered to be idle:
+This will have a negative performance impact on your test suite.
 
-```js
-CapybaraLockstep.synchronize(callback)
-```
 
 ## 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,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,75 @@
 window.CapybaraLockstep = (function() {
-  var count = 0
-  var idleCallbacks = []
+  let jobCount = 0
+  let idleCallbacks = []
+  let debug = false
+  let waitTasks = 0
 
   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)
+    promise.then(stopWork, stopWork)
   }
 
-  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 JavaScript')
     }
   }
 
@@ -48,29 +78,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 +126,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 +144,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 +188,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 +297,7 @@ window.CapybaraLockstep = (function() {
     trackFetch()
     trackXHR()
     trackInteraction()
-    trackHistory()
-    trackDynamicScripts()
+    trackRemoteElements()
     trackJQuery()
     trackHydration()
   }
@@ -220,8 +315,8 @@ window.CapybaraLockstep = (function() {
     startWork: startWork,
     stopWork: stopWork,
     synchronize: synchronize,
-    isIdle: isIdle,
-    isBusy: isBusy
+    set debug(value) { debug = value },
+    set waitTasks(value) { waitTasks = value }
   }
 })()
 

data/lib/capybara-lockstep/helper.rb

@@ -17,7 +17,22 @@ module Capybara
           tag_options[:nonce] = options.fetch(:nonce, true)
         end
 
-        javascript_tag(capybara_lockstep_js, tag_options)
+        js = capybara_lockstep_js + capybara_lockstep_config_js(options)
+        javascript_tag(js, tag_options)
+      end
+
+      def capybara_lockstep_config_js(options = {})
+        js = ''
+
+        if (debug = options.fetch(:debug, Lockstep.debug?))
+          js += "\nCapybaraLockstep.debug = #{debug.to_json}"
+        end
+
+        if (wait_tasks = options.fetch(:wait_tasks, Lockstep.wait_tasks))
+          js += "\nCapybaraLockstep.waitTasks = #{wait_tasks.to_json}"
+        end
+
+        js
       end
 
     end

data/lib/capybara-lockstep/lockstep.rb

@@ -1,10 +1,16 @@
 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 Configuration
       include Logging
 
-      attr_accessor :synchronized
+      attr_accessor :synchronizing
+      alias synchronizing? synchronizing
 
       def synchronized?
         value = page.instance_variable_get(:@lockstep_synchronized)
@@ -17,15 +23,19 @@ module Capybara
         page.instance_variable_set(:@lockstep_synchronized, value)
       end
 
-      ERROR_SNIPPET_MISSING = 'Cannot synchronize: Capybara::Lockstep JavaScript snippet is missing on page'
-      ERROR_PAGE_MISSING = 'Cannot synchronize before initial Capybara visit'
-
       def synchronize(lazy: false)
-        if (lazy && synchronized?) || @synchronizing || disabled?
+        if (lazy && synchronized?) || synchronizing? || disabled?
           return
         end
 
-        @synchronizing = true
+        synchronize_now
+      end
+
+      private
+
+      def synchronize_now
+        self.synchronizing = true
+        self.synchronized = false
 
         log 'Synchronizing'
 
@@ -53,26 +63,44 @@ module Capybara
             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"
+              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
-          log "#{e.class.name} while synchronizing: #{e.message}"
-          @synchronized = false
-          raise e
+          unhandled_synchronize_error(e)
         ensure
-          @synchronizing = false
+          self.synchronizing = false
         end
       end
 
-      private
+      def unhandled_synchronize_error(e)
+        log "#{e.class.name} while synchronizing: #{e.message}"
+        raise e
+      end
 
       def page
         Capybara.current_session

data/lib/capybara-lockstep/logging.rb

@@ -3,8 +3,8 @@ module Capybara
     module Logging
       def log(message)
         if debug? && message.present?
-          message = "[Capybara::Lockstep] #{message}"
-          if @debug.respond_to?(:debug)
+          message = "[capybara-lockstep] #{message}"
+          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.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-04 00:00:00.000000000 Z
+date: 2021-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara