RubyGems - capybara-lockstep - Versions diffs - 0.3.1 → 0.6.0 - Mend

capybara-lockstep 0.3.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml +4 -4
data/Gemfile +2 -0
data/Gemfile.lock +3 -1
data/README.md +111 -57
data/lib/capybara-lockstep/capybara_ext.rb +56 -5
data/lib/capybara-lockstep/configuration.rb +44 -4
data/lib/capybara-lockstep/helper.js +167 -72
data/lib/capybara-lockstep/helper.rb +16 -1
data/lib/capybara-lockstep/lockstep.rb +50 -14
data/lib/capybara-lockstep/logging.rb +8 -2
data/lib/capybara-lockstep/version.rb +1 -1
metadata +2 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4c87e5cabd504735dfc07b20021d109d65b74aed53ec173f390c07a2dc6086a
-  data.tar.gz: 2c8f7f1520282284f3b6eb93ddfa0d6109628ee36721c3ba90eba9f05fe565eb
+  metadata.gz: ef423eecbf9d793e932d66b056feee733835efa0387ec6740fecb2975585f95e
+  data.tar.gz: 55e8872d7b892567797ded6fb67ed17500bc3daf29e11fbf4fee45588cdab9f2
 SHA512:
-  metadata.gz: 0742d9204b35230452220c6cebd3020999f1531530c201180c31ccff3add24973764a232333de5585e3d1180b220535542e1e2c8a04b55b51c5bd388d6578f17
-  data.tar.gz: 93915d9472fe5af20a864de61dc765a0eea708a80cf69bed9d0ccde54c0310e0d0c7767b9bc4a39af1fd4d8270e2a8cd3eea0982e6a0a8a512d09a829ac1f291
+  metadata.gz: cd14f06c4b820e5e0dda482438d282e7a856c790ef0952f44c28a6f18dd9fb863323f782b8e21d9846ec9660fcf804ea257e5c05640482e777408e71ab820ccd
+  data.tar.gz: dc64900722119cc945b6b22113b63d13706d0cfb2ae39e0b8411c62aad0cbfc716ff84433189521f685219ee85f48554852df1204ce0fad1fed4e7f19b1d3cf0

data/Gemfile CHANGED Viewed

@@ -8,3 +8,5 @@ gemspec
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem 'byebug'

data/Gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (0.3.1)
+    capybara-lockstep (0.6.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)
@@ -70,6 +71,7 @@ PLATFORMS
   ruby
 DEPENDENCIES
+  byebug
   capybara-lockstep!
   rake (~> 13.0)
   rspec (~> 3.0)

data/README.md CHANGED Viewed

@@ -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
@@ -173,9 +191,9 @@ capybara-lockstep will automatically patch Capybara to wait for the browser afte
 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:
 ```text
-[Capybara::Lockstep] Synchronizing
-[Capybara::Lockstep] Finished waiting for JavaScript
-[Capybara::Lockstep] Synchronized successfully
+[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.
@@ -187,35 +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] Synchronizing
-[Capybara::Lockstep] Finished waiting for JavaScript
-[Capybara::Lockstep] Synchronized successfully
+[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
@@ -226,9 +266,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,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/capybara_ext.rb CHANGED Viewed

@@ -12,13 +12,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 +31,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.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
+        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,7 +89,7 @@ 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
         end

data/lib/capybara-lockstep/configuration.rb CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 browser')
     }
   }
@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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,18 +23,24 @@ 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'
+        start_time = current_seconds
         begin
           with_max_wait_time(timeout) do
             message_from_js = evaluate_async_script(<<~JS)
@@ -53,26 +65,46 @@ 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 successfully"
+              end_time = current_seconds
+              ms_elapsed = ((end_time.to_f - start_time) * 1000).round
+              log "Synchronized successfully [#{ms_elapsed} ms]"
               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
@@ -96,6 +128,10 @@ module Capybara
         # no-op
       end
+      def current_seconds
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
     end
   end

data/lib/capybara-lockstep/logging.rb CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "0.3.1"
+    VERSION = "0.6.0"
   end
 end

metadata CHANGED Viewed

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