capybara-lockstep 0.3.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86fa6ca6223224f8ac4b53c973cf961287964d11b129d8aa89b7b4dc81d4bba4
-  data.tar.gz: f250e201b8ef467fd46d1e30654d8e2c88366c23ad8cb314e1031cb44268dcd7
+  metadata.gz: 86f6aba93856539de9e2df301e720cced0c444de2d62436e72ea620765f9b3e1
+  data.tar.gz: 1ae5dc301b4761d7c51796313ea4a6210596b5975e02f639410916ddc53060b5
 SHA512:
-  metadata.gz: 846816f82797d02dc81869e449afaf99c3fdfe89682d6584a56b3416cbb5942138a38ae457dfebcbb4fc7f20ed2673766a02287911b258445c5a9b800d613f9c
-  data.tar.gz: 30064e290e2caed298e5868b0f1cb9c1f5aa34444895fa8cefd4d283b0433528dd1ee7793526f0652fbc11511ed3e50e9a6eb999b00f6a898411480616422199
+  metadata.gz: b1dc1f1e4a8af3d4d02f4d7b2aec3ae99844ba42bd3713028a138842bdc296c6bc0ed39688b8c15d7976830cc97df9ebc96cee3f3cfc9ab5f799e99ec59fee23
+  data.tar.gz: 50e27f5304cc7fbc1ed0c74ee87311ef8c8a333ecd4395af7cf155305ce0607f4b0f20defdf901d8f5cb3cbe8fc1ddb23638d9587c27f15e2071aea59c24297c

data/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+---
+name: Tests
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+  workflow_dispatch:
+    branches:
+    - master  
+jobs:
+  test:
+    runs-on: ubuntu-20.04
+    timeout-minutes: 3
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - ruby: 2.6.6
+          gemfile: Gemfile
+        - ruby: 2.7.2
+          gemfile: Gemfile
+        - ruby: 3.0.1
+          gemfile: Gemfile
+    env:
+      BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "${{ matrix.ruby }}"
+    - name: Bundle
+      run: |
+        gem install bundler:2.2.15
+        bundle install --no-deployment
+    - name: Run tests
+      uses: nick-invision/retry@v2
+      with:
+        timeout_seconds: 30
+        max_attempts: 3
+        command: bundle exec rake spec

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+.idea
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+
+## Unreleased
+
+### Breaking changes
+
+- 
+
+### Compatible changes
+
+-
+
+## 0.7.0 - 2021-05-04
+
+### Compatible changes
+
+- add changelog
+- add gemika for tests with github actions
+- add Ruby 3 support
+
+## 0.6.0 - 2021-03-10
+## 0.5.0 - 2021-03-09
+## 0.4.0 - 2021-03-05
+## 0.3.3 - 2021-03-05
+## 0.3.2 - 2021-03-04 
+## 0.3.1 - 2021-03-04
+## 0.3.0 - 2021-03-04
+## 0.2.3 - 2021-03-03
+## 0.2.2 - 2021-03-03
+## 0.2.1 - 2021-03-03 

data/Gemfile

@@ -8,5 +8,9 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
+gem 'jasmine'
+gem 'thin' # ruby 3 does not include a webserver
+gem 'chrome_remote'
 
 gem 'byebug'
+gem 'gemika'

data/Gemfile.lock

@@ -1,15 +1,16 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (0.3.3)
+    capybara-lockstep (1.0.0)
       activesupport (>= 3.2)
       capybara (>= 2.0)
+      ruby2_keywords
       selenium-webdriver (>= 3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.3)
