Merge branch 'dchevalier2-master-patch-12374' into 'master'

Update end-to-end best practices test case section

See merge request gitlab-org/gitlab!81845

doc/development/testing_guide/end_to_end/best_practices.md

@@ -18,12 +18,10 @@ In case custom inflection logic is needed, custom inflectors are added in the [q
 
 Every test should have a corresponding test case in the [GitLab project Test Cases](https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases) as well as a results issue in the [Quality Test Cases project](https://gitlab.com/gitlab-org/quality/testcases/-/issues).
 It's recommended that you reuse the issue created to plan the test as the results issue. If a test case or results issue does not already exist you
-can create them yourself. Alternatively, you can run the test in a pipeline that has reporting
-enabled and the test-case reporter will automatically create a new test case and/or results issue and link the results issue to it's corresponding test case.
+can create them yourself by using this [end-to-end test issue template](https://gitlab.com/gitlab-org/quality/testcases/-/blob/master/.gitlab/issue_templates/End-to-end%20Test.md) to format the issue description. (Note you must copy/paste this for test cases as templates aren't currently available.) Alternatively, you can run the test in a pipeline that has reporting enabled and the test-case reporter will automatically create a new test case and/or results issue and link the results issue to it's corresponding test case.
 
 Whether you create a new test case or one is created automatically, you will need to manually add
-a `testcase` RSpec metadata tag. In most cases, a single test will be associated with a single test case
- ([see below for exceptions](#exceptions)).
+a `testcase` RSpec metadata tag. In most cases, a single test will be associated with a single test case.
 
 For example:
 
@@ -41,7 +39,7 @@ RSpec.describe 'Stage' do
 end
 ```
 
-### Exceptions
+### For shared tests
 
 Most tests are defined by a single line of a `spec` file, which is why those tests can be linked to a
 single test case via the `testcase` tag.
@@ -54,24 +52,19 @@ multiple tests, including:
 - Templated tests.
 - Tests in shared examples that include more than one example.
 
-In those and similar cases we can't assign a single `testcase` tag and so we rely on the test-case
-reporter to programmatically determine the correct test case based on the name and description of
-the test. In such cases, the test-case reporter will automatically create a test case and/or results issue
-the first time the test runs, if none exist already.
+In those and similar cases we need to include the test case link by other means.
 
-In such a case, if you create the test case or results issue yourself or want to reuse an existing issue,
-you must use this [end-to-end test issue template](https://gitlab.com/gitlab-org/quality/testcases/-/blob/master/.gitlab/issue_templates/End-to-end%20Test.md)
-to format the issue description. (Note you must copy/paste this for test cases as templates aren't currently available.)
-
-To illustrate, there are two tests in the shared examples in [`qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/47b17db82c38ab704a23b5ba5d296ea0c6a732c8/qa/qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb):
+To illustrate, there are two tests in the shared examples in [`qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb):
 
 ```ruby
-shared_examples 'only user with access pushes and merges' do
-  it 'unselected maintainer user fails to push' do
+shared_examples 'unselected maintainer' do |testcase|
+  it 'user fails to push', testcase: testcase do
     ...
   end
+end
 
-  it 'selected developer user pushes and merges' do
+shared_examples 'selected developer' do |testcase|
+  it 'user pushes and merges', testcase: testcase do
     ...
   end
 end
@@ -84,13 +77,22 @@ RSpec.describe 'Create' do
   describe 'Restricted protected branch push and merge' do
     context 'when only one user is allowed to merge and push to a protected branch' do
       ...
-      it_behaves_like 'only user with access pushes and merges'
+
+      it_behaves_like 'unselected maintainer', 'https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases/347775'
+      it_behaves_like 'selected developer', 'https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases/347774'
+    end
+
+    context 'when only one group is allowed to merge and push to a protected branch' do
+      ...
+
+      it_behaves_like 'unselected maintainer', 'https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases/347772'
+      it_behaves_like 'selected developer', 'https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases/347773'
     end
   end
 end
 ```
 
-There would be two associated test cases, one for each shared example, with the following content:
+There would be four associated test cases, two for each shared example, with the following content for the first two:
 
 [Test 1 Test Case](https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases/347774):