Document Debugging and Rescuing on Failures 🦸

Author: ElMassimo

CHANGELOG.md

@@ -1,3 +1,7 @@
+## Capybara Test Helpers 1.0.3 (2020-11-24) ##
+
+* Add `CapybaraTestHelpers::BenchmarkHelpers`
+
 ## Capybara Test Helpers 1.0.2 (2020-11-23) ##
 
 *   Add `aliases` DSL to define `SELECTORS`.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capybara_test_helpers (1.0.2)
+    capybara_test_helpers (1.0.3)
       activesupport
       capybara
 

docs/.algolia/config.json

@@ -11,8 +11,8 @@
   "stop_urls": [
     "https://capybara-test-helpers.netlify.app/introduction.html",
     "https://capybara-test-helpers.netlify.app/installation.html",
+    "https://capybara-test-helpers.netlify.app/api/index.html",
     "https://capybara-test-helpers.netlify.app/guide/index.html",
-    "https://capybara-test-helpers.netlify.app/guide/advanced/synchronization.html",
     "https://capybara-test-helpers.netlify.app/guide/essentials/actions.html",
     "https://capybara-test-helpers.netlify.app/guide/essentials/finders.html",
     "https://capybara-test-helpers.netlify.app/guide/essentials/querying.html",
@@ -22,6 +22,7 @@
     "https://capybara-test-helpers.netlify.app/guide/essentials/injection.html",
     "https://capybara-test-helpers.netlify.app/guide/advanced/assertions.html",
     "https://capybara-test-helpers.netlify.app/guide/advanced/composition.html",
+    "https://capybara-test-helpers.netlify.app/guide/advanced/debugging.html",
     "https://capybara-test-helpers.netlify.app/guide/advanced/design-patterns.html",
     "https://capybara-test-helpers.netlify.app/guide/advanced/filtering.html",
     "https://capybara-test-helpers.netlify.app/guide/migrating_from_cucumber/index.html"

docs/.vitepress/config.js

@@ -106,6 +106,10 @@ const config = {
             text: 'Advanced Composition',
             link: '/guide/advanced/composition.html',
           },
+          {
+            text: 'Debugging',
+            link: '/guide/advanced/debugging.html',
+          },
           {
             text: 'Design Patterns',
             link: '/guide/advanced/design-patterns.html',

docs/.vitepress/styles/styles.css

@@ -27,11 +27,37 @@ a.sidebar-link:hover {
   color: #cb4e00;
 }
 
+.custom-block {
+  border-bottom-right-radius: 2px;
+  border-top-right-radius: 2px;
+}
+
 .custom-block.custom-block.tip {
   background-color: #f7f5f3;
   border-color: #f38b54;
 }
 
+.custom-block:before {
+  position: absolute;
+  top: 19px;
+  left: -14px;
+  color: #fff;
+  width: 20px;
+  height: 20px;
+  border-radius: 100%;
+  text-align: center;
+  line-height: 20px;
+  font-weight: 700;
+  font-size: 14px;
+}
+
+.custom-block.tip:before {
+  content: url(/icons/bulb.svg);
+  width: 25px;
+  height: 25px;
+  left: -16px;
+}
+
 details > summary {
   cursor: pointer;
 }

docs/api/index.md

@@ -4,4 +4,16 @@ sidebar: auto
 
 # API Reference
 
+## Actions
+
+## Aliases
+
+## Assertions
+
+## Finders
+
+## Scoping
+
+## Wrapping
+
 __Coming Soon__

docs/guide/advanced/debugging.md

@@ -0,0 +1,55 @@
+[pry-rescue]: https://github.com/ConradIrwin/pry-rescue
+[pry-stack-explorer]: https://github.com/pry/pry-stack_explorer
+
+# Debugging 🐞
+
+In order to keep track of the interactions being performed in the test, it can be very convenient to print any test helper methods as they are executed, which can also help to detect slow paths.
+
+You can easily achieve this by adding `CapybaraTestHelpers::BenchmarkHelper` to your `BaseTestHelper`:
+
+```ruby
+require 'capybara_test_helpers/benchmark_helpers' if ENV['CI']
+
+class BaseTestHelper < Capybara::TestHelper
+  include CapybaraTestHelpers::BenchmarkHelpers if ENV['CI']
+end
+```
+
+In the snippet above, we skip the extra output if we are running tests in a continuous integration server.
+
+These helpers need the `rainbow` gem to be installed for nicer output:
+
+```ruby
+gem :development, :test do
+  gem 'rainbow'
+end
+```
+
+And the result:
+
+![benchmark_helpers](/images/benchmark_helpers.svg)
+
+## Pausing on Failures 🦸
+
+When running tests locally, it can be really helpful to pause and debug when an assertion or find fails.
+
+[`pry-rescue`][pry-rescue] is excellent for this purpose when running integration tests in RSpec. You can install it by adding the following to your Gemfile:
+
+```ruby
+group :development do
+  gem 'pry-rescue'
+  gem 'pry-stack_explorer'
+end
+```
+
+and then requiring it in `spec_helper.rb`, `base_test_helper.rb`, or similar:
+
+```ruby
+require 'pry-rescue/rspec' unless ENV['CI']
+```
+
+Whenever a test fails, it will start an interactive session, allowing you to query the page contents and call any test helper methods:
+
+![benchmark_helpers](/images/pry-rescue.svg)
+
+You can navigate through the stack by running the [`up` and `down` commands][pry-stack-explorer].