From 778d8822dc517c411248bf7244cd1fc9e2667b5c Mon Sep 17 00:00:00 2001
From: Gabriel Radureau <arcodange@gmail.com>
Date: Fri, 10 Apr 2026 14:36:43 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=80=20feat:=20make=20random=20ports=20?=
 =?UTF-8?q?default=20for=20BDD=20tests=20to=20prevent=20conflicts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 features/BDD_TAGS.md         | 66 ++++++++++++++++++++++++++++++++++++
 pkg/bdd/testserver/server.go |  5 +--
 2 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/features/BDD_TAGS.md b/features/BDD_TAGS.md
index cb6abf5..b6c3c2b 100644
--- a/features/BDD_TAGS.md
+++ b/features/BDD_TAGS.md
@@ -84,6 +84,72 @@ GODOG_TAGS="@jwt && ~@todo" go test ./features/...
 DLC_DATABASE_HOST=localhost GODOG_TAGS="@wip" go test ./features/jwt/...
 ```
 
+### Random Port Selection (Default Behavior)
+
+By default, BDD tests use **random ports** (10000-19999) to prevent port conflicts during parallel execution. This ensures tests can run reliably in CI/CD pipelines and when executed multiple times.
+
+**Benefits:**
+- ✅ No port conflicts in parallel test execution
+- ✅ Safe for repeated test runs
+- ✅ Better for CI/CD environments
+
+**Disable random ports (not recommended):**
+```bash
+FIXED_TEST_PORT=true go test ./features/...
+```
+
+**Force specific port (debugging only):**
+```bash
+# Create a test config file with fixed port
+echo "server:
+  port: 9191" > test-config.yaml
+FEATURE=debug FIXED_TEST_PORT=true go test ./features/...
+```
+
+### Test Validation Process
+
+To ensure test suite stability, follow this validation process:
+
+**Validation Command:**
+```bash
+# Clean cache and run all tests 20 times
+echo "🧪 Validating test suite stability..."
+for i in {1..20}; do
+    echo "Run $i/20..."
+    go clean -testcache
+    if ! go test ./... > /dev/null 2>&1; then
+        echo "❌ Test run $i failed"
+        go test ./... -v
+        exit 1
+    fi
+done
+echo "✅ All 20 test runs passed successfully!"
+```
+
+**Failure Handling:**
+- If any test fails during validation, mark it as `@wip` and investigate
+- Use `@flaky` tag for intermittently failing tests
+- Document the issue in the test scenario comments
+
+**Success Criteria:**
+- ✅ 100% pass rate across 20 consecutive runs
+- ✅ No undefined/pending steps
+- ✅ No race conditions or port conflicts
+- ✅ Consistent execution time
+
+**CI/CD Integration:**
+```yaml
+- name: Validate Test Suite
+  run: |
+    echo "🧪 Running 20 validation runs..."
+    for i in {1..20}; do
+      echo "Run $i/20"
+      go clean -testcache
+      go test ./... || exit 1
+    done
+    echo "✅ Test suite validated successfully"
+```
+
 ### Stop On Failure Control
 You can control whether tests stop on first failure using the `GODOG_STOP_ON_FAILURE` environment variable.
 
diff --git a/pkg/bdd/testserver/server.go b/pkg/bdd/testserver/server.go
index 7b5aabd..de3d4f9 100644
--- a/pkg/bdd/testserver/server.go
+++ b/pkg/bdd/testserver/server.go
@@ -36,8 +36,9 @@ func NewServer() *Server {
 	feature := os.Getenv("FEATURE")
 	port := 9191 // Default port
 
-	// Check for random port mode (better for parallel testing)
-	if os.Getenv("RANDOM_TEST_PORT") == "true" {
+	// Use random port by default for better parallel testing
+	// Can be disabled with FIXED_TEST_PORT=true if needed
+	if os.Getenv("FIXED_TEST_PORT") != "true" {
 		// Generate a random port in the test range (10000-19999)
 		port = 10000 + rand.Intn(9999)
 		log.Debug().Int("port", port).Msg("Using random test port")