capybara-lockstep 0.7.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8335399770451283be7443be41f3f1e5c2b0401f16a64a7722fb6b39ec2f3143
-  data.tar.gz: 601249c76c50789b44199e734a64fb039cd3b77c1db3e9f9068b1e7dea188216
+  metadata.gz: 271ed22154f61a70a3961eb2bd2a8a7d29430dfb37107b9f1176257e8efab320
+  data.tar.gz: 6ba0d7a5c7e8bff779ee2a9ac2d6d32829374041dff41d7bddd9cbd19627a468
 SHA512:
-  metadata.gz: 638b0671d9f919c85b972cb2af4df763932a8c00ab21cd8387e3b483fda43448bb3c28b434aa821c0c6e75d4c67d82acb1dad0788128a5b1761bae0ae45400d6
-  data.tar.gz: eed68edd632b78dea169e208162e4a041cfc1ed2a78c6593eebf55d27d2fe54d9161e1c65f21771cb66de2ef4e2e2ce92573569118e30e8a3148368ffaaafe53
+  metadata.gz: 24f098f75fc9093065cf4210eed7fab3b8f1ea69d49d6e328f195f92affe41c262fa92daecbf1ee8247dba8bcad1d3d5c0941766bd3889416be6aedf79f3e354
+  data.tar.gz: ea3debf0f2e4178dbc200c84a98aae87a614914de889769d10ed1cc2e311f83e93de460e2b1a4c163b756dc331838164bfe7ae8f77f676833df93a984a2fda49

data/.github/workflows/test.yml

@@ -7,9 +7,13 @@ on:
   pull_request:
     branches:
     - master
+  workflow_dispatch:
+    branches:
+    - master  
 jobs:
   test:
     runs-on: ubuntu-20.04
+    timeout-minutes: 3
     strategy:
       fail-fast: false
       matrix:
@@ -24,6 +28,12 @@ jobs:
       BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
     steps:
     - uses: actions/checkout@v2
+    - name: Install Chrome
+      uses: browser-actions/setup-chrome@latest
+    - name: Show Chrome version
+      run: chrome --version
+    - name: Install ChromeDriver
+      uses: nanasess/setup-chromedriver@master
     - name: Install ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -33,4 +43,8 @@ jobs:
         gem install bundler:2.2.15
         bundle install --no-deployment
     - name: Run tests
-      run: bundle exec rake spec
+      uses: nick-invision/retry@v2
+      with:
+        timeout_seconds: 30
+        max_attempts: 3
+        command: bundle exec rake spec

data/CHANGELOG.md

@@ -2,32 +2,72 @@ 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).
 
+## 1.1.1 - 2022-03-16
 
-## Unreleased
+- Activate rubygems MFA
 
-### Breaking changes
+## 1.1.0
 
-- 
+- Stop handling of `[data-initializing]` attribute. Apps that have late initialization after the `load` event can just use `CapybaraLockstep.startWork()`.
+- Remove useless tracking of interaction events like `"click"` or `"focus"`. If such an event handler would start an AJAX request, it is already tracked.
+- On apps with Unpoly 0.x, wait for one more task after `DOMContentLoaded`. Please upgrade to Unpoly 1.x or 2.x, as this logic will be removed in a year or so.
 
-### Compatible changes
+## 1.0.0
 
--
+- First stable release.
+- Replace option `Capybara::Lockstep.config` (`true`, `false`) with a more refined option `.mode` (`:auto`, `:manual`, `:off`)
 
-## 0.7.0 - 2021-05-04
+## 0.7.0
 
-### Compatible changes
+- Ruby 3 compatibility.
+- Fix logging.
 
-- add changelog
-- add gemika for tests with github actions
-- add Ruby 3 support
+## 0.6.0
 
-## 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 
+- Synchronize around `evaluate_script` and `execute_script`.
+- Improve logging.
+
+## 0.5.0
+
+- Allow developer to signal custom async work.
+- Option to wait additional tasks, to handle legacy promise implementations.
+- Debugging log can be enabled during a running test.
+- Also wait for images and iframes.
+
+## 0.4.0
+
+- Don't fail the test when synchronization times out.
+- Capybara::Lockstep.debug = true will now also enable client-side logging on the browser's JavaScript console.
+- Always wait at least for `Capybara.default_max_wait_time`.
+
+## 0.3.2
+
+- Delay synchronization when an alert is open (instead of failing)
+
+
+## 0.3.1
+
+- Fix typo in log message
+
+## 0.3.0
+
+- Rework entire waiting logic to be lazy.
+- There is now a single method `Capybara::Lockstep.synchronize` (no distinction between awaiting "initialization" and "idle").
+
+## 0.2.3
+
+- When we cannot wait for browser idle due to an open alert, wait before the next Capybara synchronize
+
+## 0.2.2
+
+- Fix incorrect data in gemspec.
+
+
+## 0.2.1
+
+- Internal changes.
+
+
+## 0.2.0
+
+- Initial release.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara-lockstep (0.7.0)
+    capybara-lockstep (1.1.1)
       activesupport (>= 3.2)
       capybara (>= 2.0)
       ruby2_keywords
