capybara-lockstep 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cccdbf8f6eb6582b123a366febeb67f863ac3801cf91f42f7a48f685e96d1860
+  data.tar.gz: a3683b8f821c8dd706eff573fb9c0e5aa730a29dd9205d2441a3ab5a52d8f0b8
+SHA512:
+  metadata.gz: e9fc97b54f2b797809c85d45d87b1d34a687ae18617bbf17bdad57d060da96eb876283610e5442cebf876ba520333e501ca635bd48436870359e0b806cfeabc0
+  data.tar.gz: 157ae6e39f58f9437f0121fc3836d2bf3ac0c767b3dff2ff59f5f9b04516fdf4586df04ecc0bbd9c021615551878735edb910fdb393b005cfda59f906832b2f2

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.7.2

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in capybara-lockstep.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,75 @@
+PATH
+  remote: .
+  specs:
+    capybara-lockstep (0.2.1)
+      activesupport (>= 3.2)
+      capybara (>= 2.0)
+      selenium-webdriver (>= 3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.2.4.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    capybara (3.35.3)
+      addressable
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.8)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
+    childprocess (3.0.0)
+    concurrent-ruby (1.1.7)
+    diff-lcs (1.3)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    mini_mime (1.0.2)
+    minitest (5.14.1)
+    nokogiri (1.11.1-x86_64-linux)
+      racc (~> 1.4)
+    public_suffix (4.0.6)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rake (13.0.1)
+    regexp_parser (2.1.1)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.0)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.0)
+    rubyzip (1.3.0)
+    selenium-webdriver (3.142.7)
+      childprocess (>= 0.5, < 4.0)
+      rubyzip (>= 1.2.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  capybara-lockstep!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.2.12

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Henning Koch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,324 @@
+# capybara-lockstep
+
+This Ruby gem synchronizes [Capybara](https://github.com/teamcapybara/capybara) commands with client-side JavaScript and AJAX requests. This greatly improves the stability of a full-stack integration test suite, even if that suite has timing issues.
+
+
+Why are tests flaky?
+--------------------
+
+A naively written integration test will have [race conditions](https://makandracards.com/makandra/47336-fixing-flaky-integration-tests) between the test script and the controlled browser. How often these timing issues will fail your test depends on luck and your machine's performance. You may not see these issues for years until a colleague runs your suite on their new laptop.
+
+Here is a typical example for a test that will fail with unlucky timing:
+
+```ruby
+scenario 'User sends a tweet' do
+  visit '/'
+  click_link 'New tweet' # opens form in a modal dialog
+  fill_in 'text', with: 'My first tweet'
+  click_button 'Send tweet'
+  visit '/timeline'
+  expect(page).to have_css('.tweet', text: 'My first tweet')
+end
+```
+
+This test has four timing issues that may cause it to fail:
+
+1. We click on the "New tweet" button, but the the JS event handler to open the tweet form wasn't registered yet.
+2. We start filling in the form, but it wasn't loaded yet.
+3. After sending the tweet we immediately navigate away, killing the form submission request that is still in flight. Hence the tweet will never appear in the next step.
+4. We look for the new tweet, but the timeline wasn't loaded yet.
+
+Capybara will retry individual commands or expectations when they fail. However, only issues **2** and **4** can be healed by retrying.
+
+While it is [possible](https://makandracards.com/makandra/47336-fixing-flaky-integration-tests) to remove most of the timing issues above, it requires skill and discipline. capybara-lockstep fixes issues **1**, **2**, **3** and **4** without any changes to the test code.
+
+
+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:
+
+- 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).
+
+
+Installation
+------------
+
+### Prerequisites
+
+Check if your application satisfies all requirements for capybara-lockstep:
+
+- Capybara 2 or higher.
+- Your Capybara driver must use [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver/). capybara-headless deactivates itself for any other driver.
+- This gem was only tested with a Selenium-controlled Chrome browser. [Chrome in headless mode](https://makandracards.com/makandra/492109-running-capybara-tests-in-headless-chrome) is recommended, but not required.
+- This gem was only tested with Rails, but there's no Rails dependency.
+
+
+### Installing the Ruby gem
+
+Assuming that you're using Rails Add this line to your application's `Gemfile`:
+
+```ruby
+group :test do
+  gem 'capybara-lockstep'
+end
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+If you're not using Rails you should also `require 'capybara-lockstep'` in your `spec_helper.rb` (RSpec) or `env.rb` (Cucumber).
+
+
+### Including the JavaScript snippet
+
+capybara-lockstep requires a JavaScript snippet to be embedded by the application under test. If that snippet is missing on a screen, capybara-lockstep will not be able to synchronize with the browser. In that case the test will continue without synchronization.
+
+If you're using Rails you can use the `capybara_lockstep` helper to insert the snippet into your application layouts:
+
+```erb
+<%= capybara_lockstep if Rails.env.test? %>
+```
+
+Ideally the snippet should be included in the `<head>` before any other `<script>` tags. If that's impractical you will also see some benefit if you insert it later.
+
+If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), the `capybara_lockstep` helper will insert a CSP nonce by default. You can also pass a `:nonce` option.
+
+If you're not using Rails you can `include Capybara::Lockstep::Helper` and access the JavaScript with `capybara_lockstep_script`.
+
+
+### 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.
+
+capybara-lockstep needs to know when your JavaScript is done hydrating and rendering, so it can automatically wait for initialization after every Capybara `visit()`.
+
+To signal that JavaScript is still initializing, your application layouts should render the `<body>` element with an `[data-initializing]` attribute:
+
+```html
+<body data-initializing>
+```
+
+Your application JavaScript should remove the `[data-initializing]` attribute when it is done hydrating and rendering.
+
+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.
+
+If all your initializing JavaScript runs synchronously on `DOMContentLoaded`, you can remove `[data-initializing]` in an event handler:
+
+```js
+document.addEventListener('DOMContentLoaded', function() {
+  // Initialize the page here
+  document.body.removeAttribute('data-initializing')
+})
+```
+
+If you do any asynchronous initialization work (like lazy-loading 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')
+  })
+})
+```
+
+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]`:
+
+```js
+document.addEventListener('DOMContentLoaded', function() {
+  Libary.doWorkInNextTask()
+  setTimeout(function() { document.body.removeAttribute('data-initializing') })
+})
+```
+
+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
+up.compiler('body', function(body) {
+  body.removeAttribute('data-initializing')
+})
+```
+
+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
+app.directive('body', function() {
+  return {
+    restrict: 'E',
+    link: function() {
+      document.body.removeAttribute('data-initializing')
+    }
+  }
+})
+```
+
+### Verify successful integration
+
+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.
+
+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).
+
+Note that you may see some failures from tests with wrong assertions, which sometimes passed due to lucky timing.
+
+
+## Performance impact
+
+capybara-lockstep may or may not impact the runtime of your test suite. It depends on your particular tests and how many flaky tests you're seeing in the first place.
+
+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%.
+
+
+## Debugging log
+
+capybara-lockstep can print to the console whenever it waits for the browser. To enable the log:
+
+```ruby
+Capybara::Lockstep.debug = true
+```
+
+You should now see messages like this during your test runs:
+
+```
+[Capybara::Lockstep] JavaScript or AJAX requests are running
+```
+
+You may also configure logging to an existing logger object:
+
+```ruby
+Capybara::Lockstep.debug = Rails.logger
+```
+
+
+## Disabling synchronization
+
+If for some reason you want to disable browser synchronization for a while, you can do it like this:
+
+```ruby
+begin
+  Capybara::Lockstep.enabled = false
+  do_unsynchronized_work
+ensure
+  Capybara::Lockstep.enabled = true
+end
+```
+
+
+## Timeout
+
+By default capybara-lockstep will wait up to 10 seconds for the page initialize and for JavaScript and AJAX request to finish.
+
+You can configure a different timeout:
+
+```ruby
+Capybara::Lockstep.timeout = 5 # seconds
+```
+
+
+
+
+## JavaScript API
+
+capybara-lockstep already hooks into [many JavaScript APIs](#how-capybara-lockstep-helps) like `XMLHttpRequest` or `fetch()` to mark the browser as "busy" until their work finishes. **This should be enough for most test suites**.
+
+For additional edge cases you may interact with capybara-lockstep from your own JavaScripts.
+
+Note that when you only load the JavaScript snippet in tests you need check before calling any API functions:
+
+```js
+if (window.CapybaraLockstep) {
+  CapybaraLockstep.startWork()
+}
+```
+
+### 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()
+doAsynchronousWork().then(function() {
+  CapybaraLockstep.stopWork()
+})
+```
+
+### Checking if the browser is busy
+
+You can query capybara-lockstep whether it considers the browser to be busy or idle:
+
+```js
+CapybaraLockstep.isBusy() // => false
+CapybaraLockstep.isIdle() // => true
+```
+
+### Waiting until the browser is idle
+
+```js
+CapybaraLockstep.awaitIdle(callback)
+```
+
+## Ruby API
+
+capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
+
+For additional edge cases you may interact with capybara-lockstep from your Ruby code.
+
+
+### Waiting until the browser is idle
+
+This will block until the document was loaded and the DOM has been hydrated:
+
+```ruby
+Capybara::Lockstep.await_initialized
+```
+
+This will block while the browser is busy with JavaScript and AJAX requests:
+
+```ruby
+Capybara::Lockstep.await_idle
+```
+
+### Checking if the browser is busy
+
+You can query capybara-lockstep whether it considers the browser to be busy or idle:
+
+```ruby
+Capybara::Lockstep.idle? # => true
+Capybara::Lockstep.busy? # => false
+```
+
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Pull requests are welcome on GitHub at <https://github.com/makandra/capistrano-lockstep>.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Henning Koch ([@triskweline](https://twitter.com/triskweline)) from [makandra](https://makandra.com).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "capybara-lockstep"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/capybara-lockstep.gemspec

@@ -0,0 +1,33 @@
+require_relative "lib/capybara-lockstep/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "capybara-lockstep"
+  spec.version       = Capybara::Lockstep::VERSION
+  spec.authors       = ["Henning Koch"]
+  spec.email         = ["henning.koch@makandra.de"]
+
+  spec.summary       = "Synchronize Capybara commands with client-side JavaScript and AJAX requests"
+  spec.homepage      = "https://rubygems.org/gems/capybara-lockstep"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "capybara", ">= 2.0"
+  spec.add_dependency "selenium-webdriver", ">= 3"
+  spec.add_dependency "activesupport", ">= 3.2"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/capybara-lockstep.rb

@@ -0,0 +1,17 @@
+require 'capybara'
+require 'selenium-webdriver'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/module/delegation'
+
+module Capybara
+  module Lockstep
+  end
+end
+
+require_relative 'capybara-lockstep/version'
+require_relative 'capybara-lockstep/errors'
+require_relative 'capybara-lockstep/patiently'
+require_relative 'capybara-lockstep/configuration'
+require_relative 'capybara-lockstep/lockstep'
+require_relative 'capybara-lockstep/capybara_ext'
+require_relative 'capybara-lockstep/helper'

data/lib/capybara-lockstep/capybara_ext.rb

@@ -0,0 +1,71 @@
+module Capybara
+  module Lockstep
+    module VisitWithWaiting
+      def visit(*args, **kwargs, &block)
+        super(*args, **kwargs, &block).tap do
+          # There is a step that changes drivers mid-scenario.
+          # It works by creating a new Capybara session and re-visits the
+          # URL from the previous session. If this happens before a URL is ever
+          # loaded, it re-visits the URL "data:", which will never "finish"
+          # initializing.
+          unless args[0].start_with?('data:')
+            Capybara::Lockstep.await_initialized
+          end
+        end
+      end
+    end
+
+    module AwaitIdle
+      def await_idle(meth)
+        mod = Module.new do
+          define_method meth do |*args, &block|
+            super(*args, &block).tap do
+              Capybara::Lockstep.await_idle
+            end
+          end
+        end
+        prepend(mod)
+      end
+    end
+  end
+end
+
+Capybara::Session.class_eval do
+  prepend Capybara::Lockstep::VisitWithWaiting
+end
+
+# Capybara 3 has driver-specific Node classes which sometimes
+# super to Capybara::Selenium::Node, but not always.
+node_classes = [
+  (Capybara::Selenium::ChromeNode  if defined?(Capybara::Selenium::ChromeNode)),
+  (Capybara::Selenium::FirefoxNode if defined?(Capybara::Selenium::FirefoxNode)),
+  (Capybara::Selenium::SafariNode  if defined?(Capybara::Selenium::SafariNode)),
+  (Capybara::Selenium::EdgeNode    if defined?(Capybara::Selenium::EdgeNode)),
+  (Capybara::Selenium::IENode      if defined?(Capybara::Selenium::IENode)),
+].compact
+
+if node_classes.empty?
+  # Capybara 2 has no driver-specific Node implementations,
+  # so we patch the shared base class.
+  node_classes = [Capybara::Selenium::Node]
+end
+
+node_classes.each do |node_class|
+  node_class.class_eval do
+    extend Capybara::Lockstep::AwaitIdle
+
+    await_idle :set
+    await_idle :select_option
+    await_idle :unselect_option
+    await_idle :click
+    await_idle :right_click
+    await_idle :double_click
+    await_idle :send_keys
+    await_idle :hover
+    await_idle :drag_to
+    await_idle :drop
+    await_idle :scroll_by
+    await_idle :scroll_to
+    await_idle :trigger
+  end
+end

data/lib/capybara-lockstep/configuration.rb

@@ -0,0 +1,41 @@
+module Capybara
+  module Lockstep
+    module Configuration
+
+      def timeout
+        @timeout || 10
+      end
+
+      def timeout=(seconds)
+        @timeout = seconds
+      end
+
+      def debug?
+        @debug.nil? ? false : @debug
+      end
+
+      def debug=(debug)
+        @debug = debug
+      end
+
+      def enabled?
+        if javascript_driver?
+          @enabled.nil? ? true : @enabled
+        else
+          false
+        end
+      end
+
+      def enabled=(enabled)
+        @enabled = enabled
+      end
+
+      private
+
+      def javascript_driver?
+        driver.is_a?(Capybara::Selenium::Driver)
+      end
+
+    end
+  end
+end

data/lib/capybara-lockstep/errors.rb

@@ -0,0 +1,6 @@
+module Capybara
+  module Lockstep
+    class Error < StandardError; end
+    class Busy < Error; end
+  end
+end

data/lib/capybara-lockstep/helper.js

@@ -0,0 +1,205 @@
+window.CapybaraLockstep = (function() {
+  var count = 0
+  var idleCallbacks = []
+
+  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
+  }
+
+  function isBusy() {
+    return !isIdle()
+  }
+
+  function startWork() {
+    count++
+  }
+
+  function startWorkUntil(promise) {
+    startWork()
+    promise.then(stopWork, stopWork)
+  }
+
+  function startWorkForTime(time) {
+    startWork()
+    setTimeout(stopWork, time)
+  }
+
+  function startWorkForMicrotask() {
+    startWork()
+    Promise.resolve().then(stopWork)
+  }
+
+  function stopWork() {
+    count--
+
+    if (isIdle()) {
+      idleCallbacks.forEach(function(callback) {
+        callback('JavaScript has finished')
+      })
+      idleCallbacks = []
+    }
+  }
+
+  function trackFetch() {
+    if (!window.fetch) {
+      return
+    }
+
+    var oldFetch = window.fetch
+    window.fetch = function() {
+      var promise = oldFetch.apply(this, arguments)
+      startWorkUntil(promise)
+      return promise
+    }
+  }
+
+  function trackXHR() {
+    var oldSend = XMLHttpRequest.prototype.send
+
+    XMLHttpRequest.prototype.send = function() {
+      startWork()
+
+      try {
+        this.addEventListener('readystatechange', function(event) {
+          if (this.readyState === 4) { stopWork() }
+        }.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()
+        throw e
+      }
+    }
+  }
+
+  function trackInteraction() {
+    // We already override all interaction methods in the Selenium browser nodes, so they
+    // wait for an idle frame afterwards. However a test script might also dispatch synthetic
+    // events with executate_script() to manipulate the browser in ways that are not possible
+    // with the Capybara API. When we observe such an event we wait until the end of the microtask,
+    // assuming any busy action will be queued by then.
+    ['click',  'mousedown', 'keydown', 'change', 'input', 'submit', 'focusin', 'focusout', 'scroll'].forEach(function(eventType) {
+      // Use { useCapture: true } so we get the event before another listener
+      // can prevent it from bubbling up to the document.
+      document.addEventListener(eventType, onInteraction, { capture: true, passive: true })
+    })
+  }
+
+  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 trackDynamicScripts() {
+    if (!window.MutationObserver) {
+      return
+    }
+
+    // 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(onMutated)
+    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) {
+        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)
+        startWorkUntil(promise)
+        return promise
+      }
+    })
+  }
+
+  function isRemoteScript(node) {
+    if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'SCRIPT') {
+      var src = node.getAttribute('src')
+      var type = node.getAttribute('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 onMutated(changes) {
+    changes.forEach(function(change) {
+      change.addedNodes.forEach(function(addedNode) {
+        if (isRemoteScript(addedNode)) {
+          onRemoteScriptAdded(addedNode)
+        }
+      })
+    })
+  }
+
+  function whenReady(callback) {
+    // Values are "loading", "interactive" and "completed".
+    // https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState
+    if (document.readyState != 'loading') {
+      callback()
+    } else {
+      document.addEventListener('DOMContentLoaded', callback)
+    }
+  }
+
+  function track() {
+    trackFetch()
+    trackXHR()
+    trackInteraction()
+    trackHistory()
+    trackDynamicScripts()
+    trackJQuery()
+  }
+
+  function awaitIdle(callback) {
+    if (isIdle()) {
+      callback()
+    } else {
+      idleCallbacks.push(callback)
+    }
+  }
+
+  return {
+    track: track,
+    startWork: startWork,
+    stopWork: stopWork,
+    awaitIdle: awaitIdle,
+    isIdle: isIdle,
+    isBusy: isBusy
+  }
+})()
+
+CapybaraLockstep.track()

