user-engine/docs/journey-test-suites.md

Automated journey acceptance

Run make test for all regression and layer checks, then make test-journeys for the role-based acceptance selection. Tests exercise WSGI routes, authorization, CSRF, persisted records, provider failure/retry and confirmation state. They do not send email or modify real directory users.

Examples:

make test-journeys JOURNEY_ARGS="--role user"
make test-journeys JOURNEY_ARGS="--role tenant_admin"
make test-journeys JOURNEY_ARGS="--role platform_admin"
make test-journeys JOURNEY_ARGS="--report /tmp/user-engine-journeys.json"
make test-journeys JOURNEY_ARGS="--require-complete"

The last command is deliberately a release-completeness gate: it fails while any journey still has an implementation or external acceptance gap. A local suite passing is distinct from all 29 journeys being complete. tests/journey-coverage.json contains every journey ID, executable test selectors, implementation status and named remaining work. In particular, OTP help tests do not claim provider OTP activation coverage. KeyCape's Go suite and NetKingdom's provider suite are separate owner checks.

CI .forgejo/workflows/journeys.yaml runs full regression and journey selection against the exact pushed commit, and prints the JSON report. All fake identities, provider failure controls and test sessions live in tests, not production routes.

Tenant lifecycle and role changes hold an in-memory lock or tenant-scoped PostgreSQL advisory lock across provider calls and local mutation. Tests cover concurrent administrator suspension with independent database connections, lock release on exception and preservation of caller transactions. Nested first-admin bootstrap transactions roll back all local records after a failure. Directory changes and local state still are not one database transaction: desired-state retry/readback is required after a crash between external success and local save.

make test-browser-journeys starts a loopback-only synthetic portal and isolated Chromium profile, then drives user/admin/operator navigation and confirmation with Node's native CDP client. Set JOURNEY_CHROME if Chromium cannot be found. Missing browser dependencies fail explicitly; no test login endpoints are added to the production application. The ordinary CI job runs the WSGI suites; the browser command can also run on a runner provisioned with Node and Chromium.

Database suite: tests/test_journey_postgres.py uses the existing USER_ENGINE_POSTGRES_TEST_DSN plus USER_ENGINE_POSTGRES_TEST_RESET=1 contract. Use only a disposable database: conformance tests reset user-engine tables. The 2026-09-13 run used a fresh local Docker PostgreSQL container and completed all 210 regression tests with zero skips. The normal dependency-free run skips seven opt-in PostgreSQL tests. See the rollout evidence for exact commands.