From 9efa302167c36e36fed349074b06032175cb5706 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Vall=C3=A9s?=
 <3977183+jvallesm@users.noreply.github.com>
Date: Tue, 10 Sep 2024 15:34:32 +0200
Subject: [PATCH] chore(test): document DB_HOST and TEST_DBHOST variables
 (#646)

Because

- The names of these variables are similar but they have different uses
(coverage vs integration tests).

This commit

- Documents such variables.
---
 .env                    |  6 ++++++
 .github/CONTRIBUTING.md | 24 +++++++++++++++++++++++-
 Makefile                |  2 ++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/.env b/.env
index 5b1a04497..e152f994b 100644
--- a/.env
+++ b/.env
@@ -13,5 +13,11 @@ DOCKER_BUILDKIT=1
 COMPOSE_DOCKER_CLI_BUILD=1
 
 # test
+
+# TEST_DBHOST and TEST_DBNAME are used to initialize a separate database for
+# coverage tests. In general, test queries will be run within a transaction
+# that will be rolled back on cleanup, but there might be cases where this
+# isn't possible (e.g. lock tests). We want to keep these queries isolated from
+# the main database.
 TEST_DBHOST=localhost
 TEST_DBNAME=pipeline_test
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index daf9b694f..14b23b300 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -67,13 +67,35 @@ $ docker exec -it pipeline-backend /bin/bash
 $ go run ./cmd/worker
 ```
 
+### Run the unit tests
+
+```bash
+$ make coverate DBTEST=true
+```
+
+The repository tests in `make coverage` run against a real database (in contrast
+to a mocked one) in order to increase the confidence of the tests. `DBTEST=true`
+will create and migrate a test database to keep these queries isolated from the
+main DB. You can set the database host and name by overriding the `TEST_DBHOST`
+and `TEST_DBNAME` values.
+
 ### Run the integration test
 
 ```bash
 $ docker exec -it pipeline-backend /bin/bash
-$ make integration-test
+$ make integration-test API_GATEWAY_URL=api-gateway:8080 DB_HOST=pg-sql
 ```
 
+`API_GATEWAY_URL` points to the `api-gateway` container and triggers the public
+API tests. If this variable is empty, the private API tests will be run.
+
+At the end of the tests, some SQL queries are run to clean up the data.
+`DB_HOST` points to the database host so the SQL connection can be established.
+If empty, tests will try to connect to `localhost:5432`.
+
+```bash
+$ make integration-test API_GATEWAY_URL=api-gateway:8080 DB_HOST=pg-sql
+`
 ### Stop the dev container
 
 ```bash
diff --git a/Makefile b/Makefile
index 724e67ddc..816707032 100644
--- a/Makefile
+++ b/Makefile
@@ -96,6 +96,8 @@ coverage:
 
 .PHONY: integration-test
 integration-test:				## Run integration test
+	@ # DB_HOST points to localhost by default. Override this variable if
+	@ # pipeline-backend's database isn't accessible at that host.
 	@TEST_FOLDER_ABS_PATH=${PWD} k6 run \
 		-e API_GATEWAY_PROTOCOL=${API_GATEWAY_PROTOCOL} \
 		-e API_GATEWAY_URL=${API_GATEWAY_URL} \