data/lib/capybara-lockstep/helper.rb

@@ -0,0 +1,29 @@
+module Capybara
+  module Lockstep
+    module Helper
+
+      JS_PATH = File.expand_path('../helper.js', __FILE__)
+      JS = IO.read(JS_PATH)
+
+      def capybara_lockstep_js
+        JS
+      end
+
+      def capybara_lockstep(options = {})
+        tag_options = {}
+
+        # Add a CSRF nonce if supported by our Rails version
+        if Rails.version >= '5'
+          tag_options[:nonce] = options.fetch(:nonce, true)
+        end
+
+        javascript_tag(capybara_lockstep_js, tag_options)
+      end
+
+    end
+  end
+end
+
+if defined?(ActionView::Base)
+  ActionView::Base.send :include, Capybara::Lockstep::Helper
+end

data/lib/capybara-lockstep/lockstep.rb

@@ -0,0 +1,141 @@
+module Capybara
+  module Lockstep
+    class << self
+      include Patiently
+      include Configuration
+
+      def await_idle
+        return unless enabled?
+
+        ignoring_alerts do
+          # evaluate_async_script also times out after Capybara.default_max_wait_time
+          with_max_wait_time(timeout) do
+            message_from_js = evaluate_async_script(<<~JS)
+              let done = arguments[0]
+              if (window.CapybaraLockstep) {
+                CapybaraLockstep.awaitIdle(done)
+              } else {
+                done('Cannot synchronize: Capybara::Lockstep was not included in page')
+              }
+            JS
+            log(message_from_js)
+          end
+        end
+      end
+
+      def await_initialized
+        return unless enabled?
+
+        # We're retrying the initialize check every few ms.
+        # Don't clutter the log with dozens of identical messages.
+        last_logged_reason = nil
+
+        patiently(timeout) do
+          if (reason = initialize_reason)
+            if reason != last_logged_reason
+              log(reason)
+              last_logged_reason = reason
+            end
+
+            # Raise an exception that will be retried by `patiently`
+            raise Busy, reason
+          end
+        end
+      end
+
+      def idle?
+        unless enabled?
+          return true
+        end
+
+        result = execute_script(<<~JS)
+          if (window.CapybaraLockstep) {
+            return CapybaraLockstep.isIdle()
+          } else {
+            return 'Cannot check busy state: Capybara::Lockstep was not included in page'
+          }
+        JS
+
+        if result.is_a?(String)
+          log(result)
+          # When the snippet is missing we assume that the browser is idle.
+          # Otherwise we would wait forever.
+          true
+        else
+          result
+        end
+      end
+
+      def busy?
+        !idle?
+      end
+
+      private
+
+      def initialize_reason
+        ignoring_alerts do
+          execute_script(<<~JS)
+            if (location.href.indexOf('data:') == 0) {
+              return 'Requesting initial page'
+            }
+
+            if (document.readyState !== "complete") {
+              return 'Document is loading'
+            }
+
+            // The application layouts render a <body data-initializing>.
+            // The [data-initializing] attribute is removed by an Angular directive or Unpoly compiler (frontend).
+            // to signal that all elements have been activated.
+            if (document.querySelector('body[data-initializing]')) {
+              return 'DOM is being hydrated'
+            }
+
+            if (window.CapybaraLockstep && CapybaraLockstep.isBusy()) {
+              return 'JavaScript or AJAX requests are running'
+            }
+
+            return false
+          JS
+        end
+      end
+
+      def page
+        Capybara.current_session
+      end
+
+      delegate :evaluate_script, :evaluate_async_script, :execute_script, :driver, to: :page
+
+      def ignoring_alerts(&block)
+        block.call
+      rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
+        # noop
+      end
+
+      def with_max_wait_time(seconds, &block)
+        old_max_wait_time = Capybara.default_max_wait_time
+        Capybara.default_max_wait_time = seconds
+        begin
+          block.call
+        ensure
+          Capybara.default_max_wait_time = old_max_wait_time
+        end
+      end
+
+      def log(message)
+        if debug? && message.present?
+          message = "[Capybara::Lockstep] #{message}"
+          if @debug.respond_to?(:debug)
+            # If someone set Capybara::Lockstep to a logger, use that
+            @debug.debug(message)
+          else
+            # Otherwise print to STDOUT
+            puts message
+          end
+        end
+      end
+
+    end
+
+  end
+end
+

