|
| 1 | +# Remote Debugging Integration Tests |
| 2 | + |
| 3 | +- [Introduction](#introduction) |
| 4 | + - [How it works](#how-it-works) |
| 5 | +- [Getting Started](#getting-started) |
| 6 | + - [Prerequisites](#prerequisites) |
| 7 | + - [Running Upgrade integration tests](#debugging-integration-tests) |
| 8 | + - [Building images](#building-images) |
| 9 | + - [Remote debugging using GoLand](#remote-debugging-using-goland) |
| 10 | + |
| 11 | + |
| 12 | +## Introduction |
| 13 | + |
| 14 | +Remote debugging integration tests allows you to attach your debugger to the consul container and debug go code running on that container. |
| 15 | + |
| 16 | +### How it works |
| 17 | +The `dev-docker-dbg` Make target will build consul docker container that has the following: |
| 18 | +- [delve (dlv) debugger](https://github.com/go-delve/delve) installed. |
| 19 | +- a port exposed on the container that allows a debugger from your development environment to connect and attach to the consul process and debug it remotely. |
| 20 | +- logs out the host and port information so that you have the information needed to connect to the port. |
| 21 | + |
| 22 | +The integration tests have been modified to expose the `--debug` flag that will switch the test from using a `consul:local` image that can be built using `make dev-docker` to using the `consul-dbg:local` image that was build from `make dev-docker-dbg`. |
| 23 | + |
| 24 | +The test is run in debug mode with a breakpoint set to just after the cluster is created and you can retrieve the port information. From there, you can set up a remote debugging session that connects to this port. |
| 25 | + |
| 26 | +## Getting Started |
| 27 | +### Prerequisites |
| 28 | +To run/debug integration tests locally, the following tools are required on your machine: |
| 29 | +- Install [Go](https://go.dev/) (the version should match that of our CI config's Go image). |
| 30 | +- Install [`Makefile`](https://www.gnu.org/software/make/manual/make.html). |
| 31 | +- Install [`Docker`](https://docs.docker.com/get-docker/) required to run tests locally. |
| 32 | + |
| 33 | +### Debugging integration tests |
| 34 | +#### Building images |
| 35 | +- Build a consul image with dlv installed and a port exposed that the debugger can attach to. |
| 36 | + ``` |
| 37 | + make dev-docker-dbg |
| 38 | + ``` |
| 39 | +- Build a consul-envoy container image from the consul root directory that is required for testing but not for debugging. |
| 40 | + ``` |
| 41 | + docker build consul-envoy:target-version --build-arg CONSUL_IMAGE=consul:local --build-arg ENVOY_VERSION=1.24.6 -f ./test/integration/consul-container/assets/Dockerfile-consul-envoy ./test/integration/consul-container/assets |
| 42 | + ``` |
| 43 | + |
| 44 | +#### Remote debugging using GoLand |
| 45 | +(For additional information, see [GoLand's documentation on remote debugging](https://www.jetbrains.com/help/go/attach-to-running-go-processes-with-debugger.html#attach-to-a-process-on-a-remote-machine).) |
| 46 | +##### Set up the Debug Configuration for your test |
| 47 | +- Create the configuration for debugging the test. (You may have to debug the test once so GoLand creates the configuration for you.) |
| 48 | +- Go to `Run > Edit Configurations` and select the appropriate configuration. |
| 49 | +- Add `--debug` to `Program arguments` and click OK. |
| 50 | + |
| 51 | + <img src="./util/test_debug_configuration.png" alt="isolated" width="550"/> |
| 52 | +##### Obtain the debug port of your container |
| 53 | +(This is required every time a test is debugged.) |
| 54 | + |
| 55 | +- Put a breakpoint in the test that you are running right after the cluster has been created. This should be on the line after the call to `topology.NewCluster()`. |
| 56 | +- Debug the test and wait for the debug session to stop on the breakpoint in the test. |
| 57 | +- In the Debug window, search for `debug info` on the Console tab and note the host and port. |
| 58 | + |
| 59 | + <img src="./util/test_debug_info.png" alt="isolated" width="550"/> |
| 60 | +- Go to `Run > Edit Configurations` and add a `Go Remote` configuration with the host and port that your test has exposed. Click OK. |
| 61 | + |
| 62 | + <img src="./util/test_debug_remote_configuration.png" alt="isolated" width="550"/> |
| 63 | +- Debug the configuration that you just created. Verify that it shows as connected in the `Debugger` of this configuration in the `Debug` window. |
| 64 | + |
| 65 | + <img src="./util/test_debug_remote_connected.png" alt="isolated" width="550"/> |
| 66 | +##### Debug the consul backend |
| 67 | +- Set an appropriate breakpoint in the backend code of the endpoint that your test will call and that you wish to debug. |
| 68 | +- Go to the test debugging tab for the integration test in the `Debug` window and `Resume Program`. |
| 69 | + |
| 70 | + <img src="./util/test_debug_resume_program.png" alt="isolated" width="350"/> |
| 71 | +- The remote debugging session should stop on the breakpoint, and you can freely debug the code path. |
| 72 | + |
| 73 | + <img src="./util/test_debug_breakpoint_hit.png" alt="isolated" width="550"/> |
| 74 | + |
| 75 | +#### Remote debugging using VSCode |
| 76 | +(For additional information, see [VSCode's documentation on remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging).) |
| 77 | + |
| 78 | +[comment]: <> (TODO: Openly looking for someone to add VSCode specific instructions.) |
0 commit comments