Merge branch 'docs-testing-n-1-request-sepcs' into 'master'

Docs: Require request specs when testing N+1 for controllers

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

doc/development/query_recorder.md

@@ -36,6 +36,13 @@ it "avoids N+1 database queries" do
 end
 ```
 
+## Use request specs instead of controller specs
+
+Use a [request spec](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/spec/requests) when writing a N+1 test on the controller level.
+
+Controller specs should not be used to write N+1 tests as the controller is only initialized once per example.
+This could lead to false successes where subsequent "requests" could have queries reduced (e.g. because of memoization).
+
 ## Finding the source of the query
 
 It may be useful to identify the source of the queries by looking at the call backtrace.

doc/development/testing_guide/testing_levels.md

@@ -63,7 +63,7 @@ They're useful to test permissions, redirections, what view is rendered etc.
 
 | Code path | Tests path | Testing engine | Notes |
 | --------- | ---------- | -------------- | ----- |
-| `app/controllers/` | `spec/controllers/` | RSpec | |
+| `app/controllers/` | `spec/controllers/` | RSpec | For N+1 tests, use [request specs](../query_recorder.md#use-request-specs-instead-of-controller-specs) |
 | `app/mailers/` | `spec/mailers/` | RSpec | |
 | `lib/api/` | `spec/requests/api/` | RSpec | |
 | `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. |