dance-lessons-coach/documentation/BDD_TEST_ENV.md

BDD test environment

Environment variables and tooling specific to running BDD scenarios locally and in CI. Companion to 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:

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 — 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):

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:

DLC_DATABASE_HOST=... \
BDD_SCHEMA_ISOLATION=true FEATURE=greet GODOG_TAGS="@v2" \
go test ./features/greet/...

Repro CI conditions (sequential, no isolation):

DLC_DATABASE_HOST=... \
go test ./features/... -p 1

Cross-references

• BDD_GUIDE.md — authoring scenarios + steps
• ADR-0008 — choice of Godog
• ADR-0024 — feature directory organization
• ADR-0025 — isolation strategies (Implemented since PR #35)