From 98a3acee36b58ea7adc7f1bac27c6acffda39a03 Mon Sep 17 00:00:00 2001
From: Gabriel Radureau <arcodange@gmail.com>
Date: Fri, 10 Apr 2026 17:39:02 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20GODOG=5FRANDOM=5FS?=
 =?UTF-8?q?EED=20documentation=20to=20BDD=5FTAGS.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 features/BDD_TAGS.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/features/BDD_TAGS.md b/features/BDD_TAGS.md
index b6c3c2b..0212c70 100644
--- a/features/BDD_TAGS.md
+++ b/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.