golfgame/docs/soak-harness-bringup.md

Soak Harness Bring-Up

One-time setup steps before running tests/soak against an environment.

Prerequisites

• An invite code exists with 16+ available uses
• You have psql access to the target DB (or admin SQL access via some other means)

1. Flag the invite code as test-seed

Any account registered with a marks_as_test=TRUE invite code gets users_v2.is_test_account=TRUE, which keeps it out of real-user stats.

Staging

Invite code: 5VC2MCCN (16 uses, provisioned 2026-04-10).

UPDATE invite_codes SET marks_as_test = TRUE WHERE code = '5VC2MCCN';
SELECT code, max_uses, use_count, marks_as_test FROM invite_codes WHERE code = '5VC2MCCN';

Expected: marks_as_test | t.

From your workstation:

ssh root@129.212.150.189 \
  'docker compose -f /opt/golfgame/docker-compose.staging.yml exec -T postgres psql -U postgres -d golfgame' <<'SQL'
UPDATE invite_codes SET marks_as_test = TRUE WHERE code = '5VC2MCCN';
SELECT code, max_uses, use_count, marks_as_test FROM invite_codes WHERE code = '5VC2MCCN';
SQL

Production

Invite code — to be provisioned when production seeding is needed. Same pattern:

ssh root@165.245.152.51 \
  'docker compose -f /opt/golfgame/docker-compose.prod.yml exec -T postgres psql -U postgres -d golfgame' <<'SQL'
UPDATE invite_codes SET marks_as_test = TRUE WHERE code = '<PROD_INVITE_CODE>';
SQL

Local dev

The local dev environment uses the SOAKTEST invite code. Create it once (if you wiped the DB since the last run):

INSERT INTO invite_codes (code, created_by, expires_at, max_uses, is_active, marks_as_test)
SELECT 'SOAKTEST', id, NOW() + INTERVAL '10 years', 100, TRUE, TRUE
FROM users_v2 LIMIT 1
ON CONFLICT (code) DO UPDATE SET marks_as_test = TRUE;

Note: created_by references any existing user (the FK doesn't require admin role). If your dev DB has zero users, register one first via the UI or curl.

Connection string for local dev:

PGPASSWORD=devpassword psql -h localhost -U golf -d golf

2. Verify the schema migrations applied

The server-side changes (columns, matview rebuild, stats filter) run automatically on server startup via SCHEMA_SQL in server/stores/user_store.py. After the server-side changes deploy, verify against each target environment:

-- All four should return matching rows
\d users_v2           -- look for is_test_account column
\d invite_codes       -- look for marks_as_test column
\d leaderboard_overall -- look for is_test_account column
\di idx_users_test_account

If leaderboard_overall doesn't show the new column, the matview rebuild didn't run. Check server startup logs for errors around initialize_schema.

3. Run the harness

Once the harness is built (Tasks 9+ of the implementation plan):

cd tests/soak
npm install

# First run only: seed 16 accounts via the invite code
TEST_URL=https://staging.adlee.work SOAK_INVITE_CODE=5VC2MCCN npm run seed

# Smoke test against local dev
TEST_URL=http://localhost:8000 SOAK_INVITE_CODE=SOAKTEST npm run smoke

# Populate staging scoreboard
TEST_URL=https://staging.adlee.work SOAK_INVITE_CODE=5VC2MCCN npm run soak:populate

# Stress test
TEST_URL=https://staging.adlee.work SOAK_INVITE_CODE=5VC2MCCN npm run soak:stress

See tests/soak/README.md for the full flag reference.

4. Verify test account filtering works end-to-end

After a soak run, the soak-seeded accounts should be visible to admins but hidden from public stats:

# Should return no soak_* usernames (test accounts hidden by default)
curl -s "https://staging.adlee.work/api/stats/leaderboard?metric=wins" | jq '.entries[] | select(.username | startswith("soak_"))'

# Should return the soak_* accounts when explicitly requested
curl -s "https://staging.adlee.work/api/stats/leaderboard?metric=wins&include_test=true" | jq '.entries[] | select(.username | startswith("soak_"))'

In the admin panel:

• Users tab shows a [Test] badge next to soak accounts
• Invite codes tab shows [Test-seed] next to the flagged code
• "Include test accounts" checkbox (default checked) toggles visibility