🚀 feat: implement random port selection for BDD tests to prevent conflicts

pkg/bdd/suite.go

@@ -1,6 +1,10 @@
 package bdd
 
 import (
+	"fmt"
+	"strings"
+	"time"
+
 	"dance-lessons-coach/pkg/bdd/steps"
 	"dance-lessons-coach/pkg/bdd/testserver"
 
@@ -12,9 +16,16 @@ var sharedServer *testserver.Server
 
 func InitializeTestSuite(ctx *godog.TestSuiteContext) {
 	ctx.BeforeSuite(func() {
+		// Small delay to ensure any previous server instances are fully cleaned up
+		time.Sleep(50 * time.Millisecond)
+
 		sharedServer = testserver.NewServer()
 		if err := sharedServer.Start(); err != nil {
-			panic(err)
+			// Improved error message for port conflicts
+			if strings.Contains(err.Error(), "address already in use") {
+				panic(fmt.Sprintf("Port conflict: %v. Try running 'lsof -i :9191' and 'kill -9 <PID>' to free the port", err))
+			}
+			panic(fmt.Sprintf("Failed to start test server: %v", err))
 		}
 	})
 
@@ -28,7 +39,12 @@ func InitializeTestSuite(ctx *godog.TestSuiteContext) {
 			if err := sharedServer.CloseDatabase(); err != nil {
 				log.Warn().Err(err).Msg("Failed to close database connection")
 			}
-			sharedServer.Stop()
+			// Shutdown HTTP server gracefully
+			if err := sharedServer.Stop(); err != nil {
+				log.Warn().Err(err).Msg("Failed to shutdown HTTP server")
+			}
+			// Small delay to ensure port is fully released
+			time.Sleep(100 * time.Millisecond)
 		}
 		// Cleanup any test config files
 		steps.CleanupAllTestConfigFiles()

pkg/bdd/testserver/server.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"math/rand"
 	"net/http"
 	"os"
 	"strconv"
@@ -25,12 +26,22 @@ type Server struct {
 	db         *sql.DB
 }
 
+func init() {
+	// Seed the random number generator for random port selection
+	rand.Seed(time.Now().UnixNano())
+}
+
 func NewServer() *Server {
 	// Get feature-specific port from configuration
 	feature := os.Getenv("FEATURE")
 	port := 9191 // Default port
 
-	if feature != "" {
+	// Check for random port mode (better for parallel testing)
+	if os.Getenv("RANDOM_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")
+	} else if feature != "" {
 		// Try to read port from feature-specific config
 		configPath := fmt.Sprintf("features/%s/%s-test-config.yaml", feature, feature)
 		if _, statErr := os.Stat(configPath); statErr == nil {