member-console/test/AGENTS.md

test/ — instructions for LLM agents

If you are an automated agent working in this repository, read this before starting Docker. The test stack uses fixed default host ports; multiple worktrees running it concurrently will collide unless each generates its own isolated configuration.

All commands in this doc assume your working directory is test/ — that's where compose, the env file, and the binary's expected secret paths all resolve from.

All credentials in the test stack are throwaway test-only values — the Keycloak admin/admin, seeded client secrets, database passwords, and generated .env secrets exist only for local development. Never reuse any of them in a real deployment.

Required first step in any worktree

cd test
./bootstrap-stack.sh

The script:

• Derives a slug from this worktree's directory name (override with ./test/bootstrap-stack.sh my-slug).
• Allocates a deterministic port slot via FNV-32(slug) % 200. Probes for collisions and advances if any candidate port is already bound on the host.
• Copies test/secrets/ from the main worktree if missing locally (this directory is gitignored, so fresh worktrees do not inherit it).
• Writes test/.env with COMPOSE_PROJECT_NAME, COMPOSE_PROFILES, host port assignments, and MC_* env vars that override test/mc-config.yaml via Viper.
• Prints the URL/port table the developer should use, and which integration profiles are active.
• Idempotent: re-running with test/.env already in place is a no-op that reprints the summary.

Which integrations the stack composes

The stack ships core only: Postgres, Valkey, Keycloak, Temporal. Every integration service is behind a compose profile named after it, and COMPOSE_PROFILES in test/.env is the knob that selects them:

Value	Composes
(empty, the default)	core services only
fedwiki	the wiki farm chain (fedwiki-init, fedwiki-render, fedwiki) and the Caddy TLS proxy on 443
discourse	the live forum, its Postgres, and its Redis
fedwiki,discourse	a full demo composition

Docker Compose reads the variable natively, so up, ps, and down all resolve the same composition without flags, and seed-stack.sh / teardown-stack.sh follow along automatically.

Composing is not configuring. Turning a profile on starts containers; the app still ignores that integration until you uncomment its MC_* block in the same test/.env. Both halves are needed for a FedWiki or Discourse flow.

Bake a composition in at generation time when you know you want it:

COMPOSE_PROFILES=fedwiki ./bootstrap-stack.sh

To change it later, edit the one COMPOSE_PROFILES line in test/.env and re-run docker compose up -d. This is the only hand-edit test/.env sanctions (see Constraints): re-running bootstrap would not pick up a change, and a teardown would drop the database.

After bootstrap

docker compose up -d
set -a; . .env; set +a
go run .. start --config mc-config.yaml