+    activesupport (6.1.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -27,16 +28,26 @@ GEM
       regexp_parser (>= 1.5, < 3.0)
       xpath (~> 3.2)
     childprocess (3.0.0)
+    chrome_remote (0.3.0)
+      websocket-driver (~> 0.6)
     concurrent-ruby (1.1.8)
+    daemons (1.3.1)
     diff-lcs (1.3)
-    i18n (1.8.9)
+    eventmachine (1.2.7)
+    gemika (0.6.0)
+    i18n (1.8.10)
       concurrent-ruby (~> 1.0)
-    mini_mime (1.0.2)
-    mini_portile2 (2.5.0)
+    jasmine (3.6.0)
+      jasmine-core (~> 3.6.0)
+      phantomjs
+      rack (>= 1.2.1)
+      rake
+    jasmine-core (3.6.0)
+    mini_mime (1.1.0)
     minitest (5.14.4)
-    nokogiri (1.11.1)
-      mini_portile2 (~> 2.5.0)
+    nokogiri (1.11.3-x86_64-linux)
       racc (~> 1.4)
+    phantomjs (2.1.1.0)
     public_suffix (4.0.6)
     racc (1.5.2)
     rack (2.2.3)
@@ -57,12 +68,20 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.0)
+    ruby2_keywords (0.0.4)
     rubyzip (2.3.0)
     selenium-webdriver (3.142.7)
       childprocess (>= 0.5, < 4.0)
       rubyzip (>= 1.2.2)
+    thin (1.8.0)
+      daemons (~> 1.0, >= 1.0.9)
+      eventmachine (~> 1.0, >= 1.0.4)
+      rack (>= 1, < 3)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
+    websocket-driver (0.7.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
     zeitwerk (2.4.2)
@@ -73,8 +92,12 @@ PLATFORMS
 DEPENDENCIES
   byebug
   capybara-lockstep!
+  chrome_remote
+  gemika
+  jasmine
   rake (~> 13.0)
   rspec (~> 3.0)
+  thin
 
 BUNDLED WITH
-   2.2.12
+   2.2.15

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,41 @@ 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')
+    }
   })
 })
 ```
 
-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 +168,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
@@ -192,13 +209,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,29 +225,35 @@ 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
 Capybara::Lockstep.debug = Rails.logger
 ```
 
+### Logging in the browser only
 
-## Disabling synchronization
-
-If for some reason you want to disable browser synchronization for a while, you can do it like this:
+To enable logging in the browser console (but not STDOUT), include the snippet with `{ debug: true }`:
 
-```ruby
-begin
-  Capybara::Lockstep.enabled = false
-  do_unsynchronized_work
-ensure
-  Capybara::Lockstep.enabled = true
-end
 ```
+capybara_lockstep(debug: true)
+```
+
+## Synchronization timeout
 
-## 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,71 +261,109 @@ 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)
 ```
 
-## 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**.
+## Disabling synchronization
 
-For additional edge cases you may interact with capybara-lockstep from your own JavaScripts.
+Sometimes you want to disable browser synchronization, e.g. to observe a loading spinner during a long-running request.
 
-Note that when you only load the JavaScript snippet in tests you need check before calling any API functions:
+To disable automatic synchronization:
 
-```js
-if (window.CapybaraLockstep) {
-  CapybaraLockstep.startWork()
-}
+```ruby
+begin
+  Capybara::Lockstep.mode = :manual
+  do_unsynchronized_work
+ensure
+  Capybara::Lockstep.mode = :auto
+end
+```
+
+Note that you may still force synchronization by calling `Capybara::Lockstep.synchronize` manually.
+
+To completely disable synchronization:
+
+```ruby
+Capybara::Lockstep.mode = :off
+Capybara::Lockstep.synchronize # will not synchronize
 ```
 
-### 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). 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]
+```
+
+You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
 
-You can query capybara-lockstep whether it considers the browser to be busy or idle:
+
+## 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.
 
 ```js
-CapybaraLockstep.isBusy() // => false
-CapybaraLockstep.isIdle() // => true
+if (window.CapybaraLockstep) {
+  // interact with CapybaraLockstep
+}
 ```
 
-### Waiting until the browser is idle
+## Handling legacy promises
+
+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 will run the given callback once the browser is considered to be idle:
+This means there is a time window in which all AJAX requests have finished, but their callbacks have not yet run:
 
 ```js
-CapybaraLockstep.synchronize(callback)
+$.ajax('/foo').then(function() {
+  // This callback runs one task after the response was received
+})
 ```
 
