capybara-lockstep 0.3.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0d733ed210e1ba465d9d612fcf461618ee91c88a71b09f9c0020271e4ac28ef
-  data.tar.gz: 5f30713c033ebd57b30d37f27e545c2a4547f6d40cd013c15f4ebba50a1f3893
+  metadata.gz: 8335399770451283be7443be41f3f1e5c2b0401f16a64a7722fb6b39ec2f3143
+  data.tar.gz: 601249c76c50789b44199e734a64fb039cd3b77c1db3e9f9068b1e7dea188216
 SHA512:
-  metadata.gz: d8fcf72c9736d98a80661f282527f0f53affb22b5aa2b537f7e7fbc4ea246ca2886e4f798343654c984321ca3d7dfec25043fa8e70d4341558a9073ea69911fe
-  data.tar.gz: c1f5144ed73a92f33e6ac36a0838401efae44d26ec199857f0e85a99b07afcd780d558ee6f3e859ac393db11649d186c8d56f72ddd6c2629fcddd68c2af907c0
+  metadata.gz: 638b0671d9f919c85b972cb2af4df763932a8c00ab21cd8387e3b483fda43448bb3c28b434aa821c0c6e75d4c67d82acb1dad0788128a5b1761bae0ae45400d6
+  data.tar.gz: eed68edd632b78dea169e208162e4a041cfc1ed2a78c6593eebf55d27d2fe54d9161e1c65f21771cb66de2ef4e2e2ce92573569118e30e8a3148368ffaaafe53

data/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+---
+name: Tests
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+jobs:
+  test:
+    runs-on: ubuntu-20.04
+    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
+      run: 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,3 +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.2)
+    capybara-lockstep (0.7.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)
@@ -17,6 +18,7 @@ GEM
       zeitwerk (~> 2.3)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
+    byebug (11.1.3)
     capybara (3.35.3)
       addressable
       mini_mime (>= 0.1.3)
@@ -26,16 +28,28 @@ 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)
+    mini_portile2 (2.5.1)
     minitest (5.14.4)
-    nokogiri (1.11.1)
+    nokogiri (1.11.3)
       mini_portile2 (~> 2.5.0)
       racc (~> 1.4)
+    phantomjs (2.1.1.0)
     public_suffix (4.0.6)
     racc (1.5.2)
     rack (2.2.3)
@@ -56,12 +70,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)
@@ -70,9 +92,14 @@ PLATFORMS
   ruby
 
 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
@@ -173,9 +190,9 @@ capybara-lockstep will automatically patch Capybara to wait for the browser afte
 Run your test suite to see if integration was successful and whether stability improves. During validation we recommend to activate `Capybara::Lockstep.debug = true` in your `spec_helper.rb` (RSpec) or `env.rb` (Cucumber). You should see messages like this in your console:
 
 ```text
-[Capybara::Lockstep] Synchronizing
-[Capybara::Lockstep] Finished waiting for JavaScript
-[Capybara::Lockstep] Synchronized successfully
+[capybara-lockstep] Synchronizing
+[capybara-lockstep] Finished waiting for JavaScript
+[capybara-lockstep] Synchronized successfully
 ```
 
 Note that you may see some failures from tests with wrong assertions, which sometimes passed due to lucky timing.
@@ -192,30 +209,52 @@ In casual testing I experienced a performance impact between +/- 10%.
 
 ## Debugging log
 
-capybara-lockstep can print to the console whenever it waits for the browser. To enable the log:
+You can enable extensive logging. This is useful to see whether capybara-lockstep has an effect on your tests, or to debug why synchronization is taking too long.
+
+To enable the log, say this before or during a test:
 
 ```ruby
 Capybara::Lockstep.debug = true
 ```
 
-You should now see messages like this during your test runs:
+You should now see messages like this on your standard output:
 
 ```
-[Capybara::Lockstep] Synchronizing
-[Capybara::Lockstep] Finished waiting for JavaScript
-[Capybara::Lockstep] Synchronized successfully
+[capybara-lockstep] Synchronizing
+[capybara-lockstep] Finished waiting for JavaScript
+[capybara-lockstep] Synchronized successfully
 ```
 
+You should also see messages like this in your browser's JavaScript console:
+
+```
+[capybara-lockstep] Started work: fetch /path [3 jobs]
+[capybara-lockstep] Finished work: fetch /path [2 jobs]
+```
+
+
+### Using a logger
+
 You may also configure logging to an existing logger object:
 
 ```ruby
 Capybara::Lockstep.debug = Rails.logger
 ```
 
+### Logging in the browser only
+
+To enable logging in the browser console (but not STDOUT), include the snippet with `{ debug: true }`:
+
+```
+capybara_lockstep(debug: true)
+```
+
 
 ## Disabling synchronization
 
-If for some reason you want to disable browser synchronization for a while, you can do it like this:
+Sometimes you want to disable browser synchronization, e.g. to observe a loading spinner during a long-running request.
+
+To disable synchronization:
 
 ```ruby
 begin
@@ -226,9 +265,11 @@ ensure
 end
 ```
 
