From 145d7aea3b4955bbbf66f477f92744f7131bd6d0 Mon Sep 17 00:00:00 2001
From: Alain Schlesser <alain.schlesser@gmail.com>
Date: Wed, 11 Dec 2024 11:57:48 +0100
Subject: [PATCH] Adapt the CONTRIBUTING.md file with the testing flow

---
 .github/CONTRIBUTING.md | 65 ++++++++++++++++++++++++++++++++---------
 1 file changed, 51 insertions(+), 14 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index f1ac8782f..e6b15b8eb 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -109,28 +109,65 @@ Code coverage is monitored for every PR and for the code base as a whole using [
 
 ### Running the Tests
 
+There are several ways to run the tests locally:
+
+#### 1. Using Composer Scripts (Recommended)
+
+The simplest way to run tests is using the Composer scripts:
+
+```bash
+# Run tests without coverage
+composer test
+
+# Run tests with coverage
+composer coverage
+
+# Run tests with automatic test server management
+composer test:withserver
+```
+
+#### 2. Manual Test Environment Management
+
+If you need more control over the test environment, you can manage it manually:
+
+```bash
+# Start all test servers and set environment variables
+# We need to source the script to properly set environment variables in our shell
+source scripts/start-test-environment.sh
+
+# Now run your tests
+composer test
+
+# When done, stop all servers
+./scripts/stop-test-environment.sh
+```
+
+Note: The environment scripts must be sourced (using `source` or `.`) to properly set environment variables in your shell.
+
+#### 3. Individual Component Control
+
+For debugging or development, you might want to manage individual components:
+
 ```bash
-# Start the test server
+# Just the test server
 PORT=8080 vendor/bin/start.sh
-export "REQUESTS_TEST_HOST_HTTP=localhost:8080"
+export REQUESTS_TEST_HOST_HTTP=localhost:8080
 
-# Start the proxy server
+# Just the proxy servers
 PORT=9002 tests/utils/proxy/start.sh
 PORT=9003 AUTH="test:pass" tests/utils/proxy/start.sh
-export "REQUESTS_HTTP_PROXY=localhost:9002"
-export "REQUESTS_HTTP_PROXY_AUTH=localhost:9003"
-export "REQUESTS_HTTP_PROXY_AUTH_USER=test"
-export "REQUESTS_HTTP_PROXY_AUTH_PASS=pass"
+export REQUESTS_HTTP_PROXY=localhost:9002
+export REQUESTS_HTTP_PROXY_AUTH=localhost:9003
+export REQUESTS_HTTP_PROXY_AUTH_USER=test
+export REQUESTS_HTTP_PROXY_AUTH_PASS=pass
+```
 
-# Run the tests
-composer test
+Remember to stop any servers you start:
 
-# Stop the proxy server
-PORT=9002 tests/utils/proxy/stop.sh
+```bash
+vendor/bin/stop.sh                   # Stop test server
+PORT=9002 tests/utils/proxy/stop.sh  # Stop proxy servers
 PORT=9003 tests/utils/proxy/stop.sh
-
-# Stop the test server
-vendor/bin/stop.sh
 ```
 
 To run the test with code coverage, use `composer coverage` instead.