From f734f53a61864308776d463df6f7fee921c7a46a Mon Sep 17 00:00:00 2001
From: Stefan Bueringer <sbueringer@gmail.com>
Date: Mon, 17 May 2021 18:04:32 +0200
Subject: [PATCH] doc: add local e2e test execution documentation

---
 docs/book/src/developer/e2e.md | 59 ++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/book/src/developer/e2e.md b/docs/book/src/developer/e2e.md
index 7ea8647495b2..747856c05b1c 100644
--- a/docs/book/src/developer/e2e.md
+++ b/docs/book/src/developer/e2e.md
@@ -198,6 +198,65 @@ long term success of the project.
 The [test E2E package] provides examples of how this can be achieved by implementing a set of reusable
 test specs for the most common Cluster API use cases.
 
+## Running the e2e tests locally
+
+Usually, the e2e tests are executed by Prow either pre-submit (on PRs) or periodically on certain branches 
+(e.g. the default branch). Those jobs are defined in the kubernetes/test-infra repository in [config/jobs/kubernetes-sigs/cluster-api](https://github.com/kubernetes/test-infra/tree/master/config/jobs/kubernetes-sigs/cluster-api). For development and debugging 
+those tests can also be executed locally. 
+
+### Via command line
+
+To run the tests locally via command line we can just take a look at the Job configuration and execute the same locally. 
+For example to run [pull-cluster-api-e2e-main](https://github.com/kubernetes/test-infra/blob/49ab08a6a2a17377d52a11212e6f1104c3e87bfc/config/jobs/kubernetes-sigs/cluster-api/cluster-api-presubmits-main.yaml#L113-L140) just execute:
+
+```bash
+GINKGO_FOCUS="\[PR-Blocking\]" ./scripts/ci-e2e.sh
+```
+
+### Via IDE
+
+It's also possible to run the tests via an IDE which makes it easier to debug the test code by stepping through the code.
+
+First, we have to make sure all prerequisites are fulfilled, i.e. all required images have been built. This can be done
+by executing the `ci-e2e.sh` script.
+
+```bash
+# Notes:
+# * you can cancel the script as soon as it started the actual test execution in `make -C test/e2e/ run`
+# * if you want to run other tests, make sure you set all required environment variables (see the Prow Job config) 
+GINKGO_FOCUS="\[PR-Blocking\]" ./scripts/ci-e2e.sh
+
+# Make sure the cluster-template have been generated
+make -C test/e2e cluster-templates
+```
+
+Now, the tests can be run in an IDE. The following describes how this can be done in Intellij IDEA. It should work 
+roughly the same way in VS Code and other IDEs. We assume the `cluster-api` repository has been checked 
+out into `/home/user/code/src/sigs.k8s.io/cluster-api`.
+
+Create a new run configuration and fill in:
+* Test framework: `gotest`
+* Test kind: `Package`
+* Package path: `sigs.k8s.io/cluster-api/test/e2e`
+* Pattern: `^\QTestE2E\E$`
+* Working directory: `/home/user/code/src/sigs.k8s.io/cluster-api/test/e2e`
+* Environment: `ARTIFACTS=/home/user/code/src/sigs.k8s.io/cluster-api/_artifacts`
+* Program arguments: `-e2e.config=/home/user/code/src/sigs.k8s.io/cluster-api/test/e2e/config/docker.yaml -ginkgo.focus="\[PR-Blocking\]" `
+
+Execute the run configuration with `Debug`.
+
+<aside class="note">
+
+<h1>Tips</h1>
+
+You can run other tests by changing `-ginkgo-focus`. You can also customize the test execution by setting additional 
+environment variables (see `docker.yaml`).
+
+If you want to debug CAPI controller during e2e tests, just scale down the controller in the local kind cluster 
+and run it via the IDE. 
+
+</aside>
+
 <!-- links -->
 [Cluster API quick start]: https://cluster-api.sigs.k8s.io/user/quick-start.html
 [Cluster API test framework]: https://pkg.go.dev/sigs.k8s.io/cluster-api/test/framework?tab=doc