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.