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.