📝 docs: add GODOG_RANDOM_SEED documentation to BDD_TAGS.md

features/BDD_TAGS.md

@@ -84,6 +84,43 @@ GODOG_TAGS="@jwt && ~@todo" go test ./features/...
 DLC_DATABASE_HOST=localhost GODOG_TAGS="@wip" go test ./features/jwt/...
 ```
 
+### Test Randomization Control
+You can control test execution order using the `GODOG_RANDOM_SEED` environment variable.
+
+**Usage:**
+```bash
+# Use random test order (default)
+GODOG_RANDOM_SEED="" go test ./features/
+
+# Use fixed seed for reproducible test runs
+GODOG_RANDOM_SEED=17925 go test ./features/
+
+# Combine with tag filtering
+GODOG_RANDOM_SEED=17925 GODOG_TAGS="@wip" go test ./features/
+
+# Debug specific test failures by reproducing exact execution order
+GODOG_RANDOM_SEED=17925 DLC_DATABASE_HOST=localhost go test ./features/jwt/
+```
+
+**Benefits:**
+- **Reproducibility**: Same seed produces same test order
+- **Debugging**: Easily reproduce failed test runs
+- **CI/CD**: Set fixed seeds for consistent test execution
+- **Backward compatible**: Defaults to random order when not specified
+
+**Example from test output:**
+```
+30 scenarios (11 passed, 19 failed)
+147 steps (104 passed, 19 failed, 24 skipped)
+4.474215346s
+Randomized with seed: 17925
+```
+
+To reproduce this exact test run:
+```bash
+GODOG_RANDOM_SEED=17925 go test ./features/
+```
+
 ### 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.

pkg/bdd/testsetup/testsetup.go

@@ -151,9 +151,9 @@ func CreateTestSuite(t *testing.T, config *FeatureConfig, suiteName string) godo
 	}
 
 	// Allow randomization seed override via environment variable
-	randomize := -1 // Default: randomize test order
+	randomize := int64(-1) // Default: randomize test order
 	if envSeed := os.Getenv("GODOG_RANDOM_SEED"); envSeed != "" {
-		if parsedSeed, err := strconv.Atoi(envSeed); err == nil {
+		if parsedSeed, err := strconv.ParseInt(envSeed, 10, 64); err == nil {
 			randomize = parsedSeed
 		}
 	}
@@ -204,9 +204,9 @@ func CreateMultiFeatureTestSuite(t *testing.T, config *MultiFeatureConfig, suite
 	}
 
 	// Allow randomization seed override via environment variable
-	randomize := -1 // Default: randomize test order
+	randomize := int64(-1) // Default: randomize test order
 	if envSeed := os.Getenv("GODOG_RANDOM_SEED"); envSeed != "" {
-		if parsedSeed, err := strconv.Atoi(envSeed); err == nil {
+		if parsedSeed, err := strconv.ParseInt(envSeed, 10, 64); err == nil {
 			randomize = parsedSeed
 		}
 	}