📝 docs: homogenize API + BDD env docs (verifier skill audit) (#36)

Co-authored-by: Gabriel Radureau <arcodange@gmail.com> Co-committed-by: Gabriel Radureau <arcodange@gmail.com>
2026-05-04 07:53:31 +02:00
parent 82feaec51f
commit 75ae7e3c17
2 changed files with 179 additions and 0 deletions
--- a/documentation/BDD_TEST_ENV.md
+++ b/documentation/BDD_TEST_ENV.md
@@ -0,0 +1,89 @@
+# BDD test environment
+
+Environment variables and tooling specific to running BDD scenarios locally and in CI. Companion to [BDD_GUIDE.md](BDD_GUIDE.md) (which covers the BDD authoring workflow itself).
+
+## Required env vars (database connection)
+
+The BDD test server needs a Postgres instance reachable via:
+
+| Var | Default | Notes |
+|---|---|---|
+| `DLC_DATABASE_HOST` | `localhost` | Host of the Postgres instance |
+| `DLC_DATABASE_PORT` | `5432` | |
+| `DLC_DATABASE_USER` | `postgres` | Test-only credentials (NOT production) |
+| `DLC_DATABASE_PASSWORD` | `postgres` | |
+| `DLC_DATABASE_NAME` | `dance_lessons_coach_bdd_test` | Dedicated test DB |
+| `DLC_DATABASE_SSL_MODE` | `disable` | Tests run without TLS |
+
+Local setup:
+
+```bash
+docker compose up -d                                                # Postgres container
+docker exec dance-lessons-coach-postgres psql -U postgres \
+  -c "CREATE DATABASE dance_lessons_coach_bdd_test;"               # one-time
+```
+
+In CI: `.gitea/workflows/ci-cd.yaml` provisions a Postgres service container and exports the same vars.
+
+## Optional env vars
+
+### `BDD_SCHEMA_ISOLATION` (since [PR #35](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/35) — T12 stage 2/2)
+
+| Value | Behaviour |
+|---|---|
+| `true` | Each test PACKAGE (process) gets its own isolated PostgreSQL schema with migrations. Packages run in **parallel** safely. **~2.85x speedup observed locally.** This is the new default in CI. |
+| (unset / `false`) | Falls back to single shared `public` schema with `CleanupDatabase` (TRUNCATE) between scenarios. Forces sequential package execution (`-p 1`). Slower but simpler. |
+
+Implementation: `pkg/bdd/testserver/server.go Start()` builds a per-package isolated repo via `user.NewPostgresRepositoryFromDSN` (PR #34). `Stop()` drops the schema + closes the per-package pool.
+
+ADR-0025 documents the isolation strategy ("Implemented" since PR #35).
+
+### `FEATURE` (per-package selector)
+
+When set, `pkg/bdd/testserver/server.go shouldEnableV2()` reads it. Used to scope per-feature behaviour (e.g. enable v2 endpoints only when `FEATURE=greet` AND `GODOG_TAGS` includes `@v2`).
+
+Without `FEATURE` set, falls back to `bdd` (generic).
+
+### `GODOG_TAGS` (scenario filter)
+
+Standard godog env var. The default suite excludes flaky/todo/skip/v2 tags:
+```
+GODOG_TAGS="~@flaky && ~@todo && ~@skip && ~@v2"
+```
+
+Scoped runs (e.g. `@critical` only): set `GODOG_TAGS="@critical"` and run.
+
+### `BDD_ENABLE_CLEANUP_LOGS` (debug)
+
+Set `=true` to log each scenario's CLEANUP / ISOLATION operation. Useful when debugging flakiness.
+
+## Recommended local commands
+
+Run all BDD with isolation (parallel, fast):
+```bash
+DLC_DATABASE_HOST=localhost DLC_DATABASE_PORT=5432 \
+DLC_DATABASE_USER=postgres DLC_DATABASE_PASSWORD=postgres \
+DLC_DATABASE_NAME=dance_lessons_coach_bdd_test DLC_DATABASE_SSL_MODE=disable \
+BDD_SCHEMA_ISOLATION=true \
+go test ./features/...
+```
+
+Run one feature with v2 enabled:
+```bash
+DLC_DATABASE_HOST=... \
+BDD_SCHEMA_ISOLATION=true FEATURE=greet GODOG_TAGS="@v2" \
+go test ./features/greet/...
+```
+
+Repro CI conditions (sequential, no isolation):
+```bash
+DLC_DATABASE_HOST=... \
+go test ./features/... -p 1
+```
+
+## Cross-references
+
+- [BDD_GUIDE.md](BDD_GUIDE.md) — authoring scenarios + steps
+- [ADR-0008](../adr/0008-bdd-testing.md) — choice of Godog
+- [ADR-0024](../adr/0024-bdd-test-organization-and-isolation.md) — feature directory organization
+- [ADR-0025](../adr/0025-bdd-scenario-isolation-strategies.md) — isolation strategies (Implemented since PR #35)