keycloak-seed (creates realm users) runs automatically as a one-shot on up. With the fedwiki profile selected, fedwiki-render does too (it resolves real KC UUIDs and templates seed/fedwiki/*.tpl into testdata/fedwiki/), and fedwiki waits for both to complete before starting. Keycloak silently regenerates the id field on POST /users, so FedWiki identity cannot be pinned at commit time — it's rendered after each realm seed.

The member-console binary must run with test/ as its working directory because mc-config.yaml references secrets/stripe-* via relative paths. Compose auto-loads .env from the current directory, so no -f/--env-file flags are needed.

Use the URLs printed by bootstrap, not the defaults from test/mc-config.yaml — the YAML still says port: 8081, but the running process listens on whatever MC_PORT is in test/.env.

Walking the operator UI with data

The default workflow produces a clean, empty environment — good for fresh-user flows. To populate the operator panel (products, plan ladder, entitlement set, one active grant) for UX walkthroughs or operator-panel exploration, run the opt-in demo seeder from the repo root after bootstrap-stack.sh:

./test/seed-demo.sh

Idempotent — re-running is a no-op. Person rows for bob/carlos/diana are not seeded (Keycloak doesn't honor pinned sub IDs); log in once as each demo user to populate them. See seed/member-console-demo/README.md for the catalog and rationale.

Running the Go test suite

make test        # from the repo root, with the stack up

That target runs test/reset-test-db.sh and then go test -count=1 -p 1 ./... with test/.env sourced. The reset drops, recreates, and migrates the tests' own databases, so every run starts from migrations only. -p 1 runs packages one at a time: several of them commit rows others read (an org type's default plan ladder, a provider's group mappings), and interleaving those makes roughly half of parallel runs fail somewhere. -count=1 is there because Go's test cache keys on code and environment, not database state, so after a reset a cached ok would describe a database that no longer exists. The whole suite takes about 26 seconds.

The stack's Postgres carries three databases:

Database	Who writes it	Env var
member_console	the running app, seeders, browser walkthroughs	MC_DB_DSN
member_console_test	every DB-backed package test	TEST_DATABASE_URL
member_console_e2e	test/e2e/plan-management	E2E_DATABASE_URL

The split is what makes the suite trustworthy, and each boundary earns its place. Tests are off the app database because a running member-console start executes boot reconcilers (domains backfill, orphaned-placement sweep, entitlement materialization) that adopt leftover test fixtures. The in-process e2e suite is off the package-test database because it commits an org type's default plan ladder, which internal/provisioning asserts the absence of. Both were live failure modes, not hypotheticals.

Running go test ./... directly still works, but skips both the reset and the serialization, so it is flaky by construction. Prefer make test, and reach for a bare go test ./<pkg> only when iterating on one package.

Migrating during the reset is deliberate. Each package calls db.RunMigrations itself and goose takes no advisory lock, so against a genuinely empty database a dozen parallel packages would race to create the same schemas. Pre-migrating makes each of those calls a no-op.

One caveat: ./... includes test/e2e/operator-walkthroughs, which drives a browser against the live app. Those skip wholesale when no app is listening (the common case for make test), but with an app up they run against the app database and need it seeded — see the next section. A walkthrough failure there is about that database's contents, not about the isolation the reset provides.

If reset-test-db.sh reports a missing key, test/.env predates the split: cd test && rm .env && ./bootstrap-stack.sh. Containers and volumes survive.

Browser walkthroughs (e2e) and stack age

test/e2e/operator-walkthroughs/ runs against whatever state the stack DB has accumulated, and adapts rather than assumes:

• Walkthroughs skip (never fail) when their environment or subject is missing — app down, a profile-gated integration service unreachable, no org with the state they need. A skip message always names the missing precondition, including which profile would supply it.
• State-dependent walkthroughs (e.g. grant-extend) scan for a valid subject instead of trusting listing order, so orgs left behind by other walkthroughs or purchase-flow testing can't poison a run.

Skips are honest but they are still coverage gaps: for a full-exercise run, respin first (make stack-fresh from the repo root, then boot the app and run ./test/seed-demo.sh). These walkthroughs drive the live app over a browser, so they legitimately read the app database and stay subject to its accumulated state; a respin is their freshness mechanism. The Go suite no longer needs one — make test resets its own databases.

Tearing down

./teardown-stack.sh

Brings the compose stack down with volumes, removes test/.env, test/secrets/, and test/testdata/. Returns the worktree to a clean state for the next experiment. It enumerates the profiles compose.yaml declares rather than reading COMPOSE_PROFILES, so gated services come down even if the knob was turned off after they started, and it reclaims ownership of root-owned runtime data (Postgres, Temporal, Caddy, Discourse's Postgres) through a short-lived container before deleting it.

Keycloak user seeding

seed/keycloak/seed-keycloak.sh creates users via POST /admin/realms/{realm}/partialImport, not POST /admin/realms/{realm}/users. Keycloak 26.x silently drops the id field on the latter (server-side ID assignment for least-privilege admin operations); partialImport preserves pinned IDs and is the supported escape hatch. See OpenSpec change 2026-05-11-keycloak-id-pinning-fix for the empirical confirmation and design rationale.

Temporal namespace

The compose stack sets SKIP_DEFAULT_NAMESPACE_CREATION=true on the temporal service, so a one-shot temporal-seed service registers the default namespace via the internal frontend on first up. If member-console fails with Namespace default is not found, the seed service didn't run yet — docker compose ... up -d temporal-seed and re-check docker compose ... logs temporal-seed.

Stripe webhook forwarding (local activation)

Stripe cannot POST to localhost, so subscription activation (the checkout.session.completed / customer.subscription.created → pool-provision path) only fires locally if you forward events:

stripe login                                              # one-time, interactive
stripe listen --forward-to localhost:$MC_PORT/webhooks/stripe

stripe listen prints a signing secret; test/secrets/stripe-webhook-secret must equal it. The app's restricted key (rk_) cannot run stripe listen (it lacks rak_stripecli_session_write), hence the stripe login session. Replay a past event with stripe events resend <evt_id>. Forwarding is account-global — see the parallel-stack constraint below.

The app's restricted key (rk_) must include read scope for Subscriptions (plus Customers and Prices). Subscription fulfillment refetches authoritative state from the Stripe API rather than trusting the webhook payload (OpenSpec change stripe-fulfillment-reconcile), so a missing read scope surfaces as a 403 during reconcile — not at checkout.

Constraints

• Do not run Stripe webhook scenarios in parallel across stacks. All stacks share the same Stripe test account via test/secrets/stripe-*. Webhook delivery to one stack is global to that account; running two stacks through webhook flows simultaneously gives undefined results.
• Do not edit test/.env by hand, with one exception: the COMPOSE_PROFILES line and the commented-out MC_FEDWIKI_* / MC_DISCOURSE_* opt-in blocks are meant to be edited in place. For anything else — ports above all — re-run bootstrap after deleting the file.
• Do not point TEST_DATABASE_URL or E2E_DATABASE_URL at the app database. That reinstates every pollution vector the split closes, and reset-test-db.sh refuses to drop member_console precisely so a mistake here fails loudly instead of destroying the running stack's data.
• Do not remove the ${VAR:-default} fallbacks from compose.yaml. They preserve the single-stack default workflow when no .env is present.
• The HTTPS farm (Caddy) binds host 443, so only one stack at a time can serve it — but only among stacks that select the fedwiki profile; a core-only stack binds nothing there. Browsers must reach FedWiki sites over HTTPS because wiki-security-social sets Secure cookies (see project_fedwiki_security_stack); member-console's admin API still uses plain HTTP on FEDWIKI_PORT (bearer token, no cookies), so provisioning is unaffected and parallel stacks still work for everything except browser login. Caddy serves a wildcard cert from its internal CA — for manual browsing, trust the root once: docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt. Override the port with FEDWIKI_HTTPS_PORT only if you also give member-console a matching site port (buildSiteURL emits no port).
• FedWiki OAuth needs Keycloak reachable at the same host:port from both the browser and the fedwiki container. config.json's oauth2_discoveryUrl is rendered to ${KC_HOSTNAME}:${KEYCLOAK_PORT} (browser-facing), and the fedwiki service gets extra_hosts: ${KC_HOSTNAME}:host-gateway so the container resolves that name to the host. Don't drop either half.

What bootstrap-stack.sh writes to test/.env

COMPOSE_PROJECT_NAME=<slug>
SLOT=<0..199>
COMPOSE_PROFILES=            # composition knob; empty = core stack only

POSTGRES_PORT, VALKEY_PORT, KEYCLOAK_PORT,
TEMPORAL_PORT, TEMPORAL_UI_PORT, FEDWIKI_PORT, DISCOURSE_PORT

KC_HOSTNAME, DISCOURSE_HOSTNAME, MC_BASE_URL, TEMPORAL_UI_URL

MC_PORT, MC_DB_DSN, MC_VALKEY_ADDR,
MC_OIDC_IDP_ISSUER_URL, MC_TEMPORAL_HOST,
MC_TEMPORAL_OAUTH_TOKEN_URL

#MC_FEDWIKI_*                # commented-out opt-in, see below
#MC_DISCOURSE_*              # commented-out opt-in, see below

TEST_DATABASE_URL, E2E_DATABASE_URL, POSTGRES_ADMIN_DSN

Compose reads the first three blocks. Viper reads the MC_* block via the existing SetEnvPrefix("MC") + AutomaticEnv() configuration in cmd/root.go. The last block is read by test/reset-test-db.sh and the Go test suites; POSTGRES_ADMIN_DSN points at the cluster's maintenance database, the only place a DROP DATABASE can run from.

Both integrations' MC_* blocks ship commented out. Each is a required-together config group (farm URL + admin token; forum base URL + API key file), so uncommenting half of one fails boot validation on purpose. Port assignments for both are always written, whether or not their profile is on — they are harmless when nothing consumes them, and it keeps flipping the knob a one-line edit.