4 files changed, 61 insertions, 20 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)
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
index 48cacba6a8a..0dc417b3cb6 100644
--- a/spec/spec_helper.rb
+++ b/spec/spec_helper.rb
@@ -49,6 +49,7 @@ RSpec.configure do |config|
   config.include LoginHelpers, type: :feature
   config.include SearchHelpers, type: :feature
   config.include WaitForRequests, :js
+  config.include LiveDebugger, :js
   config.include StubConfiguration
   config.include EmailHelpers, :mailer, type: :mailer
   config.include TestEnv
diff --git a/spec/support/live_debugger.rb b/spec/support/live_debugger.rb
new file mode 100644
index 00000000000..b15aba01e68
--- /dev/null
+++ b/spec/support/live_debugger.rb
@@ -0,0 +1,21 @@
+require 'io/console'
+
+module LiveDebugger
+  def live_debug
+    `open #{current_url}`
+
+    puts "\nCurrent example is paused for live debugging"
+    puts "The current user credentials are: #{@current_user.username} / 12345678" if @current_user
+    puts "Press 'c' to continue the execution of the example"
+
+    loop do
+      if $stdin.getch == 'c'
+        break
+      else
+        puts "Please press 'c' to continue the execution of the example! ;)"
+      end
+    end
+
+    puts "Back to the example!"
+  end
+end
diff --git a/spec/support/login_helpers.rb b/spec/support/login_helpers.rb
index 3e117530151..2ca05bb1778 100644
--- a/spec/support/login_helpers.rb
+++ b/spec/support/login_helpers.rb
@@ -3,6 +3,14 @@ require_relative 'devise_helpers'
 module LoginHelpers
   include DeviseHelpers
 
+  # Overriding Devise::Test::IntegrationHelpers#sign_in to store @current_user
+  # since we may need it in LiveDebugger#live_debug.
+  def sign_in(resource, scope: nil)
+    super
+
+    @current_user = resource
+  end
+
   # Internal: Log in as a specific user or a new user of a specific role
   #
   # user_or_role - User object, or a role to create (e.g., :admin, :user)
@@ -28,7 +36,7 @@ module LoginHelpers
 
     gitlab_sign_in_with(user, **kwargs)
 
-    user
+    @current_user = user
   end
 
   def gitlab_sign_in_via(provider, user, uid)