Apply suggestion to...

Apply suggestion to doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md

doc/development/testing_guide/end_to_end/index.md

@@ -166,6 +166,10 @@ environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/g
 Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab/tree/master/qa/README.md#how-can-i-use-it)
 and the section below.
 
+### Running tests that require special setup
+
+Learn how to perform [tests that require special setup or consideration to run on your local environment](running_tests_that_require_special_setup.md).
+
 ## How do I write tests?
 
 In order to write new tests, you first need to learn more about GitLab QA

doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md

+# Running tests that require special setup
+
+## Jenkins spec
+
+The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a docker container based on an image stored in the [GitLab-QA container registry](https://gitlab.com/gitlab-org/gitlab-qa/container_registry).
+The docker image it uses is preconfigured with some base data and plugins.
+The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that will be used
+to run the tests. Unfortunately, the GitLab Jenkins plugin does not accept ports so `http://localhost:3000` would
+not be accepted. Therefore, this requires us to run GitLab on port 80 or inside a docker container.
+
+To start a docker container for GitLab based on the nightly image:
+
+```shell
+docker run \
+  --publish 80:80 \
+  --name gitlab \
+  --hostname localhost \
+  gitlab/gitlab-ee:nightly
+```
+
+To run the tests from the `/qa` directory:
+
+```shell
+CHROME_HEADLESS=false bin/qa Test::Instance::All http://localhost -- qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb
+```
+
+The test will automatically spinup a docker container for Jenkins and tear down once the test completes.
+
+However, if you need to run Jenkins manually outside of the tests, use this command:
+
+```shell
+docker run \
+  --hostname localhost \
+  --name jenkins-server \
+  --env JENKINS_HOME=jenkins_home \
+  --publish 8080:8080 \
+  registry.gitlab.com/gitlab-org/gitlab-qa/jenkins-gitlab:version1
+```
+
+Jenkins will be available on `http://localhost:8080`.
+
+Admin username is `admin` and password is `password`.
+
+It is worth noting that this is not an orchestrated test. It is [tagged with the `:orchestrated` meta](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb#L5)
+only to prevent it from running in the pipelines for live environments such as Staging.
+
+### Troubleshooting
+
+If Jenkins docker container exits without providing any information in the logs, try increasing the memory used by
+the Docker Engine.

qa/README.md

@@ -44,6 +44,14 @@ Note: GitLab QA uses [Selenium WebDriver](https://www.seleniumhq.org/) via
 the browser to use. You will need to have Chrome (or Chromium) and
 [chromedriver](https://chromedriver.chromium.org/) installed / in your `$PATH`.
 
+### Writing tests
+
+- [Writing tests from scratch tutorial](../doc/development/testing_guide/end_to_end/quick_start_guide.md)
+    - [Best practices](../doc/development/testing_guide/best_practices.md)
+    - [Using page objects](../doc/development/testing_guide/end_to_end/page_objects.md)
+    - [Guidelines](../doc/development/testing_guide/index.md)
+    - [Tests with special setup for local environemnts](../doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md)
+
 ### Run the end-to-end tests in a local development environment
 
 Follow the GDK instructions to [prepare](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/prepare.md)
@@ -77,13 +85,6 @@ Once you have the license file you can export it as an environment variable and
 export EE_LICENSE=$(cat /path/to/gitlab_license)
 ```
 
-### Writing tests
-
-- [Writing tests from scratch tutorial](../doc/development/testing_guide/end_to_end/quick_start_guide.md)
-    - [Best practices](../doc/development/testing_guide/best_practices.md)
-    - [Using page objects](../doc/development/testing_guide/end_to_end/page_objects.md)
-    - [Guidelines](../doc/development/testing_guide/index.md)
-
 ### Running specific tests
 
 You can also supply specific tests to run as another parameter. For example, to