@@ -44,10 +44,8 @@ GEM
       rake
     jasmine-core (3.6.0)
     mini_mime (1.1.0)
-    mini_portile2 (2.5.1)
     minitest (5.14.4)
-    nokogiri (1.11.3)
-      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)

data/README.md

@@ -1,12 +1,15 @@
 # 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.
+This Ruby gem synchronizes [Capybara](https://github.com/teamcapybara/capybara) commands with client-side JavaScript and AJAX requests. This greatly improves the stability of an end-to-end ("E2E") test suite, even if that suite has timing issues.
+
+The next section explain why your test suite is flaky and how capybara-lockstep can help.\
+If you don't care you may skip to [installation instructions](#installation).
 
 
 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.
+A naively written E2E 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:
 
@@ -23,28 +26,56 @@ 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.
+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.
+[Capybara will retry](https://github.com/teamcapybara/capybara#asynchronous-javascript-ajax-and-friends) 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.
+
+
+### This is a JavaScript problem
+
+The timing issues above will only manifest in an app where links, forms and buttons are handled by JavaScript.
+
+When all you have is standard HTML links and forms, stock Capybara will not see timing issues:
+
+- After a `visit()` Capybara/WebDriver will wait until the page is completely loaded
+- When following a link Capybara/WebDriver will wait until the link destination is completely loaded
+- When submitting a form Capybara/WebDriver will wait until the response is completely loaded
+
+However, when JavaScript handles a link click, you get **zero guarantees**.\
+Capybara/WebDriver **will not wait** for AJAX requests or any other async work.
 
-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.
+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](https://github.com/teamcapybara/capybara#asynchronous-javascript-ajax-and-friends).
 
-Whenever Capybara visits a new URL or simulates a user interaction (clicking, typing, etc.):
+capybara-lockstep synchronizes before:
 
-- 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 simulates a user interaction (clicking, typing, etc.)
+- Capybara visits a new URL
+- Capybara executes JavaScript
+
+When capybara-lockstep synchronizes it will:
+
+- wait for all document resources to load (images, CSS, fonts, frames).
+- wait for client-side JavaScript to render or hydrate DOM elements.
+- wait for any pending AJAX requests to finish and their callbacks to be called.
 - 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.
+- capybara-lockstep waits for dynamically inserted `<img>` or `<iframe>` elements to load.
+
+In summary Capybara can no longer observe the page while HTTP requests are in flight.
+This covers most async work that causes flaky tests.
+
+You can also configure capybara-lockstep to [wait for other async work](#signaling-asynchronous-work) that does not involve the network, like animations.
 
 
 Installation
@@ -76,127 +107,90 @@ And then execute:
 $ bundle install
 ```
 
-If you're not using Rails you should also `require 'capybara-lockstep'` in your `spec_helper.rb` (RSpec) or `env.rb` (Cucumber).
+If you're not using Rails you should also `require 'capybara-lockstep'` in your `spec_helper.rb` (RSpec), `test_helper.rb` (Minitest) 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:
+**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? %>
+<%= capybara_lockstep if defined?(Capybara::Lockstep) %>
 ```
 
-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.
+Ideally the snippet should be included in the `<head>` before any other `<script>` tags.
 
-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`.
 
-If you're not using Rails you can `include Capybara::Lockstep::Helper` and access the JavaScript with `capybara_lockstep_script`.
+**If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)** the `capybara_lockstep` Rails helper will insert a CSP nonce by default. You can also pass an explicit nonce string using the `:nonce` option.
 
 
-### Signaling the end of page initialization
 
-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.
+### Verify successful integration
 
-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.
+capybara-lockstep will automatically patch Capybara to wait for the browser after every command.
 
-To signal that JavaScript is still initializing, your application layouts should render the `<body>` element with an `[data-initializing]` attribute:
+Run your test suite to see if integration was successful and whether stability improves. During validation we recommend to activate the [debugging log](#debugging-log) before your test:
 
-```html
-<body data-initializing>
+```ruby
+Capybara::Lockstep.debug = true
 ```
 
-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.
+You should see messages like this in your console:
 
-**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.**
+```text
+[capybara-lockstep] Synchronizing
+[capybara-lockstep] Finished waiting for JavaScript
+[capybara-lockstep] Synchronized successfully
+```
 
-#### Example: Vanilla JS
+Note that you may see some failures from tests with wrong assertions, which previously passed due to lucky timing.
 
-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 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:
+## Signaling asynchronous work
 
-```js
-document.addEventListener('DOMContentLoaded', function() {
-  Libary.initialize({
-    onFinished: function() {
-      document.body.removeAttribute('data-initializing')
-    }
-  })
-})
-```
+By default capybara-lockstep waits until resources have loaded, AJAX requests have finished and their callbacks have been called.
 
-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]`:
+You can configure capybara-lockstep to wait for other async work that does not involve the network. Let's say we have an animation that fades in a new element over 2 seconds. The following will prevent Capybara from observing the page while the animation is running:
 
 ```js
-document.addEventListener('DOMContentLoaded', function() {
-  Libary.initialize()
-  setTimeout(function() { document.body.removeAttribute('data-initializing') })
-})
+async function fadeIn(element) {
+  CapybaraLockstep.startWork('Animation')
+  startAnimation(element, 'fade-in')
+  await waitForAnimationEnd(element)
+  CapybaraLockstep.stopWork('Animation')
+}
 ```
 
-If your initialization code lazy-loads another script, you should only remove `[data-initializing]` once that is done:
+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:
 
-```js
-document.addEventListener('DOMContentLoaded', function() {
-  import('huge-library').then(function({ HugeLibrary }) {
-    HugeLibrary.initialize()
-    document.body.removeAttribute('data-initializing')
-  })
-})
+```text
+[capybara-lockstep] Started work: Animation [1 jobs]
+[capybara-lockstep] Finished work: Animation [0 jobs]
 ```
 
+You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
 
-#### 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
-up.compiler('body', function(body) {
-  body.removeAttribute('data-initializing')
-})
-```
 
-#### Example: AngularJS 1
+## Note on interacting with the JavaScript API
 
-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]`:
+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
-app.directive('body', function() {
-  return {
-    restrict: 'E',
-    link: function() {
-      document.body.removeAttribute('data-initializing')
-    }
-  }
-})
+if (window.CapybaraLockstep) {
+  // interact with CapybaraLockstep
+}
 ```
 
-### 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. 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:
+If you can use ES6 you may also use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) to only call a function if `window.CapybaraLockstep` is defined:
 
-```text
-[capybara-lockstep] Synchronizing
-[capybara-lockstep] Finished waiting for JavaScript
-[capybara-lockstep] Synchronized successfully
+```js
+window.CapybaraLockstep?.startWork('Work')
 ```
 
-Note that you may see some failures from tests with wrong assertions, which sometimes passed due to lucky timing.
-
 
 ## Performance impact
 
@@ -204,7 +198,7 @@ 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 performance impact between +/- 10%.
+In casual testing with large test suites I experienced a performance impact between +/- 10%.
 
 
 ## Debugging log
@@ -243,44 +237,41 @@ 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 }`:
+To enable logging in the browser console (but not STDOUT), include the [JavaScript snippet](#including-the-javascript-snippet) with `{ debug: true }`:
 
-```
+```ruby
 capybara_lockstep(debug: true)
 ```
 
+## Synchronization timeout
 
-## Disabling synchronization
-
-Sometimes you want to disable browser synchronization, e.g. to observe a loading spinner during a long-running request.
+By default capybara-lockstep will wait `Capybara.default_max_wait_time` seconds for the page initialize and for JavaScript and AJAX request to finish.
 
-To disable synchronization:
+When synchronization times out, capybara-lockstep will [log](#debugging-log):
 
-```ruby
-begin
-  Capybara::Lockstep.enabled = false
-  do_unsynchronized_work
-ensure
-  Capybara::Lockstep.enabled = true
-end
+```text
+[capybara-lockstep] Could not synchronize within 3 seconds
 ```
 
-## Synchronization timeout
+You can configure a different 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.
+```ruby
+Capybara::Lockstep.timeout = 5 # seconds
+```
 
-When synchronization times out, capybara-lockstep will log but not raise an error.
+By default Capybara will **not** raise an error after a timeout. You may occasionally get a slow server response, and Capybara will retry synchronization before the next interaction or `visit`. This is often good enough.
 
-You can configure a different timeout:
+If you want to be strict you may configure that an `Capybara::Lockstep::Timeout` error is raised after a timeout:
 
 ```ruby
-Capybara::Lockstep.timeout = 5 # seconds
+Capybara::Lockstep.timeout_with = :error
 ```
 
-To revert to defaulting to `Capybara.default_max_wait_time`, set the timeout to `nil`:
+To revert to defaults:
 
 ```ruby
 Capybara::Lockstep.timeout = nil
+Capybara::Lockstep.timeout_with = nil
 ```
 
 
@@ -300,70 +291,85 @@ You may also synchronize from your client-side JavaScript. The following will ru
 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:
+## Disabling synchronization
 
-```js
-CapybaraLockstep.startWork('Eject warp core')
-doAsynchronousWork().then(function() {
-  CapybaraLockstep.stopWork('Eject warp core')
-})
-```
+Sometimes you want to disable browser synchronization, e.g. to observe a loading spinner during a long-running request.
 
-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:
+To disable automatic synchronization:
 
-```text
-[capybara-lockstep] Started work: Eject warp core [1 jobs]
-[capybara-lockstep] Finished work: Eject warp core [0 jobs]
+```ruby
+begin
+  Capybara::Lockstep.mode = :manual
+  do_unsynchronized_work
+ensure
+  Capybara::Lockstep.mode = :auto
+end
 ```
 
-You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
+In the `:manual` mode you may still force synchronization by calling `Capybara::Lockstep.synchronize` manually.
 
+To completely disable synchronization:
 
-## Note on interacting with the JavaScript API
+```ruby
+Capybara::Lockstep.mode = :off
+Capybara::Lockstep.synchronize # will not synchronize
+```
 
-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) {
-  // interact with CapybaraLockstep
-}
-```
 
 ## 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.
+Legacy promise implementations (like jQuery's `$.Deferred` and AngularJS' `$q`) work using [tasks instead of microtasks](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/). Their AJAX implementations (like `$.ajax()` and `$http`) use task-based 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
-$.ajax('/foo').then(function() {
+$http.get('/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:
+It is theoretically possible that your test will observe the browser in that window, and expect content that has not been rendered yet. Affected code must call `then()` on a task-based promise **or** use `setTimeout()` to push work into the next task.
 
-```js
-Capybara:Lockstep.wait_tasks = 1
+Any issues caused by 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:
+
+```ruby
+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.
+If you see longer chains of `then()` or nested `setTimeout()` calls 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.
+Waiting additional tasks will have a negative performance impact on your test suite.
 
+> **Note:** When capybara-lockstep detects jQuery on the page, it will automatically patch [`$.ajax()`](https://api.jquery.com/jQuery.ajax/) to wait an additional task after the response was received. If your only concern is callbacks to `$.ajax()` you do not need so set `Capybara::Lockstep.wait_tasks`.
 
-## 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.
+## Contributing
 
-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).
+Pull requests are welcome on GitHub at <https://github.com/makandra/capybara-lockstep>.
 
+After checking out the repo, run `bin/setup` to install dependencies.
 
-## Contributing
+Then, run `rake spec` to run the tests.
 
-Pull requests are welcome on GitHub at <https://github.com/makandra/capybara-lockstep>.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Manually testing a change
+
+To test an unrelased change with a test suite, we recommend to temporarily link the local repository from your test suites's `Gemfile`:
+
+```ruby
+gem 'capybara-lockstep', path: '../capybara-lockstep'
+```
+
+As an alternative you may also install this gem onto your local machine by running `bundle exec rake install`.
+
+### Releasing a new version
+
+- Update the version number in `version.rb`
+ - 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).
+ - If RubyGems publishing seems to freeze, try entering your OTP code.
 
 
 ## License

data/capybara-lockstep.gemspec

@@ -14,6 +14,10 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
 
+  spec.metadata["bug_tracker_uri"] = "https://github.com/makandra/capybara-lockstep/issues"
+  spec.metadata["changelog_uri"] = "https://github.com/makandra/capybara-lockstep/blob/master/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = 'true'
+
   # 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

data/lib/capybara-lockstep/capybara_ext.rb

@@ -55,8 +55,7 @@ module Capybara
               # 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)
+              Lockstep.auto_synchronize(lazy: !script_may_navigate_away, log: "Synchronizing before script: #{script}")
             end
 
             super(script, *args, &block).tap do
@@ -143,9 +142,10 @@ module Capybara
   module Lockstep
     module SynchronizeWithCatchUp
       ruby2_keywords def synchronize(*args, &block)
-        # This method is called very frequently by capybara.
+        # 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

@@ -10,6 +10,14 @@ module Capybara
         @timeout = seconds
       end
 
+      def timeout_with
+        @timeout_with.nil? ? :log : @timeout_with
+      end
+
+      def timeout_with=(action)
+        @timeout_with = action&.to_sym
+      end
+
       def debug?
         # @debug may also be a Logger object, so convert it to a boolean
         @debug.nil? ? false : !!@debug
@@ -29,16 +37,30 @@ module Capybara
         @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&.to_sym
+      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 wait_tasks
@@ -55,10 +77,6 @@ module Capybara
         @wait_tasks
       end
 
-      def disabled?
-        !enabled?
-      end
-
       private
 
       def javascript_driver?

data/lib/capybara-lockstep/errors.rb

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

data/lib/capybara-lockstep/helper.js

@@ -123,43 +123,21 @@ window.CapybaraLockstep = (function() {
     }
   }
 
-  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(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 trackRemoteElements() {
     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()
+    // Dynamic imports or analytics snippets may insert a script element
+    // that loads and executes additional JavaScript. We want to be isBusy()
     // until such scripts have loaded or errored.
     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.
+    // CapybaraLockstep.track() is called as the first script in the head.
+    // jQuery will be loaded after us, so we wait until DOMContentReady.
     whenReady(function() {
       if (!window.jQuery || waitTasks > 0) {
         return
@@ -180,28 +158,6 @@ window.CapybaraLockstep = (function() {
     })
   }
 
-  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() {
-      stopWorkNow()
-      if (document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
-        startWork('Page initialization')
-        let observer = new MutationObserver(onInitializingAttributeChanged)
-        observer.observe(document.body, { attributes: true, attributeFilter: [INITIALIZING_ATTRIBUTE] })
-      }
-    })
-  }
-
-  function onInitializingAttributeChanged() {
-    if (!document.body.hasAttribute(INITIALIZING_ATTRIBUTE)) {
-      stopWork('Page initialization')
-    }
-  }
-
   function isRemoteScript(element) {
     if (element.tagName === 'SCRIPT') {
       let src = element.getAttribute('src')
@@ -303,13 +259,28 @@ window.CapybaraLockstep = (function() {
     }
   }
 
+  function trackOldUnpoly() {
+    // CapybaraLockstep.track() is called as the first script in the head.
+    // Unpoly will be loaded after us, so we wait until DOMContentReady.
+    whenReady(function() {
+      // Unpoly 0.x would wait one task after DOMContentLoaded before booting.
+      // There's a slim chance that Capybara can observe the page before compilers have run.
+      // Unpoly 1.0+ runs compilers on DOMContentLoaded, so there's no issue.
+      if (window.up?.version?.startsWith('0.')) {
+        startWork('Old Unpoly')
+        setTimeout(function () {
+          stopWork('Old Unpoly')
+        })
+      }
+    })
+  }
+
   function track() {
+    trackOldUnpoly()
     trackFetch()
     trackXHR()
-    trackInteraction()
     trackRemoteElements()
     trackJQuery()
-    trackHydration()
   }
 
   function synchronize(callback) {

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
@@ -56,6 +68,8 @@ module Capybara
               if (protocol === 'data:' || protocol == 'about:') {
                 done(#{ERROR_PAGE_MISSING.to_json})
               } else if (document.readyState === 'complete') {
+                // WebDriver always waits for the `load` event after a visit(),
+                // unless a different page load strategy was configured.
                 synchronize()
               } else {
                 window.addEventListener('load', synchronize)
@@ -76,9 +90,14 @@ module Capybara
             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.
+          timeout_message = "Could not synchronize within #{timeout} seconds"
+          log timeout_message
+          if timeout_with == :error
+            raise Timeout, timeout_message
+          else
+            # Don't raise an error, this may happen if the server is slow to respond.
+            # We will retry on the next Capybara synchronize call.
+          end
         rescue ::Selenium::WebDriver::Error::UnexpectedAlertOpenError
           log ERROR_ALERT_OPEN
           # Don't raise an error, this will happen in an innocent test.

data/lib/capybara-lockstep/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Lockstep
-    VERSION = "0.7.0"
+    VERSION = "1.1.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lockstep
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-04 00:00:00.000000000 Z
+date: 2022-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -101,6 +101,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/makandra/capybara-lockstep
   source_code_uri: https://github.com/makandra/capybara-lockstep
+  bug_tracker_uri: https://github.com/makandra/capybara-lockstep/issues
+  changelog_uri: https://github.com/makandra/capybara-lockstep/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -116,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Synchronize Capybara commands with client-side JavaScript and AJAX requests