# 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)