-## Timeout
+## Synchronization timeout
+
+By default capybara-lockstep will wait `Capybara.default_max_wait_time` seconds for the page initialize and for JavaScript and AJAX request to finish.
 
-By default capybara-lockstep will wait up to 10 seconds for the page initialize and for JavaScript and AJAX request to finish.
+When synchronization times out, capybara-lockstep will log but not raise an error.
 
 You can configure a different timeout:
 
@@ -236,70 +277,82 @@ You can configure a different timeout:
 Capybara::Lockstep.timeout = 5 # seconds
 ```
 
-## Ruby API
+To revert to defaulting to `Capybara.default_max_wait_time`, set the timeout to `nil`:
 
-capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
+```ruby
+Capybara::Lockstep.timeout = nil
+```
 
-For additional edge cases you may interact with capybara-lockstep from your Ruby code.
 
+## Manual synchronization
 
-### Waiting until the browser is idle
+capybara-lockstep will automatically patch Capybara to wait for the browser after every command. **This should be enough for most test suites**.
 
-This will block until the document was loaded, the DOM has been hydrated and all AJAX requests have concluded:
+For additional edge cases you may manually tell capybara-lockstep to wait. The following Ruby method will block until the browser is idle:
 
 ```ruby
 Capybara::Lockstep.synchronize
 ```
 
-An example use case is a Cucumber step that explicitely waits for JavaScript to finish, in the rare occasion where capybara-lockstep hasn't picked up an event or request:
+You may also synchronize from your client-side JavaScript. The following will run the given callback once the browser is idle:
 
-```gherkin
-When 'I wait for the page to load' do
-  Capybara::Lockstep.synchronize
-end
+```js
+CapybaraLockstep.synchronize(callback)
+```
+
+## Signaling asynchronous work
+
+If for some reason you want capybara-lockstep to consider additional asynchronous work as "busy", you can do so:
+
+```js
+CapybaraLockstep.startWork('Eject warp core')
+doAsynchronousWork().then(function() {
+  CapybaraLockstep.stopWork('Eject warp core')
+})
+```
+
+The string argument is used for logging (when logging is enabled). It does **not** need to be unique per job. In this case you should see messages like this in your browser's JavaScript console:
+
+```text
+[capybara-lockstep] Started work: Eject warp core [1 jobs]
+[capybara-lockstep] Finished work: Eject warp core [0 jobs]
 ```
 
-## JavaScript API
+You may omit the string argument, in which case nothing will be logged, but the work will still be tracked.
 
-capybara-lockstep already hooks into [many JavaScript APIs](#how-capybara-lockstep-helps) like `XMLHttpRequest` or `fetch()` to mark the browser as "busy" until their work finishes. **This should be enough for most test suites**.
 
-For additional edge cases you may interact with capybara-lockstep from your own JavaScripts.
+## Note on interacting with the JavaScript API
 
-Note that when you only load the JavaScript snippet in tests you need check before calling any API functions:
+If you only load capybara-lockstep in tests you, should check for the `CapybaraLockstep` global to be defined before you interact with the JavaScript API.
 
 ```js
 if (window.CapybaraLockstep) {
-  CapybaraLockstep.startWork()
+  // interact with CapybaraLockstep
 }
 ```
 
-### Signaling asynchronous work
+## Handling legacy promises
 
-If for some reason you want capybara-lockstep to consider additional asynchronous work as "busy", you can do so:
+Legacy promise implementations (like jQuery's `$.Deferred` and AngularJS' `$q`) work using tasks instead of microtasks. Their AJAX implementations (like `$.ajax()` and `$http`) use these promises to signal that a request is done.
+
+This means there is a time window in which all AJAX requests have finished, but their callbacks have not yet run:
 
 ```js
-CapybaraLockstep.startWork()
-doAsynchronousWork().then(function() {
-  CapybaraLockstep.stopWork()
+$.ajax('/foo').then(function() {
+  // This callback runs one task after the response was received
 })
 ```
 
-### Checking if the browser is busy
-
-You can query capybara-lockstep whether it considers the browser to be busy or idle:
+It is theoretically possible that your test will observe the browser in that window, and expect content that has not been rendered yet. This will usually be mitigated by Capybara's retry logic. **If** you think that this is an issue for your test suite, you can configure capybara-headless to wait additional tasks before it considers the browser to be idle:
 
 ```js
-CapybaraLockstep.isBusy() // => false
-CapybaraLockstep.isIdle() // => true
+Capybara:Lockstep.wait_tasks = 1
 ```
 
-### Waiting until the browser is idle
+If you see longer `then()` chains in your code, you may need to configure a higher number of tasks to wait.
 
-This will run the given callback once the browser is considered to be idle:
+This will have a negative performance impact on your test suite.
 
-```js
-CapybaraLockstep.synchronize(callback)
-```
 
 ## Development