Merge branch 'patch-28' into 'master'

Add debugging section to testing_guide/best_practices.md.

See merge request gitlab-org/gitlab-ce!14858

doc/development/testing_guide/best_practices.md

@@ -60,6 +60,35 @@ 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 pause 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, press any key.
+
+For example:
+
+```
+$ 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 any key to resume the execution of the example!
+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

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

spec/support/live_debugger.rb

+require 'io/console'
+
+module LiveDebugger
+  def live_debug
+    puts
+    puts "Current example is paused for live debugging."
+    puts "Opening #{current_url} in your default browser..."
+    puts "The current user credentials are: #{@current_user.username} / #{@current_user.password}" if @current_user
+    puts "Press any key to resume the execution of the example!!"
+
+    `open #{current_url}`
+
+    loop until $stdin.getch
+
+    puts "Back to the example!"
+  end
+end

spec/support/login_helpers.rb

@@ -3,6 +3,21 @@ 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
+
+  # Overriding Devise::Test::IntegrationHelpers#sign_out to clear @current_user.
+  def sign_out(resource_or_scope)
+    super
+
+    @current_user = nil
+  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 +43,7 @@ module LoginHelpers
 
     gitlab_sign_in_with(user, **kwargs)
 
-    user
+    @current_user = user
   end
 
   def gitlab_sign_in_via(provider, user, uid)
@@ -41,6 +56,7 @@ module LoginHelpers
   def gitlab_sign_out
     find(".header-user-dropdown-toggle").click
     click_link "Sign out"
+    @current_user = nil
 
     expect(page).to have_button('Sign in')
   end

spec/support/test_env.rb

@@ -182,6 +182,8 @@ module TestEnv
     return unless @gitaly_pid
 
     Process.kill('KILL', @gitaly_pid)
+  rescue Errno::ESRCH
+    # The process can already be gone if the test run was INTerrupted.
   end
 
   def setup_factory_repo