feat: Add optional VSCode integration (#499)

Document explains how to make it possible to run our envtest-based tests
using VSCode.

Author: dlipovetsky

Makefile

@@ -337,13 +337,21 @@ mocks: ## Generate mocks for the project
 
 GOTESTPKGS = $(shell go list ./... | grep -v /mocks | grep -v /templates)
 
+KUBEBUILDER_ASSETS=$(shell setup-envtest use --print path $(ENVTEST_K8S_VERSION) --arch=amd64)
+
+.PHONY: print-envtest
+print-envtest: ## Set up envtest (download kubebuilder assets)
+	@echo KUBEBUILDER_ASSETS=$(KUBEBUILDER_ASSETS)
+
 .PHONY: unit-test
 unit-test: mocks  ## Run unit tests.
-	KUBEBUILDER_ASSETS="$(shell setup-envtest use $(ENVTEST_K8S_VERSION)  --arch=amd64 -p path)" $(GOTEST) $(GOTESTPKGS)
+	KUBEBUILDER_ASSETS="$(KUBEBUILDER_ASSETS)" \
+	$(GOTEST) $(GOTESTPKGS)
 
 .PHONY: coverage
 coverage: mocks ## Run the tests of the project and export the coverage
-	KUBEBUILDER_ASSETS="$(shell setup-envtest use $(ENVTEST_K8S_VERSION)  --arch=amd64 -p path)" $(GOTEST) -race -coverprofile=coverage.out -covermode=atomic $(GOTESTPKGS)
+	KUBEBUILDER_ASSETS="$(KUBEBUILDER_ASSETS)" \
+	$(GOTEST) -race -coverprofile=coverage.out -covermode=atomic $(GOTESTPKGS)
 
 .PHONY: template-test
 template-test: docker-build prepare-local-clusterctl ## Run the template tests

docs/vscode-integration/README.md

@@ -0,0 +1,13 @@
+# VSCode Integration
+
+Some of the unit tests use the [envtest package](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest) from the controller-runtime project to create a temporary Kubernetes API server.
+
+Envtest reads the location of the necessary binaries, i.e. etcd and kube-apiserver, from an environment variable. This environment variable is initialized by our make targets, but VSCode does not run tests using make.
+
+We can use a VSCode task to write the location to a file, and configure vscode-go, which runs the tests, to initialize its environment from this file.
+
+To run envtest-based tests from VSCode, follow these steps:
+
+1. Install setup-envtest (and other build/test dependencies) by running `devbox install`.
+2. Copy `settings.json` and `tasks.json` in this directory into the `.vscode` folder at the root of the repository.
+3. Restart VSCode.

docs/vscode-integration/settings.json

@@ -0,0 +1,3 @@
+{
+    "go.testEnvFile": "${workspaceFolder}/.vscode/test.env"
+}

docs/vscode-integration/tasks.json

@@ -0,0 +1,32 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "type": "shell",
+            "label": "Prepare vscode to run envtest-based tests",
+            "detail": "Install envtest and configure the vscode-go test environment.",
+            "group": {
+                "kind": "test",
+                "isDefault": true
+            },
+            "command": [
+                "echo $(make print-envtest) > ${workspaceFolder}/.vscode/test.env",
+            ],
+            "presentation": {
+                "echo": true,
+                "reveal": "silent",
+                "focus": false,
+                "panel": "shared",
+                "showReuseMessage": false,
+                "clear": false
+            },
+            "runOptions": {
+                "runOn": "folderOpen",
+                "instanceLimit": 1,
+            },
+            "promptOnClose": true,
+        }
+    ]
+}