Add LiveDebugger#live_debug to debug Capybara in feature tests.

Signed-off-by: Rémy Coutable <remy@rymai.me>

1 files changed, 30 insertions, 19 deletions

diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index 386fe2a35eb..d07a368abfd 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -58,6 +58,36 @@ writing one](testing_levels.md#consider-not-writing-a-system-test)!
 - It's ok to look for DOM elements but don't abuse it since it makes the tests
   more brittle
 
+#### Debugging Capybara
+
+Sometimes you may need to debug Capybara tests by observing browser behavior.
+
+You can stall Capybara and view the website on the browser by using the
+`live_debug` method in your spec. The current page will be automatically opened
+in your default browser.
+You may need to sign-in first (the current user's credentials are displayed in
+the terminal).
+
+To resume the test run, you only need to press `c`.
+
+For example:
+
+```ruby
+$ bin/rspec spec/features/auto_deploy_spec.rb:34
+Running via Spring preloader in process 8999
+Run options: include {:locations=>{"./spec/features/auto_deploy_spec.rb"=>[34]}}
+
+Current example is paused for live debugging
+The current user credentials are: user2 / 12345678
+Press 'c' to continue the execution of the example
+Please press 'c' to continue the execution of the example! ;) <- I pressed `d` here
+Back to the example!
+.
+
+Finished in 34.51 seconds (files took 0.76702 seconds to load)
+1 example, 0 failures
+```
+
 ### `let` variables
 
 GitLab's RSpec suite has made extensive use of `let` variables to reduce
@@ -267,25 +297,6 @@ RSpec.configure do |config|
 end
 ```
 
-### Debugging Capybara
-
-Sometimes you may need to debug Capybara tests by observing browser behavior.
-
-You can stall capybara and view the website on the browser by adding a long sleep command in your spec and then opening your browser
-to the capybara url.
-
-You can get the capybara url by doing `puts current_url`.
-You can also get the user's email by doing `puts user.email`.
-
-The default password for the user is `12345678`. 
-
-Example:
-```ruby
-puts current_url
-puts user.email
-sleep(200)
-```
-
 ---
 
 [Return to Testing documentation](index.md)