data/lib/capybara-lockstep/patiently.rb

@@ -0,0 +1,58 @@
+module Capybara
+  module Lockstep
+    # Ported from https://github.com/makandra/spreewald/blob/master/lib/spreewald_support/tolerance_for_selenium_sync_issues.rb
+    module Patiently
+
+      RETRY_ERRORS = %w[
+        Capybara::Lockstep::Busy
+        Capybara::ElementNotFound
+        Spec::Expectations::ExpectationNotMetError
+        RSpec::Expectations::ExpectationNotMetError
+        Minitest::Assertion
+        Capybara::Poltergeist::ClickFailed
+        Capybara::ExpectationNotMet
+        Selenium::WebDriver::Error::StaleElementReferenceError
+        Selenium::WebDriver::Error::NoAlertPresentError
+        Selenium::WebDriver::Error::ElementNotVisibleError
+        Selenium::WebDriver::Error::NoSuchFrameError
+        Selenium::WebDriver::Error::NoAlertPresentError
+        Selenium::WebDriver::Error::JavascriptError
+        Selenium::WebDriver::Error::UnknownError
+        Selenium::WebDriver::Error::NoSuchAlertError
+      ]
+
+      # evaluate_script latency is ~ 0.025s
+      WAIT_PERIOD = 0.03
+
+      def patiently(timeout = Capybara.default_max_wait_time, &block)
+        started = monotonic_time
+        tries = 0
+        begin
+          tries += 1
+          block.call
+        rescue Exception => e
+          raise e unless retryable_error?(e)
+          raise e if (monotonic_time - started > timeout && tries >= 2)
+          sleep(WAIT_PERIOD)
+          if monotonic_time == started
+            raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead"
+          end
+          retry
+        end
+      end
+
+      private
+
+      def monotonic_time
+        # We use the system clock (i.e. seconds since boot) to calculate the time,
+        # because Time.now may be frozen
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def retryable_error?(e)
+        RETRY_ERRORS.include?(e.class.name)
+      end
+
+    end
+  end
+end

data/lib/capybara-lockstep/version.rb

@@ -0,0 +1,5 @@
+module Capybara
+  module Lockstep
+    VERSION = "0.2.1"
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: capybara-lockstep
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Henning Koch
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-03-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: 
+email:
+- henning.koch@makandra.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- capybara-lockstep.gemspec
+- lib/capybara-lockstep.rb
+- lib/capybara-lockstep/capybara_ext.rb
+- lib/capybara-lockstep/configuration.rb
+- lib/capybara-lockstep/errors.rb
+- lib/capybara-lockstep/helper.js
+- lib/capybara-lockstep/helper.rb
+- lib/capybara-lockstep/lockstep.rb
+- lib/capybara-lockstep/patiently.rb
+- lib/capybara-lockstep/version.rb
+homepage: https://rubygems.org/gems/capybara-lockstep
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubygems.org/gems/capybara-lockstep
+  source_code_uri: https://rubygems.org/gems/capybara-lockstep
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.6
+signing_key: 
+specification_version: 4
+summary: Synchronize Capybara commands with client-side JavaScript and AJAX requests
+test_files: []