+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
+Capybara:Lockstep.wait_tasks = 1
+```
+
+If you see longer `then()` chains in your code, you may need to configure a higher number of tasks to wait.
+
+This will have a negative performance impact on your test suite.
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

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

data/capybara-lockstep.gemspec

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

data/lib/capybara-lockstep/capybara_ext.rb

@@ -1,7 +1,9 @@
+require 'ruby2_keywords'
+
 module Capybara
   module Lockstep
     module VisitWithWaiting
-      def visit(*args, &block)
+      ruby2_keywords def visit(*args, &block)
         url = args[0]
         # Some of our apps have a Cucumber step that changes drivers mid-scenario.
         # It works by creating a new Capybara session and re-visits the URL from the
@@ -12,13 +14,18 @@ module Capybara
 
         if visiting_remote_url
           # We're about to leave this screen, killing all in-flight requests.
-          Capybara::Lockstep.synchronize
+          # Give pending form submissions etc. a chance to finish before we tear down
+          # the browser environment.
+          #
+          # We force a non-lazy synchronization so we pick up all client-side changes
+          # that have not been caused by Capybara commands.
+          Lockstep.synchronize(lazy: false)
         end
 
         super(*args, &block).tap do
           if visiting_remote_url
-            # puts "After visit: unsynchronizing"
-            Capybara::Lockstep.synchronized = false
+            # We haven't yet synchronized the new screen.
+            Lockstep.synchronized = false
           end
         end
       end
@@ -26,11 +33,57 @@ module Capybara
   end
 end
 
-
 Capybara::Session.class_eval do
   prepend Capybara::Lockstep::VisitWithWaiting
 end
 
+module Capybara
+  module Lockstep
+    module SynchronizeAroundScriptMethod
+
+      def synchronize_around_script_method(meth)
+        mod = Module.new do
+          define_method meth do |script, *args, &block|
+            # Synchronization uses execute_script itself, so don't synchronize when
+            # we're already synchronizing.
+            if !Lockstep.synchronizing?
+              # It's generally a good idea to synchronize before a JavaScript wants
+              # to access or observe an earlier state change.
+              #
+              # In case the given script navigates away (with `location.href = url`,
+              # `history.back()`, etc.) we would kill all in-flight requests. For this case
+              # we force a non-lazy synchronization so we pick up all client-side changes
+              # that have not been caused by Capybara commands.
+              script_may_navigate_away = script =~ /\b(location|history)\b/
+              Lockstep.auto_synchronize(lazy: !script_may_navigate_away, log: "Synchronizing before script: #{script}")
+            end
+
+            super(script, *args, &block).tap do
+              if !Lockstep.synchronizing?
+                # We haven't yet synchronized with whatever changes the JavaScript
+                # did on the frontend.
+                Lockstep.synchronized = false
+              end
+            end
+          end
+          ruby2_keywords meth
+        end
+        prepend(mod)
+      end
+
+    end
+  end
+end
+
+Capybara::Session.class_eval do
+  extend Capybara::Lockstep::SynchronizeAroundScriptMethod
+
+  synchronize_around_script_method :execute_script
+  synchronize_around_script_method :evaluate_async_script
+  # Don't synchronize around evaluate_script. It calls execute_script
+  # internally and we don't want to synchronize multiple times.
+end
+
 module Capybara
   module Lockstep
     module UnsychronizeAfter
@@ -38,9 +91,10 @@ module Capybara
         mod = Module.new do
           define_method meth do |*args, &block|
             super(*args, &block).tap do
-              Capybara::Lockstep.synchronized = false
+              Lockstep.synchronized = false
             end
           end
+          ruby2_keywords meth
         end
         prepend(mod)
       end
@@ -87,10 +141,11 @@ end
 module Capybara
   module Lockstep
     module SynchronizeWithCatchUp
-      def synchronize(*args, &block)
-        # This method is called very frequently by capybara.
+      ruby2_keywords def synchronize(*args, &block)
+        # This method is called by Capybara before most interactions with
+        # the browser. It is a different method than Capybara::Lockstep.synchronize!
         # We use the { lazy } option to only synchronize when we're out of sync.
-        Capybara::Lockstep.synchronize(lazy: true)
+        Capybara::Lockstep.auto_synchronize(lazy: true)
 
         super(*args, &block)
       end

data/lib/capybara-lockstep/configuration.rb

@@ -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,27 +11,62 @@ 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?
+      def mode
         if javascript_driver?
-          @enabled.nil? ? true : @enabled
+          @mode.nil? ? :auto : @mode
         else
-          false
+          :off
         end
       end
 
+      def mode=(mode)
+        @mode = mode
+      end
+
       def enabled=(enabled)
-        @enabled = enabled
+        case enabled
+        when true
+          log "Setting `Capybara::Lockstep.enabled = true` is deprecated. Set `Capybara::Lockstep.mode = :auto` instead."
+          self.mode = :auto
+        when false
+          log "Setting `Capybara::Lockstep.enabled = false` is deprecated. Set `Capybara::Lockstep.mode = :manual` or `Capybara::Lockstep.mode = :off` instead."
+          self.mode = :manual
+        when nil
+          # Reset to default
+          self.mode = nil
+        end
       end
 
-      def disabled?
-        !enabled?
+      def wait_tasks
+        @wait_tasks
+      end
+
+      def wait_tasks=(value)
+        @wait_tasks = value
+
+        send_config_to_browser(<<~JS)
+          CapybaraLockstep.waitTasks = #{value.to_json}
+        JS
+
+        @wait_tasks
       end
 
       private
@@ -40,6 +75,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 stopWork() {
-    count--
+  function startWorkUntil(promise, tag) {
+    startWork(tag)
+    let taggedStopWork = stopWork.bind(this, tag)
+    promise.then(taggedStopWork, taggedStopWork)
+  }
 
-    if (isIdle()) {
-      idleCallbacks.forEach(function(callback) {
-        callback('Finished waiting for JavaScript')
-      })
-      idleCallbacks = []
+  function stopWork(tag) {
+    let tasksElapsed = 0
+
+    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,13 +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 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
     }
@@ -103,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] })
       }
     })
@@ -144,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
@@ -188,7 +307,7 @@ window.CapybaraLockstep = (function() {
     trackFetch()
     trackXHR()
     trackInteraction()
-    trackDynamicScripts()
+    trackRemoteElements()
     trackJQuery()
     trackHydration()
   }
@@ -203,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 }
   }
 })()
 

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

@@ -23,14 +23,26 @@ module Capybara
         page.instance_variable_set(:@lockstep_synchronized, value)
       end
 
-      def synchronize(lazy: false)
-        if (lazy && synchronized?) || synchronizing? || disabled?
+      def synchronize(lazy: false, log: nil)
+        if (lazy && synchronized?) || synchronizing? || mode == :off
           return
         end
 
+        # Allow passing a log message that is only logged
+        # when we're actually synchronizing.
+        if log
+          self.log(log)
+        end
+
         synchronize_now
       end
 
+      def auto_synchronize(**options)
+        if mode == :auto
+          synchronize(**options)
+        end
+      end
+
       private
 
       def synchronize_now
@@ -39,6 +51,8 @@ module Capybara
 
         log 'Synchronizing'
 
+        start_time = current_seconds
+
         begin
           with_max_wait_time(timeout) do
             message_from_js = evaluate_async_script(<<~JS)
@@ -67,10 +81,16 @@ module Capybara
               log(message_from_js)
             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.
@@ -120,6 +140,10 @@ module Capybara
         # no-op
       end
 
+      def current_seconds
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
     end
 
   end

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 = "1.0.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-05 00:00:00.000000000 Z
+date: 2021-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: ruby2_keywords
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - henning.koch@makandra.de
@@ -59,9 +73,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/test.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt