Testing Guide¶

This covers how to test platform behavior — plan management, billing, onboarding, and MCP tools — without touching production accounts.

Principles¶

Never use a real user's org for plan mutation tests — use a designated test org
All admin API calls require an admin JWT — get one via the console or a test token
Never push to main without python3 -m compileall -q src/relay/ passing clean
Stripe test mode is the sandbox — use test card 4242 4242 4242 4242 for payment flows

Plan management — API test routines¶

Check an org's current plan¶

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://api.relayctx.com/api/admin/v1/orgs/{org_id} | jq '.org_billing'

Expected: { "tier": "beta"|"free"|"pro"|"grace", "stripe_customer_id": "...", ... }

Update org plan (admin)¶

curl -s -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": "pro"}' \
  https://api.relayctx.com/api/admin/v1/orgs/{org_id}/plan

Verify: re-check org billing, confirm Stripe customer subscription updated.

Trigger EAP graduation (Step 4 — once built)¶

curl -s -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://api.relayctx.com/api/admin/v1/orgs/{org_id}/graduate

Expected (card on file): tier → pro Expected (no card): tier → grace, grace_expires_at set

Verify Stripe ↔ platform sync¶

Change plan in console → verify org_billing.tier updated
Trigger Stripe webhook (via Stripe CLI): stripe trigger customer.subscription.updated → verify platform tier mirrors

Onboarding — test routines¶

Check onboarding status for a user¶

# User-facing
curl -s -H "Authorization: Bearer $USER_TOKEN" \
  https://api.relayctx.com/api/user/v1/onboarding/status

# Admin view
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://api.relayctx.com/api/admin/v1/users/{user_id}/onboarding

Expected: { "complete": true|false, "steps": [...] }

Restart onboarding (admin)¶

curl -s -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://api.relayctx.com/api/admin/v1/users/{user_id}/onboarding/restart

Finance — test routines¶

Trigger a live revenue snapshot¶

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://api.relayctx.com/api/admin/v1/finance/revenue/live

Returns live MRR/ARR from Stripe. Upserts into revenue_snapshots.

View recent transactions¶

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.relayctx.com/api/admin/v1/finance/transactions?limit=10"

View discount commitments¶

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://api.relayctx.com/api/admin/v1/finance/discounts/summary

EAP graduation test checklist¶

Before enabling graduation for a cohort:

[ ] Test org has tier='beta' confirmed
[ ] Run graduation endpoint with card-on-file org → verify tier='pro'
[ ] Run graduation endpoint with no-card org → verify tier='grace', grace_expires_at set
[ ] Confirm user notified in both cases (check notification log)
[ ] Set grace_expires_at to a past date → run sweep job manually → verify tier='free'
[ ] Confirm free downgrade notification sent
[ ] Verify Stripe subscription state matches in each case

Console testing harness (planned)¶

A dedicated admin console screen (/system/api-tests) will run these routines interactively:

Select a test org from a picker
Choose a routine (plan update, graduation, onboarding check, finance snapshot)
Execute and view structured response
Compare before/after state

Also planned: end-user test prompt — a configurable script that simulates a user signup → onboarding → relay send flow, reporting pass/fail per step.

MCP tool testing¶

Test MCP tools against a test org via any Claude client pointed at mcp.relayctx.com:

relay_pulse_active — check active pulse returns
relay_transfer_create — send a test transfer
relay_transfer_receive — receive it back
relay_search_saved — verify search indexes

Use the test org's API token. Never use a production user's token for automated tests.

Last updated: 2026-06-14